Sign-in

Umpteenth has no passwords, so you sign in with a passkey, through an OpenID Connect identity provider, or with a GitHub account. Passkeys work without any setup. Each identity provider or GitHub app is a provider under auth.providers in config.yml, and the login page shows a button for each one next to Sign in with a passkey. Every option also takes an environment variable, such as AUTH_PROVIDERS_GITHUB_CLIENT_SECRET, and Configuration lists them all.

To start without hosting anything else, use passkeys, which your password manager, phone or security key keeps.
If you run an identity provider such as Pocket ID or Authentik connect it through OpenID Connect, so it decides who gets in.
If your team lives on GitHub, sign in with GitHub and list the accounts or organizations that may.

Passkeys and providers work side by side, as Several providers shows.

Passkeys

A passkey account belongs to Umpteenth itself, with a name and an optional email address that you keep up to date yourself. Your browser creates the passkey and binds it to the host of app.url, so open Umpteenth at that address, over HTTPS or at localhost. Browsers refuse passkeys on plain HTTP anywhere else, and on an IP address such as http://192.168.1.10:8080.

The first account

Until anyone has an account, the login page reads Set up Umpteenth. Enter a Name and an Email, which can stay empty, and click Create account with a passkey. Your browser asks where to save the passkey, and you land on the dashboard as an instance admin who owns the workspace.

The first sign-in through a provider closes the setup too, since the instance has a user from then on.

Add people

After the first account, people get a passkey account in one of two ways:

An instance admin clicks Add user under Admin → Users, enters a Name and an Email, which can stay empty, and ticks Instance admin for another admin. Umpteenth shows a sign-in link once, which signs the person in a single time within 24 hours. They land on their Account page, where Add passkey creates the passkey they sign in with from then on.
With workspaces on, an invite link takes someone without an account to the login page, where Create an account creates a passkey account that joins the workspace.

An address an admin types into Add user counts as verified, so email invites to it reach the account. Addresses people enter themselves don’t, so invite them with a link. Anyone else who tries to sign up gets “Ask an instance admin for an account, or for an invite to a workspace”.

Manage passkeys

Open Account in the account menu at the top right to change your name and email address and to manage your passkeys. Add one per device or password manager with Add passkey, and give it a clearer name with Rename in its ⋯ menu. Remove deletes a passkey, and your last one stays, so you never lock yourself out.

If someone loses every passkey, an instance admin clicks Create sign-in link in that user’s ⋯ menu under Admin → Users and sends them the new link. A new link replaces the ones before it.

OpenID Connect

Setting	Value
Redirect URI	`<app.url>/api/auth/callback/<id>`, such as `https://umpteenth.example.com/api/auth/callback/pocket-id`
Scopes	`openid profile email groups`
Client type	Confidential or public, since Umpteenth uses PKCE either way

<id> is the key you give the provider under auth.providers in the next step, made of lowercase letters, digits and single hyphens. Note the issuer URL, the client ID and, for a confidential client, the client secret.

Add the provider to config.yml under its ID, with the type oidc.

auth:
  providers:
    pocket-id:
      type: oidc
      name: Pocket ID
      issuer: https://id.example.com
      client_id: "<client ID>"
      client_secret: "<client secret>"

name labels the button, which reads Sign in with Pocket ID here. Leave client_secret empty for a public client.

Restart Umpteenth with docker compose restart umpteenth, or start it for the first time with docker compose up -d.

Umpteenth fetches the issuer’s configuration from inside its container, so the issuer URL has to work there as well as in your browser, which rules out localhost.

Everyone your identity provider admits to the client can sign in. To narrow that down, list groups in the provider’s allowed_groups, such as allowed_groups: [umpteenth-users], and have your identity provider put the groups claim into the ID token. If it lists groups in another claim, name that claim in groups_claim, such as groups_claim: roles. Umpteenth then admits members of at least one listed group, and everyone else lands back on the login page with “Your account is not allowed to use Umpteenth”.

GitHub

A github provider signs you in with a github.com account through a GitHub OAuth app.

On GitHub, open Settings → Developer settings → OAuth Apps and click New OAuth App (Register a new application on an account without OAuth apps).

Fill in the form and click Register application.

Field	Value
Application name	The name GitHub shows when it asks you to authorize the app, such as `Umpteenth`
Homepage URL	`app.url`, such as `https://umpteenth.example.com`
Authorization callback URL	`<app.url>/api/auth/callback/github`, where `github` is the provider’s ID in step 4

Click Generate a new client secret, and copy the secret and the Client ID.

Add the provider to config.yml with the type github, and list who may sign in.

auth:
  providers:
    github:
      type: github
      name: GitHub
      client_id: "<client ID>"
      client_secret: "<client secret>"
      allowed_users: [octocat]
      allowed_organizations: [acme]

Restart Umpteenth with docker compose restart umpteenth, or start it for the first time with docker compose up -d.

Any GitHub account can authorize an OAuth app, so Umpteenth refuses to start while a github provider names nobody in its allow or admin lists. allowed_users lists GitHub usernames, and allowed_organizations admits the active members of the listed organizations, so a pending invitation isn’t enough. Everyone else lands back on the login page with “Your account is not allowed to use Umpteenth”.

If an organization restricts access for OAuth apps, an owner has to approve the app on GitHub, or Umpteenth turns the organization’s members away.

Several providers

Add a block under auth.providers for each way to sign in, and mark one as primary:

auth:
  providers:
    pocket-id:
      type: oidc
      name: Pocket ID
      issuer: https://id.example.com
      client_id: "<client ID>"
      client_secret: "<client secret>"
      primary: true
    github:
      type: github
      name: GitHub
      client_id: "<client ID>"
      client_secret: "<client secret>"
      allowed_organizations: [acme]

The primary provider gets the large button at the top of the login page, and the others follow below it, with Sign in with a passkey last. Without any provider, the passkey button is the large one. Passkeys use the provider ID passkey, so no provider can have it.

Umpteenth tells users apart by the account they sign in with, so a person who signs in through Pocket ID and through GitHub becomes two users, and a passkey account is a third.

Instance admins

Instance admins see every user and workspace of the instance and can deactivate users, as Workspaces describes. The first passkey account is one, and an instance admin makes other passkey accounts admins with Make instance admin in their ⋯ menu under Admin → Users. For people who sign in through a provider, name them in that provider’s options: admin_groups on an oidc provider, and admin_users or admin_organizations on a github provider.

auth:
  providers:
    pocket-id:
      # type, name, issuer and client as above
      admin_groups: [umpteenth-admins]
    github:
      # type, name, client and allow lists as above
      admin_users: [octocat]

Admins get in even when the allow lists leave them out. Umpteenth checks the admin lists at every sign-in, so a change takes effect the next time that person signs in, and Admin → Users offers no admin switch for these accounts.