Skip to content

External login providers

An external login provider lets users sign in with an account they have elsewhere: an OpenID Connect provider (Google Workspace, Microsoft Entra ID, Keycloak, and the like), GitHub, Discord, or one Mastodon server. You set providers up with the my login-provider command on a host that has the server’s configuration, or through the admin API (/api/v1/admin/login_providers) with the manage_login_providers permission, which only the built-in admin role has. The command works before any administrator can sign in, so you can use it for the first setup. In the web client, administrators with that permission use “Login providers” in the administration menu. The list shows each provider’s kind, state, how many users are linked and whether sign-up is allowed, under a summary of the limit to login providers while it is on; “Add a login provider” opens the form that creates one. Choosing a provider opens its page, which shows its callback URL with a button that copies it, and where you change its settings, enable or disable it and give it a new client secret, all saved with one button, and delete it, which asks you to type its name.

  • A provider only proves who someone is at that provider. An account is never linked to a user by email address: a user links an account under “Linked accounts” in settings, or signs up with it as a new user. An email address that matches an existing user never links that user.
  • A linked user still enters the two-factor code (TOTP) after signing in with a provider, and a user whose account is not active cannot sign in.
  • New users can sign up with a provider only when you allow it for that provider (-allow-signup) and the registration mode lets them register; the invite code, CAPTCHA, sign-up blocks, and network limit apply as on the password form. Someone who signs up this way has no password and signs in with the provider only. The diagram of the sign-up paths shows both ways of signing up side by side.
Kind -issuer Conditions
oidc The issuer URL (https), exactly as the provider’s ID tokens name it, such as https://accounts.google.com -claim <claim>=<value>: only users whose ID token has the claim with one of the values given for it
github None: the server knows github.com’s endpoints -org <organization>: only members of one of the Organizations (add -scope read:org)
discord None: the server knows discord.com’s endpoints -guild <server ID>: only members of one of the Discord servers (guilds); none lets every Discord user in
mastodon The server’s web domain, such as mastodon.example (Mastodon 4.3 or later) None

For Google Workspace, limit the users to your organization with -claim hd=<your domain>. Do not rely on the domain of the email address.

In the Google Cloud console, create an OAuth client of type “Web application”. To keep it to your organization, set the user type of the OAuth consent screen to “Internal” (available when the project belongs to a Google Workspace organization), and also add the hd condition: the user type restricts who Google lets in, and the condition makes this server check the hd claim of every ID token.

Terminal window
printf '%s\n' "$CLIENT_SECRET" | my login-provider create -kind oidc -name Google \
-issuer https://accounts.google.com -client-id 123.apps.googleusercontent.com -claim hd=example.com

Keycloak and other OpenID Connect providers

Section titled “Keycloak and other OpenID Connect providers”

The issuer is the realm URL, such as https://sso.example.com/realms/main, exactly as the provider’s ID tokens name it. Create a confidential client with the standard flow, and the openid, email, and profile scopes. If the provider is on a private network, list it in login_provider_allowed_destinations (below). Use -claim to require a claim, such as a group claim, with one of the values given.

Create an application in the Discord Developer Portal, open “OAuth2”, and give the server the client ID and the client secret. The server asks for the identify and email scopes, and also guilds when you list servers with -guild. A user is known by their numeric Discord ID; the username and display name only suggest the username on the sign-up form. The email address counts as verified only when Discord says it is verified; otherwise the user confirms it by mail like any other address.

With -guild, the server checks on every sign-in, sign-up, and link that the user belongs to one of the listed servers and refuses the user otherwise. Without it, every Discord user may sign in. A guild ID is a number of up to 20 digits: in Discord, turn on “Developer Mode” (User Settings, Advanced), then right-click the server’s icon and choose “Copy Server ID”.

Terminal window
printf '%s\n' "$DISCORD_SECRET" | my login-provider create -kind discord -name Discord \
-client-id 123456789012345678 -guild 987654321098765432

Add the callback URL under “OAuth2”, “Redirects” in the application, after add prints it.

Create an OAuth App (Settings, Developer settings, OAuth Apps) and give it the client ID and secret. The server asks for the user:email scope, and also read:org when you list Organizations with -org. With -org, the server checks on every sign-in that the user belongs to one of the Organizations, so members of other Organizations are refused.

The redirect URI that the provider needs is the provider’s callback URL, https://<host>/auth/external/<id>/callback, which contains the ID that the server gives the provider. So:

  1. Register an OAuth client at the provider (an “OAuth App” on GitHub) with any redirect URI for now, and note the client ID and the client secret it gives.
  2. Run my login-provider create with them. It prints the callback URL.
  3. Change the redirect URI of the client at the provider to that callback URL.
Terminal window
# The client secret is read from standard input, or prompted for in a terminal.
printf '%s\n' "$CLIENT_SECRET" | my login-provider create -kind oidc -name "Example SSO" \
-issuer https://sso.example.com -client-id my-client-id -claim hd=example.com
printf '%s\n' "$GITHUB_SECRET" | my login-provider create -kind github -name GitHub \
-client-id Iv1.0123456789abcdef -org example-org -scope read:org

A mastodon provider is one Mastodon server that you name; users of other servers cannot sign in with it. The server must be Mastodon 4.3 or later: add reads its authorization server metadata (/.well-known/oauth-authorization-server) and refuses a server without it. Without -client-id, add registers a client at the server itself, with the callback URL and the profile scope, and stores the client ID and secret it gets, so there is nothing to do at the server:

Terminal window
my login-provider create -kind mastodon -name mastodon.example -issuer mastodon.example

If the server does not let others register clients, add fails. Create an application with the profile scope and the callback URL in the server’s development settings instead, and give its client ID and secret as for the other kinds (the callback URL contains the provider’s ID, so follow the three steps above).

Users sign in with the profile scope only, which reads their account and nothing else. Mastodon gives no email address, so someone who signs up with it confirms the address by mail. The sign-up form suggests the account’s username. While the server’s domain, or a parent domain, has a domain action (domain actions), its button is gone and nobody signs in, signs up, or links an account with it. The server of a provider does not change; set up a new provider for another server.

The client secret is stored encrypted with the key encryption key (key management) and is never shown again, by the command or by the admin API.

A new provider is enabled. By default users may link their existing account to it (-allow-link), but nobody may sign up with it: add -allow-signup to let new users register with it, which the registration mode still limits (registration).

Terminal window
my login-provider list # every provider with its callback URL and linked users
my login-provider set -name "Corp SSO" <id> # changes only the settings it names
my login-provider set -claim '' <id> # '' removes every -claim (or -scope, -org)
my login-provider rotate-secret <id> # reads the new client secret like add
my login-provider disable <id>
my login-provider enable <id>
my login-provider delete <id>
  • set changes only the settings it names. -scope, -claim, and -org replace the whole list. The kind of a provider does not change; set up a new provider instead.
  • rotate-secret replaces the client secret with the one you enter. Rotate it at the provider first, then here.
  • disable keeps the provider and the accounts linked to it, but nobody signs in, signs up, or links with it, and the sign-in page does not show it, until you run enable. disable and delete print how many linked users can no longer sign in with the provider, and what the limit to login providers does now while its setting is on.
  • delete removes the provider for good.

Disabling or deleting a provider does not touch the users. A user who has a password or a passkey, or has another linked account, signs in that way, unless sign-in is limited to login providers and another provider stays enabled. A user who has none of these can no longer sign in at all: disable and delete print how many linked users lose the provider, and the web client shows the number in the confirmation. enable restores the users of a disabled provider; a deleted provider cannot come back.

To recover such a user, issue a password reset link on the account’s Management page of the admin screens, or with my admin account password-reset-link @alice, and give it to the user (registration). The user then signs in with the new password.

Every change is recorded in the audit log under the provider’s display name, as the CLI or as the administrator who made it through the admin API.

The instance setting login_providers_only (off by default) makes the providers the only way to sign in and register, while at least one provider is enabled. Turn it on on the “Registration” page of “Server settings” in the web client, or with the CLI:

Terminal window
my instance set login_providers_only true

The confirmation in the web client and the output of the command say how many active local users have no link to an enabled provider. The web client also says when that includes you. It warns and does not refuse: you decide.

While the limit applies:

  • Passwords and passkeys sign nobody in, and the sign-in page shows only the providers. A sign-in that had started with a password or a passkey and waits for its two-factor code is refused too.
  • Nobody registers with a password. The registration page shows the providers that allow sign-ups (-allow-signup), under the registration mode as usual. With no such provider, registration reads as closed, also to clients and in NodeInfo.
  • Nobody asks for or uses a password reset link. Links stay valid until they expire, and work if the limit ends in time.
  • Users cannot set or change a password, or add a passkey, because neither could sign in. They can still remove them.
  • my admin account password-reset-link and the admin screens still issue a link, and say that it does not work until the limit ends. my admin create still creates an administrator, and warns that the password cannot sign in.
  • A user cannot unlink their last account at an enabled provider.

What keeps working:

  • Sessions, app access tokens, and refresh tokens stay valid. The limit ends none of them.
  • A password or a passkey still confirms operations in a session. That is how an existing user moves to a provider: while signed in, they open “Linked accounts” in settings, confirm with the password or passkey, and sign in at the provider.
  • Sign-in, sign-up, and linking at a provider, and the two-factor code after a provider’s sign-in.

Every refusal reads the same whatever email address, password, or token was sent, so it says nothing about any account.

Users without a link cannot sign in once their sessions end, until you act. An account is never linked by email address, so a provider’s sign-in does not find them either. Ask them to link an account while they are signed in. A user who lost their session needs you to end the limit for a while, or to keep them out. This includes a user under disable_login, suspend, or ban, who has no sign-in page to appeal from without a link. Linking also needs the browser to be signed in to the sign-in pages: a user whose app is still signed in, but whose browser session ended, cannot link while the limit applies, and has to wait for you. Announce the change to your users before you turn the limit on, so that they link an account while their sessions last.

The limit follows the setting and the providers from one request to the next, without a restart.

  • An administrator who is locked out runs this on a host that has the server’s configuration:

    Terminal window
    my instance set login_providers_only false
  • When no provider is enabled, the limit does not apply: disabling or deleting the last provider opens password and passkey sign-in again, whatever the setting says. Users with neither a password nor a passkey still need a reset link.

  • With the setting on and no provider enabled, setting up or enabling a provider starts the limit at once; a new provider is enabled as soon as it is set up. The web client warns first, with how many active users have no link to that provider and whether that includes you. It warns only for the action that would start the limit. my login-provider create, enable, disable, and delete print what the limit does now while the setting is on.

  • When an outage at the provider keeps everyone out, use the same command.

Operations that ask for the password or a passkey (setting a password, adding a passkey, deleting or moving the account, linking another account) ask a user who has neither to sign in again at a linked provider (registration). An OpenID Connect provider is asked to authenticate the user again (max_age=0 and prompt=login) and the server refuses an earlier authentication; a Mastodon server is asked with force_login=true. GitHub and Discord have no way to ask for a fresh sign-in, so a user who is still signed in there is confirmed without entering anything. The server still checks that the account is the linked one, but this is weaker proof that the person is at the keyboard. Prefer an OpenID Connect provider, or have users keep a password or a passkey, when this matters.

The server reaches providers through its outbound HTTP guard, which refuses loopback and private addresses. To use a provider on your own network, such as a Keycloak next to the server, list its host or address range in login_provider_allowed_destinations.

For LLMs and coding agents:this page as Markdown, llms.txt,llms-full.txt, llms-small.txt

Analytics on this site