Single sign-on (OIDC)

Each organisation can sign in through its own identity provider with OpenID Connect. Users click Sign in with SSO on the sign-in page; their account is created the first time they sign in, if their email domain is allowed. Available on every tier.

Set it up

1. Register the platform at your identity provider

Create an OpenID Connect application (a "web application" with a client secret) and register this redirect URI:

<PUBLIC_URL>/api/v1/auth/sso/callback

PUBLIC_URL is the address your users reach the platform at, set in .env without a trailing slash. It defaults to http://localhost:8080, so set it on any real deployment:

PUBLIC_URL=https://tprm.example.com

The platform asks for the openid email profile scopes and uses the authorization code flow with PKCE.

2. Configure the organisation

As an administrator, open Organization > General > Single sign-on (OpenID Connect) (/orga/team/settings) and fill in:

Saving checks the issuer at once: an unreachable provider, or an issuer that is not https, is refused.

SSO only

SSO only turns off, for everyone but local administrators:

• password sign-in,
• password reset links,
• invitations: the Invite Member button gives way to "Accounts are created at first sign-in with SSO".

Local administrators keep their password. They are the way back in if the identity provider is down or misconfigured, so SSO only cannot be turned on while the organisation has no local administrator with a password.

How sign-in works

1. The user enters their work email and clicks Sign in with SSO. The email domain picks the organisation; with a single organisation offering SSO on the instance, the email can be left empty.
2. The identity provider authenticates them and sends them back with a one-time code, valid for 10 minutes.
3. The platform exchanges the code (client secret and PKCE), reads the user's profile from the provider, and checks that:
   • the email is verified at the provider, when it says so,
   • its domain is allowed for the organisation,
   • an existing account with that email belongs to the same organisation.
4. On the first sign-in, a member account is created, without a password, with the first and last name from the provider. The user limit of the license applies.

Good to know

• Roles. Accounts created by SSO are members. Roles are not mapped from the identity provider's groups yet.
• Leavers. Someone removed at the identity provider can no longer sign in. A session they already have open stays valid until they sign out.
• Existing accounts with an allowed email can use SSO too: the account is matched by email.
• SAML is not supported. Most providers offer OpenID Connect next to SAML; ADFS 2016 and later included.

Troubleshooting