trellum
Docs / Portal guide / Single sign-on

Single sign-on

Applies to: latest

Each organization configures its own SSO in the UI — no instance-wide identity configuration. OpenID Connect and LDAP/Active Directory SSO are supported.

Identity provider side

OpenID Connect providers must supply the email verification evidence needed for first linking, as well as support discovery and the authorization code flow. The provider setup below describes prerequisites and limitations; a successful connection alone does not establish first-link support. Internal providers can run on a network with no internet access. Register trellum as a client (an "app registration") there and collect:

  • The issuer URL — the base the provider serves /.well-known/openid-configuration from, e.g. https://keycloak.internal/realms/acme
  • The client ID
  • A client secret
  • The redirect URI shown on the portal's SSO settings page

Register that URI exactly, including its scheme and trailing slash. The authorization request and token exchange use this same callback, built from the instance's Public URL (or PORTAL_BASE_URL when that field is empty). For an HTTPS deployment, set the public URL to https:// even when a reverse proxy forwards HTTP to the portal. No per-provider callback override is needed.

Grant the openid, profile and email scopes. For group mapping, have the provider emit a claim listing the user's groups (groups at most providers; roles or a namespaced claim at some) and grant whatever consent your provider needs to read group memberships.

Portal side

In Organization settings → Single sign-on, enter those values (the secret is stored encrypted) and set:

  • Issuer URL — your provider's OpenID Connect issuer (Microsoft Entra: https://login.microsoftonline.com/<tenant-id>/v2.0, Google: https://accounts.google.com, Okta: https://<your-domain>.okta.com, Keycloak: https://<host>/realms/<realm>). On save the portal fetches the issuer's /.well-known/openid-configuration and shows the authorization and token endpoints it found; a wrong issuer is refused with the discovery error, so it fails here rather than at someone's first login
  • Email domains — which addresses route to this organization's SSO
  • Auto-provision — create an account automatically on first successful login, or leave it off so SSO only works for people who are already members (an unrecognized login is refused with instructions to request an invitation)
  • Default role and groups — what an auto-provisioned user gets
  • Groups claim — the claim the provider lists the user's groups in (groups unless you change it)
  • Group mapping — identity provider groups, as they appear in that claim, to trellum permission groups
  • Extra scopes — empty unless the provider only emits its groups claim for a scope of its own; the provider setup below says when
  • allow_password_login — whether passwords still work alongside SSO
  • enforce_sso — require SSO for this organization

Group mapping is re-applied on every login, so revoking a group in your directory revokes the corresponding access at next sign-in.

Before linking an existing member or provisioning an account, the portal requires email verification evidence: email_verified: true for ordinary OpenID Connect providers, or the tenant-bound Entra evidence described below. For the ordinary setup, send email with matching email_verified: true as a JSON boolean. A missing verification claim, false, or a string such as "true" does not establish verification. An existing portal account or an invitation does not bypass this requirement. Requesting the email scope requests claims; the provider must also have verified that user's address.

For ordinary verification, UserInfo claims take precedence over ID-token claims. Keep the email and verification state consistent in both responses; when present, an effective email_verified value other than Boolean true is refused. The Entra domain-confirmation path additionally rejects an explicit negative in either source. Returning identities use their existing provider subject link rather than repeating first-link verification; their email must still belong to a routed domain, verified when domain verification is required. The mailbox-less Entra exception below uses a tenant-managed UPN. Neither Entra exception extends to AD FS or other providers.

An internal provider whose certificate comes from a private CA works without disabling verification: point REQUESTS_CA_BUNDLE at your CA bundle in the portal's environment. Discovery and the login flow share one HTTP client, so that single variable covers both.

Test sign-in

Before you turn on Enforce SSO or turn off password login, check that single sign-on works from end to end. Organization settings → Single sign-on → Test sign-in runs the real sign-in and tells you what would have happened. It never logs anyone in, links an account, creates a user or changes a group, and you stay signed in as yourself throughout. Only organization admins can run it, and it uses the settings as last saved with SSO enabled.

OpenID Connect. Press Test sign-in. Your identity provider opens and asks which account to use; choose the account you want to try (a test user is ideal). You come back to the settings page with a checklist:

  • Identity provider reached
  • Email claim found, with the address the provider sent
  • Email domain routes to single sign-on, or why not: the domain is not listed, or it is listed but not yet verified
  • Email verified by the identity provider
  • Admission outcome: would sign in the existing member, would create a new account, or would be refused, with the reason
  • Groups claim found and how many groups it listed, which mapped permission groups would be granted, and which would be removed

The test only counts for ten minutes after you press the button and works once.

To check first linking, choose a fresh provider identity that has never been linked to this organization in the portal. A private browser window alone does not make an identity unlinked. Use a verified address in a routed domain (verified when domain verification is required), and either add that address as a member first or enable Auto-provision for the intended test. Require passing email verification and the expected admission outcome. Repeat for each connection or account type you intend to admit. Test sign-in leaves the identity unlinked, so you can repeat it after correcting provider settings.

A successful sign-in by an already-linked user does not prove first-link support. For a linked identity, Test sign-in can show passing admission but failed email verification, making the overall test fail even when a real returning sign-in would succeed. Use a fresh identity to validate onboarding. A live test checks the saved configuration and chosen account; sample tokens and automated fixtures do not establish live provider compatibility.

Directory (LDAP / Active Directory). Enter a directory login and password under Test sign-in and press the button. The password is checked against the directory and is never stored or logged. The checklist is the same, minus the provider's email verification.

The page keeps the last result, who ran it and when. Each run is recorded in the audit log as sso.test_signin with the outcome and the checklist, never with tokens or passwords. For an unlinked identity, a failing line (a red cross) means a real first sign-in would be refused; a warning, such as a missing groups claim, does not fail the test but is worth reading. If you enforce SSO or turn off password login without a passing test on record, the page shows a warning. It does not stop you.

Provider setup

The portal requests the openid, profile and email scopes and reads the ID token and the userinfo response together. The Entra domain-confirmation exception below requires evidence from the ID token itself. What differs per provider is the issuer URL, where the email comes from, and what it takes to get a groups claim into the token. Extra scopes stays empty unless a subsection below says otherwise.

Microsoft Entra ID

  • Issuer: https://login.microsoftonline.com/<directory-tenant-id>/v2.0. Use the tenant ID, not common — discovery must name your tenant.
  • App registrations → New registration, single tenant. Under Authentication add a Web platform with the portal's redirect URI; under Certificates & secrets create a client secret (note its expiry). The client ID is the Application (client) ID on the overview page.
  • Email: email is present for accounts that have one. Accounts without a mailbox carry only preferred_username (the UPN), which the portal uses instead — so list the UPN domain under Email domains too. This fallback requires the exact tenant-specific Microsoft issuer above and an ID token whose tid matches its tenant ID. Configure this only for a tenant whose administrators control those UPNs; generic username claims are not trusted for linking. If an email claim is present without email_verified: true, configure the ID-token claims below.
  • Email domain confirmation: under App registrations → your application → Token configuration → Add optional claim, choose ID and add email and xms_edov. If using the manifest, merge these entries into the existing optionalClaims.idToken array, preserving other claims:

json {"name": "email", "essential": false}, {"name": "xms_edov", "essential": false}

xms_edov is Microsoft's confirmation of the email domain owner, not a general mailbox-verification flag. The portal accepts it only when it is Boolean true in the validated ID token, the tenant and issuer match the configured provider, the subject matches the sign-in identity, and the token email matches the email being linked. UserInfo-only confirmation cannot satisfy this check. An explicit negative email_verified still blocks it. Configure the organization provider only for a tenant you trust to manage identities for its allowed email domains. See Microsoft's optional claim reference.

Adding an optional claim does not force Microsoft to return true. If it is absent or false, ask the tenant administrator to check the account and domain verification; do not map a constant true or disable verification. After saving, start a fresh Test sign-in. Existing accounts must still belong to this organization, and new accounts still require Auto-provision. Keep the registered callback URL unchanged; these are ID-token claims, not additional API permissions or entries for Extra scopes. - Groups: Token configuration → Add groups claim, pick Security groups (or Groups assigned to the application in a large tenant), ID token format Group ID. Values are group object IDs, so the mapping reads <object-id> = <permission group>. Choosing a name format there (sAMAccountName, or Cloud-only group display names, which needs the assigned-groups option) lets you map names instead. - Above 200 groups the token carries an overage pointer instead of the list; the portal leaves that user's mapped groups untouched on such logins. Keep the count down with Groups assigned to the application.

Google Workspace

  • Issuer: https://accounts.google.com.
  • Google Cloud console → APIs & Services → Credentials → Create credentials → OAuth client ID, type Web application, with the portal's redirect URI under Authorized redirect URIs. Set the consent screen's audience to Internal so only accounts in your Workspace can sign in.
  • Email: the email scope returns email and email_verified; first linking requires a verified Workspace account with Boolean email_verified: true. hd identifies the hosted Workspace domain. Use the Internal audience above to restrict accounts; the email suffix alone does not prove Workspace membership. See Google's OIDC claim reference and Workspace identity guidance.
  • Groups: none. Google's OpenID Connect tokens carry no group membership, so leave Group mapping empty — an empty mapping touches nothing — and use Default groups or the portal's own group management instead.

Okta

  • Issuer: the org authorization server, https://<your-okta-domain> (e.g. https://acme.okta.com), or a custom authorization server such as https://<your-okta-domain>/oauth2/default.
  • Applications → Create App Integration → OIDC - OpenID Connect → Web Application, with the portal's redirect URI under Sign-in redirect URIs. Assign the users or groups that may sign in; copy the client ID and secret.
  • Email: the email scope requests email and email_verified. Complete verification of the user's primary email in Okta and confirm your chosen authorization server and flow return Boolean email_verified: true for that address. An assigned or active account alone is not proof of email verification. See Okta's scope-dependent claims.
  • Groups on the org authorization server: open the app's Sign On tab, OpenID Connect ID Token → Edit, Groups claim type: Filter, claim name groups, Matches regex .* (or Starts with a prefix). The org server only emits the claim when the groups scope is requested, so enter groups under Extra scopes. On a custom authorization server add the claim under Security → API → your server → Claims (Include in token type: ID Token, Value type: Groups, any scope) and no extra scope is needed. Values are group names, e.g. Analysts; every user is also in Everyone.

Ping Identity (PingOne)

  • Issuer: https://auth.pingone.com/<environment-id>/as — auth.pingone.eu, .ca, .asia or .com.au for tenants in those regions.
  • Applications → + → OIDC Web App. On Configuration choose the Authorization Code grant, add the portal's redirect URI and set token endpoint authentication to Client Secret Basic; grant the openid, profile and email scopes under Resources; enable the app.
  • Email: the email scope requests email and email_verified. Complete PingOne's email verification flow so the user's directory emailVerified state is true. Check the application's claim mappings return that state as Boolean email_verified: true alongside the verified address. Populating the email attribute alone is insufficient.
  • Groups: Attribute Mappings → + Add, claim groups, PingOne attribute Group Names (memberOfGroupNames; Group IDs to map by ID). A mapped claim is returned in the ID token regardless of scopes. Values are PingOne group names.

OneLogin

  • Issuer: https://<subdomain>.onelogin.com/oidc/2.
  • Applications → Add App → OpenId Connect (OIDC). On Configuration add the portal's redirect URI; on SSO choose application type Web and token endpoint authentication Basic; copy the client ID and secret. Give users access through a role.
  • Email: email comes with the email scope, but OneLogin omits email_verified by default. Follow OneLogin's verification-claim setup: create a custom attribute holding the user's real email verification state, populate it only through a workflow that verifies the current address, and map an OIDC app parameter named email_verified to that attribute (custom_attribute_email_verified if its short name is email_verified). Confirm the issued claim is JSON Boolean true, not the string "true"; an unset attribute omits the claim. Never map a constant true or mark every user verified merely to enable sign-in. Without real verification state and this mapping, the recipe does not support first linking.
  • Groups: on Parameters open Groups, set Default if no value to User Roles with Semicolon Delimited input (Multi-value output). OneLogin emits the claim only for the groups scope, so enter groups under Extra scopes. Values are role names. A user with no roles gets no claim at all, which the portal treats as membership of none.

JumpCloud

  • Issuer: https://oauth.id.jumpcloud.com (the app's SSO tab shows the issuer for your tenant).
  • SSO Applications → + Add New Application → Custom Application → Manage Single Sign-On → Configure SSO with OIDC, with the portal's redirect URI under Redirect URIs, Client Authentication Type: Client Secret Post, standard scopes Email and Profile. Save, then copy the client ID and the secret, which is shown once. Connect the user groups that should have access on User Groups.
  • Email: email comes with the Email scope.
  • Groups: under Attribute Mapping → Group Attributes tick include group attribute and name it groups. Only the groups connected to the application are listed, by name.

Auth0

  • Issuer: https://<tenant>.<region>.auth0.com (e.g. https://acme.eu.auth0.com), or your custom domain.
  • Applications → Create Application → Regular Web Applications, with the portal's redirect URI under Allowed Callback URLs. Enable the connections your users sign in with; copy the client ID and secret.
  • Email: the email scope requests email and email_verified; it does not verify an account. Complete the connection's email verification workflow and confirm Boolean email_verified: true is returned for the address. Database users can complete Auth0's verification email; social and enterprise connections depend on their upstream verification workflow and may update the state on later sign-ins. Check each connection you enable.
  • Groups: Auth0 refuses custom claims named groups or roles; a custom claim must be namespaced with a URL you control. Add a Login / Post Login Action:

js exports.onExecutePostLogin = async (event, api) => { api.idToken.setCustomClaim("https://example.com/groups", event.authorization?.roles ?? []); };

then set Groups claim to https://example.com/groups. Values are the role names assigned under User Management → Roles.

Keycloak

  • Issuer: https://<host>/realms/<realm> (/auth/realms/<realm> on older versions).
  • Clients → Create client, type OpenID Connect, Client authentication on, Standard flow on, with the portal's redirect URI under Valid redirect URIs. The secret is on the Credentials tab.
  • Email: retain the built-in email client scope and its email and email verified mappers. The latter emits the user's verification state as Boolean email_verified. Have users complete Verify Email, with realm email delivery configured; filling in the email field alone is insufficient. Confirm email_verified: true reaches the portal. See Keycloak's client scopes and email verification.
  • Groups: on the client's Client scopes tab open the <client>-dedicated scope, Add mapper → By configuration → Group Membership, token claim name groups, Full group path off, Add to ID token on. Values are then plain group names; with the full path on they read /parent/child and the mapping must match. A User Realm Role mapper works the same way with Groups claim set to its claim name.

AD FS (Windows Server 2016 and later)

First-link limitation: the email, UPN and groups recipe below does not supply verified-email evidence. It is insufficient to link an existing member or provision a new account. First-link support requires a validated configuration emitting Boolean email_verified: true based on real verification of the supplied email; no such recipe is established here. Entra's tenant-specific exceptions do not apply to AD FS. Do not add a constant verification claim. Microsoft's OIDC concepts describe claim issuance and allatclaims, which copies claims without establishing email verification.

This limitation does not apply to direct LDAP / Active Directory sign-in, which checks directory credentials rather than an OIDC verification claim.

  • Issuer: https://<federation-service-host>/adfs.
  • AD FS Management → Application Groups → Add Application Group → Server application accessing a Web API. Server application: note the client identifier, add the portal's redirect URI, Generate a shared secret and copy it. Web API: set the Identifier to that same client identifier. Under Permitted scopes tick openid, profile, email and allatclaims.
  • On the Web API's Issuance Transform Rules add Send LDAP Attributes as Claims: E-Mail-Addresses → E-Mail Address, and Token-Groups - Unqualified Names with the outgoing claim type typed as groups.
  • Enter allatclaims under Extra scopes: AD FS copies the rule-issued claims into the ID token only for that scope, and its userinfo endpoint returns nothing but sub.
  • Email: email from the rule when the account has a mail attribute; a fallback to upn does not satisfy first-link email verification.
  • Groups: groups, as Active Directory group names. A user in one group gets a plain string instead of a list, which the portal accepts. AD FS 2016 needs update KB4019472 for allatclaims.

LDAP / Active Directory

Directory sign-in is for on-premises directories with no federation layer in front of them. If you have Microsoft Entra ID, AD FS (2016 or later), or any cloud identity provider, use OpenID Connect instead: with OpenID Connect the portal never handles the password.

For an organization whose identity lives in an on-premises directory — Active Directory, OpenLDAP, FreeIPA — with no OpenID Connect provider in front of it, or on a network with no route to one. Set Identity source to LDAP / Active Directory on the same settings page. An organization has one identity source: OpenID Connect or a directory, not both.

This works differently from OpenID Connect, and it is worth being plain about it: the password is typed into the portal's login form and the portal checks it against your directory.

Fields:

  • Server URI — ldaps://dc.corp.example:636, or ldap://dc.corp.example:389, which the portal upgrades with StartTLS before anything else is sent. Every connection is TLS; there is no way to send a password in the clear. Referrals are never followed.
  • CA certificate — the PEM certificate of the CA that signed your directory's certificate. Internal directories almost always use a private CA; paste it here. Certificate verification is always on — there is no option to disable it — and the server name is checked against the certificate.
  • Bind DN and bind password — a read-only service account the portal searches with (the password is stored encrypted). It needs read access to the search base and to the users' entries; a directory that hides them from it answers "no such object", and the connection test says so. Leave the DN blank to search anonymously, if your directory allows it.
  • User search base and user filter — where to look and how. {login} in the filter is replaced by the email typed at the login form (escaped). The default (|(mail={login})(userPrincipalName={login})) suits Active Directory and works unchanged on OpenLDAP, which ignores the userPrincipalName half it does not know. Exactly one entry must match.
  • Email, display name and groups attributes — mail, displayName and memberOf by default. Active Directory always has memberOf; on OpenLDAP it exists only with the memberof overlay loaded, and only for groups added or changed after it was enabled. Without it the attribute is empty and no group mapping applies.

A login is a bind-then-search: the portal binds as the service account, finds the user's entry, then binds again as that entry with the typed password. That second bind is the credential check. The entry's email attribute names the portal account (the typed email if the entry has none), and it must sit inside the organization's email domains, as with OpenID Connect. Membership rules are the same too: existing users must already be members, new accounts are created only with auto-provisioning on.

Group mapping keys on the group's DN as it appears in the groups attribute — CN=Analysts,OU=Groups,DC=corp,DC=example — and is re-applied on every login like the OpenID Connect mapping.

Email domains route logins to the directory exactly as they route to an OpenID Connect provider, and domain ownership (below) applies the same way. With allow_password_login on, a password the directory rejects is still tried against the portal's own account; with it off, or with enforce_sso on, the directory is the only check. Members with a portal MFA device are asked for their code after the directory accepts the password, and an organization MFA policy applies to directory logins like any other password login.

Test directory connection on the settings page binds with the saved settings and reads the search base, so an unreachable server, a rejected service account or a wrong base is diagnosed there rather than at someone's failed login. A directory that cannot be reached during a login shows a generic "sign-in is unavailable" message and records the error in the audit trail. Passwords are never logged or recorded.

When sign-in fails

If single sign-on fails after the identity provider has answered, the person sees We couldn't sign you in, a one-line cause, a Try again button (back to your identity provider when starting over can help, otherwise the login page), a Back to sign-in link, and a reference such as K3M7Q2XA.

Message Meaning
Your account isn't a member of Org yet. Ask an organization admin to invite you. A portal account exists for that email but isn't in the organization.
Org doesn't create accounts automatically. Ask an organization admin to invite you. No account yet and auto-provisioning is off.
email isn't in an email domain Org uses for single sign-on. The email's domain isn't one of the organization's routed domains.
Your identity provider didn't confirm your email address. The provider didn't supply accepted verification evidence for this email. For Entra, check the optional ID-token claims described above.
Your identity provider didn't send an email address. The token carries no email claim.
Single sign-on isn't turned on for Org. SSO was switched off, for example after the link was bookmarked.
Sign-in was cancelled. The person declined at the provider.
Your sign-in session expired or was already used. The sign-in started in another tab, took too long, or was reloaded.
Your identity provider reported a problem. / declined the sign-in. The provider returned an error (for example an Entra AADSTS code, a wrong client secret or issuer). Details are in the server log, never on the page.

Finding a reference. Open Organization settings → Audit log and search the reference. The matching auth.sso_denied row carries the reference and a reason_code (for example existing_non_member_account or idp_state_invalid) in its details; the same reference is written to the server log next to the reason, along with the provider's error text for identity-provider failures.

If Test sign-in reaches Entra, finds the email and routes its domain, but fails Email verified by the identity provider, check that you are running 0.9.3 or later and that the application's ID token includes email and Boolean xms_edov: true as described above. Application consent alone does not supply this evidence. Deleting an existing portal account will not fix it: both first-time linking and new-account creation require verification.

Security model

Instance operators are exempt from SSO enforcement, so a misconfiguration cannot lock everyone out of the instance. Linking an identity to a portal account happens only for someone already a member of that org — a domain being routed to SSO does not by itself grant access to it.

Warning

With verification switched off, email-domain routing asserts domain ownership rather than verifying it. On an instance shared by organizations that do not trust each other, confirm domain claims out of band before enabling a new organization's SSO — or turn verification back on, below.

Domain ownership

Whoever routes an email domain decides who may sign in as its users, so on a shared instance a claim alone isn't enough: without proof, any org admin could claim a domain they don't own and capture logins meant for someone else.

Organization settings → Single sign-on has a domain ownership section. When verification is optional, expand the advanced domain verification section to use it. Claim a domain, publish the TXT record it shows you, then verify:

_trellum-verification.example.com   TXT   trellum-verification=<token>

The token is per claim, so publishing someone else's proves nothing, and a domain can be held by only one organization at a time.

While verification is required, a listed email domain that is not verified does not route logins to single sign-on. The settings page lists those domains in a warning, and also warns when no listed domain routes at all. Still allow password login cannot be turned off while no domain routes, because people would then have no way to sign in. Enforce SSO is not blocked, since it applies to existing members whatever their email domain.

The login page asks for the work email first and nothing else. If the address routes to single sign-on (or belongs to a member of an organization that enforces it), the person is sent straight to the identity provider. Sign in with a password instead, shown to everyone, skips that redirect where the organization still allows password login (allow_password_login on, and the person is not a member of an organization that enforces SSO); instance operators are exempt from enforcement, so they can always reach the password step if single sign-on breaks. If the address does not route, or the person chose a password, the next page shows the email read-only, with a Use a different email link, and asks for the password (labelled Directory password when the address routes to a directory). That page looks the same whether or not an account exists, and the routing is checked again when the password is submitted, so an enforcing organization's members can never sign in with a password. The portal logs a warning when the address's domain is listed by an enabled configuration but is unverified.

New installations using the supplied .env.example, and newly generated demo environments, set TRELLUM_SSO_DOMAIN_VERIFICATION=false. This suits an instance run by one trusted organization: configure the email domains and identity provider without a separate DNS ownership step. The email-domain allowlist, provider authentication and organization membership checks still apply.

Existing environment files retain their behavior on upgrade. An explicit true or false is honored; when the setting is absent, verification remains on. Instances shared by organizations that do not trust each other should set it to true. Once on, only verified domains route, both when choosing where to send a login and when accepting the identity the provider asserts on return.

Turning verification back on

An instance that opted out and later needs verification — a second organization is joining, say — must not simply switch it on. Once the setting is on, only verified domains route. An organization with SSO enabled whose claimed domains are not all verified loses SSO at those domains outright: the login page stops sending its users to the identity provider, and the callback refuses the identity that comes back as outside the organization's verified domains. That includes organizations whose SSO worked the day before, so on an instance that already has SSO in use:

  1. While verification is still off, have each organization with SSO enabled claim and verify its domains in Organization settings → Single sign-on. Verification works with the setting off; it is just not required yet.
  2. Run manage.py check_sso_domains until it exits clean. It lists every enabled organization's claimed domains with their state and names the organizations that would lose SSO if verification were turned on now; --verify re-checks DNS for every pending claim first.
  3. Only then set TRELLUM_SSO_DOMAIN_VERIFICATION=true and restart the services. Verify the resulting claims before enforcing SSO.

Verifying needs the organization to publish a TXT record in its own DNS, which an operator cannot do on its behalf — plan step 1 as a request to each organization with lead time, not as a same-day configuration change.