Skip to content
Chatto v0.5.0

Login Providers

Add a login provider as a [[auth.providers]] entry in chatto.toml. The login page shows one button for each provider. Sign-in and account linking open in a popup, so users must allow popups for Chatto.

TypeUse for
oidcAny standard OIDC provider, for example Pocket ID
githubGitHub OAuth apps
gitlabGitLab OAuth applications
googleGoogle OAuth clients
discordDiscord OAuth2 applications

Self-hosted OIDC providers include Pocket ID, Kanidm, VoidAuth, Portier, Authelia, Dex, Authentik, and Keycloak. Make sure that your provider supports standard OIDC discovery.

Each provider needs a stable id, for example github-main or staff-google. The ID is part of the callback URL, and Chatto stores it in each account link.

  • Use short, URL-safe IDs. Do not use spaces, /, ?, or #.
  • Do not change an ID after users link accounts. A change disconnects those links.

Register this callback URL with each provider:

https://chat.example.com/auth/providers/{providerID}/callback

Chatto makes the URL from webserver.url. Set webserver.url to the public HTTPS address of your server.

Older OIDC registrations can also use /auth/oidc/callback. Use the provider-specific URL for new registrations.

[webserver]
url = "https://chat.example.com"
[[auth.providers]]
id = "company-sso"
type = "oidc"
label = "Company SSO"
issuer_url = "https://idp.example.com"
client_id = "..."
client_secret = "<generate-me>"
auto_provision = false
# Optional: override the method from OIDC discovery.
# token_endpoint_auth_method = "client_secret_basic"

issuer_url is an absolute http or https URL. Chatto uses OIDC discovery from this issuer and verifies the ID token.

For oidc providers only, token_endpoint_auth_method can be client_secret_basic, client_secret_post, or none. Basic and POST need a client_secret. none needs no secret.

When you do not set it, public clients use none. Other clients use Basic if discovery lists it, and POST if not. If discovery does not list methods, Chatto uses Basic. Chatto does not try a second method after a failed exchange.

If your OIDC provider supports Client ID Metadata Documents (CIMD), you do not need to register a client ID and secret:

[[auth.providers]]
id = "company-sso"
type = "oidc"
label = "Company SSO"
issuer_url = "https://idp.example.com"
client_id = "https://chat.example.com/oauth/client-metadata.json"
auto_provision = true

Set client_id to exactly {webserver.url}/oauth/client-metadata.json and do not set client_secret. Chatto publishes its callback URL and client metadata at that URL.

Chatto requests only the scopes that identify the account. It requests email scopes only when request_email = true. The default is false.

TypeDefault scopesWith request_email = true
oidcopenid, profileopenid, profile, email
githubnoneread:user, user:email
gitlabnoneread_user
googleopenid, profileopenid, profile, email
discordidentifyidentify, email

To set different scopes:

[[auth.providers]]
# ...
scopes = ["openid", "profile", "groups"]

Chatto always adds openid for OIDC providers.

auto_provision controls whether a new provider identity can create an account.

  • false (default): Chatto returns the user to the login page with an explanation. Existing users can link the provider from account settings.
  • true: the user confirms a username, and then Chatto creates the account.

With invite-only account creation, new accounts also need an invitation code.

For a company provider, you can assign usernames and prevent users from disconnecting the provider:

[[auth.providers]]
# ...
manage_usernames = true
update_usernames = false
allow_unlinking = false
# OIDC only; the default is preferred_username.
username_claim = "preferred_username"

manage_usernames defaults to false. When enabled, Chatto assigns the username at account creation. Users still confirm account creation and can edit their display name. Chatto trims spaces, converts the username to lowercase, and checks its format. The source depends on the provider:

ProviderUsername source
OIDCusername_claim, which defaults to preferred_username
GitHubAccount login
GitLabAccount username
DiscordAccount username, not the global display name
GoogleLocal part of the verified email address: alice@example.com becomes alice

Google has no separate username. With default scopes, set request_email = true for managed Google usernames. Custom scopes replace those defaults and must include email or https://www.googleapis.com/auth/userinfo.email. Chatto rejects managed Google configuration without email access at startup. Email access lets Chatto receive the email address from Google and makes its local part the public Chatto username. Unverified or missing email addresses cannot supply a Google username. Other providers do not fall back to email. No provider uses the display name.

If the name is taken, Chatto tries name-2, name-3, and further numbers, up to 1,000 candidates. It shortens the base when needed to fit the suffix. Missing, invalid, or reserved names prevent account creation; correct the provider claim.

Existing usernames stay unchanged by default. Set update_usernames = true to update them at subsequent sign-ins. This requires manage_usernames = true. An existing numeric suffix stays unchanged while it matches the provider name. If synchronization fails, the existing name stays and sign-in continues. The server logs a synchronization warning without the username.

Users cannot edit their username while any linked provider manages usernames. Display names remain editable. If multiple providers synchronize usernames, the provider used at sign-in determines the name. Configure those providers consistently to avoid repeated renames.

allow_unlinking defaults to true. Set it to false to disable user-initiated unlinking. Operators can still unlink through the operator API, provided another enabled sign-in method remains. If unlinking is allowed, removing the last managed provider restores local username editing. Removing a provider from the configuration or disabling manage_usernames also removes its edit restriction.

For old OIDC links that contain only an identity hash, Chatto applies configured OIDC restrictions until the next verified OIDC sign-in identifies the provider.

By default, every user of a provider can sign in through it. To allow only the members of some groups of an OIDC provider, add allowed_groups:

[[auth.providers]]
id = "company"
type = "oidc"
# ...
allowed_groups = ["chat-users"]
# Optional. The default is "groups".
# groups_claim = "groups"
  • allowed_groups: OIDC only. The user must be in at least one of these groups. Group names must match exactly.
  • groups_claim: OIDC only. The claim that contains the groups of the user. Chatto reads it from the ID token. If the ID token does not contain it, Chatto reads it from UserInfo. The claim can be a string or a list of strings. It must be a top-level claim. Chatto does not read nested claims such as realm_access.roles in Keycloak. Configure the provider to send the groups in a top-level claim.

If the groups claim is missing, Chatto denies the sign-in.

Chatto checks the groups at each sign-in and each time a user links the provider to an account. This also applies to accounts that already exist. When you remove a user from all allowed groups, that user cannot sign in through the provider again. Sessions that already exist stay valid until they end. The user sees a general message that does not tell why Chatto denied the sign-in.

Some providers send groups only when Chatto requests a groups scope. Add it with scopes. A scopes list replaces the default scopes:

scopes = ["openid", "profile", "groups"]

An OIDC provider can give Chatto roles to the members of its groups. Add group_roles with group:role pairs, separated by spaces:

[[auth.providers]]
id = "company"
type = "oidc"
# ...
group_roles = "chat-mods:moderator it-ops:admin it-leads:admin"
  • A user who is in a group gets the role when they sign in through the provider, link the provider to their account, or create an account through it.
  • A role can have more than one group. Any one of them gives the role.
  • Chatto reads the groups from the same claim as allowed_groups. See groups_claim in Restrict who can sign in.
  • Use role names, not display names. Chatto skips a role that does not exist and writes a warning to the log.
  • You cannot map the owner and everyone roles. Only one provider can map a role.
  • Group names cannot contain spaces. Use group IDs or other claim values without spaces. A group name can contain colons, because Chatto splits each pair at its last colon.

Chatto removes a role only if the provider gave it:

  • When a user leaves all groups of a role, Chatto removes the role at their next sign-in through the provider.
  • A role that an admin assigned stays. This also applies when the user later joins or leaves a mapped group, and to assignments that existed before you added the mapping.
  • Admins can still assign and remove each role. If an admin removes a role that the provider gave, the provider gives it again at the next sign-in while the user is in a matching group.
  • If allowed_groups denies the sign-in, Chatto removes the roles that the provider gave.
  • If a user unlinks the provider from their account, Chatto removes the roles that the provider gave.
  • If the provider sends no groups claim and you do not use allowed_groups, Chatto does not change any role.

Chatto records which provider gave each role by its issuer URL, as for account links. You can change the provider id. If the issuer URL changes, the provider does not remove roles that it gave under the old issuer.

Chatto learns about group changes only at sign-in. Until a user signs in again through the provider, they keep the roles from their last sign-in, also in sessions that already exist.

Chatto matches a login by provider identity, never by email address:

  • OIDC: the verified issuer and the subject.
  • OAuth providers: the provider id and the provider user ID.

To link a provider, a user signs in, opens account settings, and confirms their password or signs in again. An identity that is linked to a different account cannot be linked. Removing a provider needs confirmation and keeps existing sessions.

An account without an email address has no password until the user sets one. Email password reset needs a verified email address. On SSO servers without email, make sure that each user keeps at least one working provider link.

A linked identity is enough to sign in and counts toward limits.max_users, even without an email address. Chatto stores a provider email as a verified email only when the provider confirms it:

ProviderChatto stores a verified email when
oidcemail is present and email_verified = true
githubGitHub returns a verified primary email
googleThe profile marks the email as verified
discordThe profile has verified = true
gitlabNever

Password reset and owners.emails need a verified email. A linked identity alone does not make a user an owner.

Clients find the configured providers through chatto.discovery.v1.ServerDiscoveryService.GetServer. The login.providers field lists each provider ID, type, label, and login URL:

Terminal window
curl -X POST https://chat.example.com/api/connect/chatto.discovery.v1.ServerDiscoveryService/GetServer \
-H 'Content-Type: application/json' \
-H 'Connect-Protocol-Version: 1' \
--data '{}'

Pocket ID lets people sign in with passkeys. This example uses https://chat.example.com for Chatto and https://id.example.com for Pocket ID. Both must use HTTPS and must reach each other at these URLs.

  1. Create the client. In Pocket ID, open OIDC Clients and select Add OIDC Client:

    FieldValue
    NameChatto
    Callback URLhttps://chat.example.com/auth/providers/pocket-id/callback
    Client Launch URLhttps://chat.example.com (optional)

    Save the client. Copy the Client ID and Client Secret.

  2. Give users access. In Allowed User Groups, select the groups that can use Chatto, or select Unrestrict for all users. Until you do this, Pocket ID denies access to everyone. Pocket ID groups do not give Chatto roles or permissions.

  3. Configure Chatto. Set issuer_url to the Pocket ID base URL, without /.well-known/openid-configuration:

    [webserver]
    url = "https://chat.example.com"
    [[auth.providers]]
    id = "pocket-id"
    type = "oidc"
    label = "Pocket ID"
    issuer_url = "https://id.example.com"
    client_id = "<pocket-id-client-id>"
    client_secret = "<generate-me>"
    auto_provision = false

    Replace <generate-me> with the Pocket ID client secret.

  4. Choose how accounts are created. Keep auto_provision = false on an existing or invite-only server. Users then link Pocket ID from account settings. Set it to true to let all allowed Pocket ID users create accounts.

  5. Restart and test. Restart Chatto, open the login page, and select Pocket ID. With auto_provision = false, first sign in to an existing account, link Pocket ID, sign out, and then sign in with Pocket ID.

To get a verified email from Pocket ID, add request_email = true. Chatto stores the address only when Pocket ID also returns email_verified = true.

SymptomSolution
The provider rejects the callbackMake the registered callback URL match https://chat.example.com/auth/providers/{providerID}/callback exactly, including https. Set webserver.url to the public HTTPS URL.
Chatto cannot discover the providerSet issuer_url to the public base URL of the provider, without a discovery path. For Pocket ID, APP_URL must also be that URL.
Pocket ID says that the user is not allowedSelect Allowed User Groups, or select Unrestrict.
Chatto does not create an accountSet auto_provision = true, or sign in to an existing account and link the provider first.
Links stopped working after a changeRestore the original provider id and its callback URL.
Users see “not allowed to sign in to this server”The user is not in an allowed group, or the provider does not send the groups claim. Check allowed_groups, groups_claim, and whether the provider needs a groups scope.