Single sign-on

Ctadel supports two single sign-on protocols: OIDC, spoken directly by the application, and SAML 2.0, handled by a dedicated component of your instance. This page describes both forms, what your identity provider must receive, the mapping between groups and roles, and the creation of accounts at first sign-in.

Before you start

• The tab lives under "Settings", "Users & Access", sub-tab "SSO". It requires the manage:sso permission; without it, the tab shows "Managing single sign-on requires the manage:sso permission."
• The tab holds two cards: "Require SSO sign-in" and "Identity Providers", with two add buttons, "OIDC" and "SAML".
• The mapping between groups and roles uses the numeric identifier of Ctadel roles. Prepare the roles in the "Roles" sub-tab before configuring the provider; see Users and roles.

OIDC provider

The "New OIDC provider" form asks for:

Field	Content
"Display name"	The name of the button on the sign-in page
"Issuer URL"	Your provider's issuer URL; discovery reads <issuer>/.well-known/openid-configuration
"Client ID" and "Client secret"	The application registered with your provider
"Scopes"	openid profile email by default; add groups or your provider's equivalent to receive groups
"Groups claim"	The name of the claim carrying the groups, groups by default
"Default role ID"	Optional: the role given to everyone who signs in through this provider
"Enabled", "Default", "JIT"	Three switches; "JIT" allows account creation at first sign-in

The name, issuer and client ID are required. After "Create", the tab shows: "{name} created. Add this exact redirect URI in your identity provider's authorized callbacks:" followed by the address to copy, of the form https://<CUSTOMER>.ctadel.eu/api/auth/callback/oidc-<ID>. This "Redirect URI" stays visible on the provider's row.

The client secret is encrypted before storage and never shown again. The "Test" button reads the issuer's discovery document and answers "Provider reachable" or "Provider unreachable".

SAML provider

The "New SAML provider" form asks for:

Field	Content
"Display name (e.g. Okta SAML)"	The name of the button on the sign-in page
"IdP metadata:"	Either "URL" (the address of the metadata published by your provider) or "XML" (the document pasted as is); one of the two, not both
"Groups attribute (default: groups)"	The SAML attribute carrying the groups
"Default role ID (optional)"	As for OIDC
"Enabled", "Default", "JIT"	As for OIDC

Your identity provider needs two values, shown on the provider's row with a copy button:

• "ACS URL", where it posts the SAML response: https://<CUSTOMER>.ctadel.eu/jackson/api/oauth/saml.
• "Entity ID", the identifier of Ctadel as a service provider: https://<CUSTOMER>.ctadel.eu.

Your provider's metadata are kept by your instance. Only the addresses the browser and your provider need (authorization, token, ACS) are reachable from the Internet. The "Test" button of a SAML provider checks that your instance's SAML endpoint answers, not that your provider is reachable.

Mapping groups to roles

At every sign-in, Ctadel recomputes the roles managed by SSO:

1. The "Default role ID" when set.
2. For each group received in the configured claim or attribute, the role named in the group-to-role mapping, entered one line per mapping as group-name=role-ID ("One mapping per line: IdP group name = Ctadel role ID. Empty = no mapping.").

Assignments coming from SSO are wiped and rewritten at every sign-in: a person removed from a group on your side loses the matching role at their next sign-in. Roles granted by hand under "Users" are left untouched. A role deleted since the mapping was written is skipped and logged, without blocking the sign-in.

Account creation at first sign-in

With "JIT" on (the default), an unknown person who authenticates with your provider gets a Ctadel account: address and name received from the provider, no password, address considered verified. With "JIT" off, only people who already have an account (invited beforehand) can sign in; the others are refused.

An existing account with the same address is attached to the SSO identity in two cases: a SAML provider, or an OIDC provider that asserts it verified the address (email_verified, or xms_edov for Microsoft Entra). Otherwise the sign-in is refused and logged, so that a provider where anyone picks their own address cannot take over an existing account.

An account created by SSO cannot use a password or "Forgot password?". It does not go through the emailed sign-in code either.

Editing a provider without losing the secret

The "Edit" button opens the "Edit {name}" form. Only the changed fields are sent.

• OIDC: "Display name", issuer, client ID, "Client secret" ("Leave empty to keep the current secret; type a new one to rotate it."), scopes, groups claim.
• SAML: "Display name" and groups attribute. "The IdP metadata cannot be changed here: delete the provider and create it again to point it at another IdP."
• Both: "Default role ID", the group-to-role mapping, "Enabled", "Default", "JIT".

Only one provider can be "Default"; ticking one removes the flag from the other. Changes apply at the next sign-in attempt, without a restart.

Requiring SSO sign-in

The "Require SSO sign-in" card holds a switch: "When on, only configured SSO providers can sign in. Password and OAuth (Google, GitHub) login are blocked." Two guards prevent locking the instance:

• The switch refuses to turn on without an enabled provider.
• While it is on, disabling or deleting the last enabled provider is refused: "SSO sign-in is required and this is the last enabled provider: turn off "Require SSO sign-in" first, or nobody could sign in."

If your provider becomes unreachable while the requirement is on, the sign-in page shows "SSO is required but not configured" and the recovery path: at your request, the Ctadel team restores password sign-in on your instance for the time of the repair. This recovery mode cannot be enabled from the application.

The sign-in page

On /login, each enabled provider appears as a "Sign in with {name}" button, the "Default" provider first. Below, "or sign in with email" precedes the password form, hidden when SSO sign-in is required. The button sends you to your provider, and the session opens on return.

Limitations

• The group-to-role mapping is entered after creation, under "Edit".
• A role is designated by its numeric identifier, not by its name.
• For a SAML provider, "Test" checks your instance, not your provider; the only real check is a sign-in.
• SAML metadata cannot be edited: delete and recreate the provider.
• Deleting a provider does not delete the accounts it created: "Users linked to this provider will no longer be able to sign in via this flow." They stay listed under "Users".
• SSO sign-ins and refusals are logged server-side, but no screen of the application shows that log.
• No SCIM provisioning, no single logout (SLO).
• OIDC scopes are not universal: Google rejects groups, and other providers only return groups once configured on their side.