SSO and SCIM
Keeptrusts exposes organization connection administration and API handlers for OpenID Connect (OIDC), SAML 2.0, group-to-role/team mapping, and SCIM 2.0 provisioning.
Configure, test, and recover the connection before requiring it for all members.
:::warning Current console browser-flow boundary
The current console source does not implement the /sso/callback bridge that
its login flow supplies to OIDC and SAML providers. The SAML metadata download
also currently generates /auth/saml/callback, which is not a console route.
Connection administration and metadata tests do not make either browser flow
adoption-ready. Do not enforce SSO until a deployed console provides and
verifies the live callback bridge and corrected SAML metadata.
:::
Prerequisites
Prepare:
- an identity-provider administrator;
- a Keeptrusts identity administrator;
- the email-domain hint used for discovery, with domain ownership verified when the organization's enforcement policy requires it;
- OIDC discovery and client credentials, or SAML metadata;
- the roles and teams that groups should map to;
- a non-owner test user; and
- a documented emergency owner/recovery path.
Do not use the only active owner as the first SSO test account.
Configure OIDC
In Settings → Single Sign-On, create an OIDC connection and enter:
- a clear connection name;
- the OIDC discovery URL;
- client ID;
- client secret;
- email-domain hint.
Keeptrusts stores the client secret encrypted. On edit, leave the secret field blank to retain the current value.
The intended console callback is <console-origin>/sso/callback. Confirm that
the deployed console actually serves that bridge before registering it with
the identity provider, then match it exactly, including scheme, host, path,
and port. The route is absent from the current console source.
Configure SAML
For SAML, prefer the identity provider's metadata URL. Metadata XML can also be
provided when the deployment workflow requires it. The current console
download builds service-provider metadata with an
<console-origin>/auth/saml/callback assertion-consumer-service URL, but that
route is not implemented. Do not import it as a working production ACS. Wait
for corrected metadata that points at a verified live callback bridge, then
verify both its entity ID and ACS before testing.
Validate:
- metadata is parseable;
- signing certificate and endpoints are current;
- audience/entity ID matches;
- email and identity attributes map correctly; and
- clock synchronization is healthy.
Plan certificate rotation before expiry. Retain the old and new configuration only for the supported overlap period, then verify the final active certificate.
Test before enforcement
After the callback boundary above is resolved, use the console connection test, then complete a real sign-in with a non-owner account.
Verify:
- Domain discovery selects the intended connection from a verified domain or the enabled connection's domain hint.
- Authentication returns to the expected organization.
- Email and display identity are correct.
- Group mapping grants only intended teams and roles.
- Unmapped groups receive only the reviewed fallback role, if configured.
- Logout and a fresh login both work.
- The recovery owner can still access the organization.
A successful metadata test is necessary but not sufficient; complete an interactive login.
Map identity-provider groups
Configure the group-claim name and map exact IdP groups to Keeptrusts roles or teams. Optionally configure a fallback role for users with no matching group.
When sync on login is enabled, Keeptrusts re-evaluates mappings each time the user signs in. Test both adding and removing an IdP group so you know how access changes propagate.
Avoid mapping a broad default group to an owner or administrator role.
Enforce SSO
Enforcement requires organization members to sign in through SSO. Do not enable it in the current console build while the callback bridge is absent. For a build with that route corrected, enable enforcement only after the test checklist passes and the recovery procedure is owned.
Before switching it on:
- notify members and support owners;
- confirm the verified domain;
- confirm at least two tested administrative recovery owners;
- preserve the configuration and Trail reference;
- schedule a monitored window; and
- know the supported administrative recovery workflow for disabling enforcement if the primary identity-provider path becomes unavailable.
Do not enable enforcement to diagnose an untested connection.
Enable SCIM
SCIM lets the identity provider push user and group changes.
- Enable SCIM on the tested SSO connection.
- Copy the endpoint URL into the identity provider.
- Generate a bearer token.
- Copy the token immediately; it is shown only once.
- Store it in the identity provider's secret store.
- Test user creation, update, suspension/deprovisioning, and group change with a non-privileged test identity.
- Review the resulting member state and Trail records.
Do not send the SCIM token in email or tickets. Revoke it when exposed, unused, or replaced.
Deprovisioning checklist
SCIM deprovisioning should be tested end to end:
- IdP change reaches Keeptrusts;
- the member becomes inactive or loses the intended membership;
- group-derived roles are removed;
- direct assignments and independently issued tokens are reviewed;
- active sessions follow the organization's expected policy; and
- the action appears in Trail.
SCIM does not justify ignoring direct roles, tokens, or ownership transfers.
Troubleshooting
| Symptom | Check |
|---|---|
| Domain does not discover SSO | Entered email, verified-domain ownership where required, enabled connection, and exact domain hint |
| OIDC callback fails | Discovery URL, exact redirect URI, client ID/secret, issuer, and clock |
| SAML assertion rejected | Metadata, certificate, audience/entity ID, recipient, and time conditions |
| User signs in with wrong access | Group claim, exact group mapping, fallback role, sync-on-login state |
| SCIM returns unauthorized | Active token, copied value, endpoint URL, and IdP secret formatting |
| Removed group still grants access | Other teams, direct user roles, token roles, and next login/sync behavior |