Documentation

Choosing between them

	Local accounts	SAML 2.0	OIDC	Token
Who it is for	People	People	People	Machines
Credential held by	The platform realm	Corporate directory	Corporate directory	The platform
Setup effort	None	Moderate	Low	None
Joiner and leaver handling	Manual, per account	Follows the directory	Follows the directory	Manual
Corporate password policy applies	No	Yes	Yes	n/a
Multi-factor	Configured in the realm	Inherited from the provider	Inherited from the provider	n/a
Single logout	n/a	Supported	Supported	n/a
Suitable for production	Break-glass only	Yes	Yes	Yes

If your corporate provider offers both, choose OIDC. It is materially simpler to configure, the failure messages are clearer, and there is nothing SAML does here that OIDC does not. Choose SAML when the corporate provider only speaks SAML, or when a security team requires it.

Local accounts are not an enterprise option. They are correct for an evaluation, for a very small deployment, and for the break-glass administrator every federated deployment should keep. Running an estate on them means maintaining a second user directory with its own joiners and leavers, and that directory will drift.

What federation does and does not change

Changes	Does not change
Who authenticates the user	What the user can do once in — roles and permissions stay in the platform
Where the password policy lives	The audit trail, which attributes actions the same way
How accounts are created — on first sign-in, from the group claim	Service accounts, which stay local
How leavers are handled — remove from the group	The need for a break-glass administrator

Federation moves authentication. It does not move authorisation: the group claim maps onto a platform role, and that role's permissions are still set under Roles and Permissions.

Planning a federation

Decide these before touching any configuration. Each one is painful to change afterwards.

1. The external address. It goes into the redirect URI, which must match exactly. Changing it later means changing it at the identity provider too, and a mismatch fails authentication with a clear error — which is at least a good failure.

2. The group-to-role mapping. Which directory groups map onto which platform roles. Keep it narrow, and especially keep the group that maps to administrator small enough to name the members of.

3. What happens to existing local accounts. A person with both a local account and a federated identity has two platform records. Decide whether to migrate the roles onto the federated record and delete the local one, and do it deliberately rather than discovering the duplicate later.

4. Where the client secret lives, and when it expires. This is the one that bites. The secret is shown once at creation and has an expiry date. When it expires, sign-in stops for everyone at once, with no warning and no symptom beforehand. Put the expiry date in a calendar that someone reads, and the secret in a credential store.

5. The break-glass account. A local administrator, strong password, in a credential store, tested after every change to the federation. The scenario it exists for is the one where the directory is unavailable or misconfigured — which is exactly when you cannot ask the directory team for help.

Rolling out safely

Configure the federation while local sign-in still works.
Test with one account that holds a non-administrative role.
Confirm the group claim arrives and maps to the expected role — a user who signs in successfully and sees nothing has authenticated but has no role.
Test single logout if you intend to use it.
Widen to a pilot group.
Keep local sign-in available throughout.
Once the pilot is clean, migrate the remaining users and retire their local accounts — except the break-glass one.

Token access for machines

Non-interactive callers do not use any of the above. An integration authenticates with its own service account and receives a short-lived session it renews; an agent authenticates with the host certificate issued when the host was registered. Neither path involves the corporate identity provider, which is deliberate: an automated job should not stop working because a directory is briefly unavailable.

Details are on Token Authentication and API Authentication.

When federation breaks

Symptom	Cause
Everyone's sign-in fails at once, with no change made	The client secret expired
Redirect URI error	The configured address and the registered URI differ — scheme, host or trailing path
Signs in, sees nothing	The group claim did not arrive, or maps to no role
Some users work, others do not	Those users are not in a mapped group
Sign-in loops back to the sign-in page	The public address does not match what the proxy forwards, or the forwarded-proto header is missing
Works internally, fails externally	Two addresses, one registered

In every one of these, the break-glass local administrator is how you get in to fix it.

CBOM Secure