Enterprise OIDC SSO & SCIM Users
This implementation supports app/environment-scoped OpenID Connect Authorization Code sign-in with S256 PKCE and preprovisioned SCIM User identities. It is not SAML, a directory-sync certification, SCIM Groups, just-in-time signup or email-based linking. Enterprise identities cannot sign into the Auth Security Portal, claim a personal email account, or obtain portal/organization roles automatically. An app owner/admin manages each connection separately from consumer login toggles.
1. Platform operator
Apply the release’s reviewed additive migration before deploying, initially with ENTERPRISE_SSO_ENABLED=false and ENTERPRISE_SCIM_ENABLED=false. Supply a protected ENTERPRISE_ENCRYPTION_KEYS_JSON keyring of id/key entries (canonical base64 32-byte encryption keys) and ENTERPRISE_ACTIVE_KEY_ID. Keep old keys while stored client secrets and pending requests need them. NEXT_PUBLIC_APP_URL must be the exact trusted HTTPS Auth origin. Activate each feature deliberately and redeploy; no example keys or live IdP connection is provided. The ordinary maintenance job expires consumed/pending login requests after ten minutes. Third-party app developers do not edit Aelith’s platform environment variables.
2. App owner/admin and identity-provider administrator
- In App → Enterprise, choose the intended environment. Register one exact app return URL in that environment; it must have only one environment owner. Hosted return URLs use HTTPS; native return URLs use Auth’s existing exact reverse-domain/custom-link rules.
- In your IdP, register a confidential OIDC client with the Auth callback
https://YOUR_AUTH_ORIGIN/api/enterprise/callback. Require authorization code, S256 PKCE, client_secret_basic, RS256 or ES256 ID tokens, nonce and a fresh integer auth_time in response to max_age=0/prompt=login. The issuer, authorization, token and JWKS endpoints must be public HTTPS on port 443 and share the same origin; explicit endpoint metadata is used, not arbitrary discovery. - Save a new connection with the exact issuer string, endpoints, client ID and client secret. It starts off. Secrets are encrypted server-side, never included in client configuration or list responses. Configuration values are immutable; replace a connection rather than silently rebinding its existing identities to another issuer.
- Generate a scoped SCIM provisioning token and copy it once into your IdP’s protected provisioning configuration. Combine your trusted Auth origin with the connection’s displayed
/api/scim/CONNECTION_ID/v2base. Token rotation immediately invalidates the previous token; revocation is independent of SSO. Never place this bearer token in an app. - Map SCIM externalId to the exact, case-sensitive OIDC sub for this client. Pairwise subjects must match the client-specific sub; an email address is not an acceptable substitute unless your IdP explicitly uses it as its stable verified subject. SCIM userName/displayName are directory metadata, not verified Auth email ownership. Provision users, then explicitly enable the SSO connection.
New connections/users are not marked Verified. Operator readiness, an On setting, a SCIM 201 or an IdP callback does not prove your customer application completed sign-in. Use a controlled real app sign-in and backend session validation before rollout; enterprise connections are not wired into the consumer-method connection-test Verified workflow yet.
3. Developer integration
Hosted app login pages show enabled workplace connections only for the exact callback’s active environment. Native apps fetch /api/enterprise/options?client_id=CLIENT_ID&redirect_uri=EXACT_RETURN_URL and open /api/enterprise/authorize in the system authentication browser with client_id, connection_id, redirect_uri and original response_type=code, code_challenge, code_challenge_method=S256, state and nonce. The source SDK enterpriseAuthorizationUrl builds this URL; SDK publication is separate. Retain the client verifier/state/nonce securely and use the existing native token/session/refresh/logout helpers. The IdP PKCE verifier is separate and remains encrypted on Auth’s server. Login processing, cancellation and completion are distinct one-use states. Logout/expiry during IdP exchange cannot complete; request-to-grant lineage also cancels a code or session issued in a late callback race without revoking an unrelated attempt. A pending browser proof is retained while Auth MFA is unfinished, then expires after ten minutes. Native custom-return redirects contain only one-time code/state; redeem via the existing /api/oauth/token. Replays, wrong verifier/client/redirect and deprovisioned users fail. Hosted web uses the existing token callback contract: validate on your backend, avoid URL logging, clear the URL and establish your own app session.
MFA and session boundaries
SSO preserves original request time, tenant scope and connection revision through Auth MFA and native code redemption. An already-enabled Auth factor is required, not bypassed; completing enterprise MFA never creates an Auth portal cookie. Enterprise identities have no consumer provider/password/email credentials. Self-service Auth factor enrollment/account linking for these isolated identities is not exposed by the current enterprise flow; configure enterprise MFA at your IdP and assess any additional Auth factor requirements before live rollout. Native refresh remains separately opt-in. The SCIM resource id equals the Auth user ID (JWT sub). Signed hosted/native access and refresh tokens include enterprise_connection_id and enterprise_environment_id; successful backend /api/verify also returns authoritative enterprise connectionId/environmentId. Tenant events include enterpriseConnectionId. Use these verified identifiers with your own business roles; do not infer a company from email/userName or treat membership as an automatic admin grant. Server verification checks current app/environment/identity/connection state; offline JWKS checks alone cannot detect revocation.
SCIM protocol surface
Bearer-authenticated ServiceProviderConfig, Schemas and ResourceTypes describe the supported User surface. Users supports create/read/list/replace/PATCH/deactivate/delete. Supported fields are immutable externalId, ASCII userName (case-insensitive uniqueness), displayName and active. There are at most 10,000 active/retired provisioned identities per connection. Pagination uses startIndex/count (up to 100); filtering supports userName, externalId or id eq a quoted string. Unsupported filters/attributes, bulk, sorting, password changes and Groups are rejected; this is a bounded SCIM subset, not full interoperability certification.
PUT/PATCH honor If-Match against returned weak ETags. PATCH supports add/replace for userName/displayName/active and remove for displayName. Deactivation revokes scoped sessions and preserves a cutoff; reactivation requires fresh sign-in and does not clear app-admin suspension. DELETE is an idempotent deactivation/tombstone: retired externalIds/userNames cannot be reused; use active=false for reversible offboarding. No global user, other tenant or portal account is deleted. Namespace foreign keys prevent hard-deleting a populated connection/environment and thereby turning retained enterprise users into ordinary Auth accounts; hard deletion/retention cleanup is not exposed by this release. Duplicate create returns 409; retrieve by externalId before retrying provisioning. Deactivation and login serialize through the app lock. Directory metadata updates do not claim verified email or merge identities.
Recovery and testing
Disabling a connection blocks scoped sessions and pending proofs, preserves a permanent authentication cutoff, and revokes its SCIM token; re-enabling cannot resurrect old sessions. Safety disable/revoke controls remain available when platform flags/keys are unavailable. Keep enforcement code/schema deployed after use; simply downgrading to code that ignores enterprise identity restrictions is unsafe. Local test IdP uses real fixture signatures and mocked network, provisioning and clients; those tests are not a live IdP certification or a production connection test. Actual IdP setup, credentials, user provisioning/sign-in and deployment require separate action approval.
Protocol references: OpenID Connect Core, SCIM Core Schema, SCIM Protocol.