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.
Supported providers
Section titled “Supported providers”| Type | Use for |
|---|---|
oidc | Any standard OIDC provider, for example Pocket ID |
github | GitHub OAuth apps |
gitlab | GitLab OAuth applications |
google | Google OAuth clients |
discord | Discord 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.
Provider IDs
Section titled “Provider IDs”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.
Callback URLs
Section titled “Callback URLs”Register this callback URL with each provider:
https://chat.example.com/auth/providers/{providerID}/callbackChatto 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.
Configuration
Section titled “Configuration”[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.
[webserver]url = "https://chat.example.com"
[[auth.providers]]id = "github-main"type = "github" # or "gitlab", "google", "discord"label = "GitHub"client_id = "..."client_secret = "<generate-me>"auto_provision = falseCHATTO_AUTH_PROVIDERS_0_ID=company-ssoCHATTO_AUTH_PROVIDERS_0_TYPE=oidcCHATTO_AUTH_PROVIDERS_0_LABEL="Company SSO"CHATTO_AUTH_PROVIDERS_0_ISSUER_URL=https://idp.example.comCHATTO_AUTH_PROVIDERS_0_CLIENT_ID=...CHATTO_AUTH_PROVIDERS_0_CLIENT_SECRET=<generate-me>CHATTO_AUTH_PROVIDERS_0_AUTO_PROVISION=false
CHATTO_AUTH_PROVIDERS_1_ID=github-mainCHATTO_AUTH_PROVIDERS_1_TYPE=githubCHATTO_AUTH_PROVIDERS_1_LABEL=GitHubCHATTO_AUTH_PROVIDERS_1_CLIENT_ID=...CHATTO_AUTH_PROVIDERS_1_CLIENT_SECRET=<generate-me>Indexes start at 0 and must not have gaps. Fields are ID, TYPE, LABEL,
CLIENT_ID, CLIENT_SECRET, TOKEN_ENDPOINT_AUTH_METHOD, ISSUER_URL,
SCOPES (comma-separated), REQUEST_EMAIL, and AUTO_PROVISION.
If you set any CHATTO_AUTH_PROVIDERS_<index>_* variable, Chatto ignores the
providers in chatto.toml. Chatto also accepts the older
CHATTO_AUTH_OIDC_ENABLED, _ISSUER_URL, _CLIENT_ID, _CLIENT_SECRET, and
_LABEL variables. They create one oidc provider with id = "oidc". Do not
use them together with counted variables.
Token endpoint authentication
Section titled “Token endpoint authentication”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.
CIMD public clients
Section titled “CIMD public clients”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 = trueSet 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.
Scopes
Section titled “Scopes”Chatto requests only the scopes that identify the account. It requests email
scopes only when request_email = true. The default is false.
| Type | Default scopes | With request_email = true |
|---|---|---|
oidc | openid, profile | openid, profile, email |
github | none | read:user, user:email |
gitlab | none | read_user |
google | openid, profile | openid, profile, email |
discord | identify | identify, email |
To set different scopes:
[[auth.providers]]# ...scopes = ["openid", "profile", "groups"]Chatto always adds openid for OIDC providers.
Auto-provisioning
Section titled “Auto-provisioning”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.
Manage usernames and account links
Section titled “Manage usernames and account links”For a company provider, you can assign usernames and prevent users from disconnecting the provider:
[[auth.providers]]# ...manage_usernames = trueupdate_usernames = falseallow_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:
| Provider | Username source |
|---|---|
| OIDC | username_claim, which defaults to preferred_username |
| GitHub | Account login |
| GitLab | Account username |
| Discord | Account username, not the global display name |
Local 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.
Restrict who can sign in
Section titled “Restrict who can sign in”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 asrealm_access.rolesin 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"]Map groups to roles
Section titled “Map groups to roles”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. Seegroups_claimin 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
ownerandeveryoneroles. 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_groupsdenies 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.
Account matching
Section titled “Account matching”Chatto matches a login by provider identity, never by email address:
- OIDC: the verified issuer and the subject.
- OAuth providers: the provider
idand 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.
Verified email and verified factors
Section titled “Verified email and verified factors”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:
| Provider | Chatto stores a verified email when |
|---|---|
oidc | email is present and email_verified = true |
github | GitHub returns a verified primary email |
google | The profile marks the email as verified |
discord | The profile has verified = true |
gitlab | Never |
Password reset and owners.emails need a verified email. A linked identity
alone does not make a user an owner.
Discovery fields
Section titled “Discovery fields”Clients find the configured providers through
chatto.discovery.v1.ServerDiscoveryService.GetServer. The login.providers
field lists each provider ID, type, label, and login URL:
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 '{}'Example: Pocket ID
Section titled “Example: Pocket ID”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.
-
Create the client. In Pocket ID, open OIDC Clients and select Add OIDC Client:
Field Value Name ChattoCallback URL https://chat.example.com/auth/providers/pocket-id/callbackClient Launch URL https://chat.example.com(optional)Save the client. Copy the Client ID and Client Secret.
-
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.
-
Configure Chatto. Set
issuer_urlto 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 = falseTerminal window CHATTO_WEBSERVER_URL=https://chat.example.comCHATTO_AUTH_PROVIDERS_0_ID=pocket-idCHATTO_AUTH_PROVIDERS_0_TYPE=oidcCHATTO_AUTH_PROVIDERS_0_LABEL="Pocket ID"CHATTO_AUTH_PROVIDERS_0_ISSUER_URL=https://id.example.comCHATTO_AUTH_PROVIDERS_0_CLIENT_ID=<pocket-id-client-id>CHATTO_AUTH_PROVIDERS_0_CLIENT_SECRET=<generate-me>CHATTO_AUTH_PROVIDERS_0_AUTO_PROVISION=falseReplace
<generate-me>with the Pocket ID client secret. -
Choose how accounts are created. Keep
auto_provision = falseon an existing or invite-only server. Users then link Pocket ID from account settings. Set it totrueto let all allowed Pocket ID users create accounts. -
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.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Solution |
|---|---|
| The provider rejects the callback | Make 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 provider | Set 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 allowed | Select Allowed User Groups, or select Unrestrict. |
| Chatto does not create an account | Set auto_provision = true, or sign in to an existing account and link the provider first. |
| Links stopped working after a change | Restore 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. |