Can we start without SSO?
Yes for a pilot. Use Cognito email auth with a named approver, MFA and invite rules, backup admin, and a dated SSO follow-up.
Check fallbackEnterprise identity
Enterprise SSO admin guide.
Configure Cognito-backed SAML or OIDC for human users, admins, and agent operators with explicit domain ownership, callback and logout URLs, claims mapping, workspace role assignment, testing evidence, troubleshooting, and rollback steps before broad customer invites.
SSO first decision
Start the pilot now. Require SSO before broad rollout.
When is SSO required?
Before broad enterprise invites. Prove SAML or OIDC, callback URLs, logout, claims, role mapping, and rollback first.
Review setupWhat must fail closed?
Unknown groups, privileged roles, billing access, agent identities, and SCIM deprovisioning stay blocked until approved.
See rolesNeed identity help?
Bring provider type, callback URLs, a redacted claim sample, expected role, actual role, and rollback owner. Do not send tokens.
Open SSO supportSSO assumptions
SAML, OIDC, and Cognito-only launches must name the accepted identity posture.
The enterprise packet should say which mode is active, who accepted it, and which Linear blocker tracks any remaining SSO limitation.
Cognito-backed SAML
Enterprise SAML federation terminates at Cognito and maps assertions into the workspace role model before the custom app session is issued.
Customer provides
- IdP metadata URL or signed metadata XML.
- Entity ID, SSO URL, signing certificate, and NameID format.
- Group or app-role claim names that can drive role assignment.
Cognito-backed OIDC
Enterprise OIDC federation uses Cognito as the relying party, validates issuer metadata, and converts ID token claims into workspace membership fields.
Customer provides
- Issuer URL, client ID, client secret handoff path, and JWKS availability.
- Allowed scopes such as openid, email, profile, and groups.
- Claim names for subject, email, display name, and group membership.
Cognito-only fallback
If enterprise SSO is not enabled for launch, the customer explicitly accepts Cognito email auth as a temporary limitation with a dated follow-up.
Customer provides
- Named approver for the SSO limitation.
- Accepted MFA and invite workflow for launch users.
- Target date or blocker issue for SAML/OIDC enablement.
Admin setup
Cognito federation, custom domains, callback URLs, claims, roles, and sessions all need separate rollback notes.
| Area | Admin action | Required evidence | Rollback |
|---|---|---|---|
| Cognito federation | Create the SAML or OIDC identity provider in Cognito, bind it to the app client, and keep provider secrets outside source control and Terraform state outputs. | Provider type, issuer/entity ID, metadata source, certificate expiry, and app client binding. | Disable the provider on the app client and return affected users to the accepted Cognito-only invite path. |
| Custom domain | Confirm the Cognito hosted auth domain or customer-facing auth subdomain, certificate, DNS ownership, and environment separation. | Domain, certificate status, DNS validation, environment, and owner approval. | Restore the previous hosted UI domain or remove the customer domain from the launch allowlist. |
| Callback and logout URLs | Allowlist exact callback and logout URLs for dev, staging, preview, and production before inviting customer users. | URL matrix covering login callback, logout return, app redirect, and blocked external redirect checks. | Revert Cognito app client callback/logout URLs to the last known good matrix. |
| Claims mapping | Map subject, email, display name, groups, workspace role, and billing admin claims into normalized workspace membership fields. | Claim table, sample redacted assertion or ID token, and validation result for every launch role. | Return unmapped users to read-only or disable SSO login until the role mapping is corrected. |
| Role assignment | Assign least-privilege workspace roles from IdP groups and require human approval for owner, admin, billing-admin, and agent roles. | Role mapping table, approver, backup admin, and emergency stop owner. | Remove the role mapping group or demote affected users to read-only while the customer owner reviews access. |
| Session security | Confirm MFA posture, token lifetime, session cookie settings, account recovery path, and audit events for login, logout, and role changes. | MFA decision, token/session lifetime, recovery owner, and audit smoke result. | Shorten session lifetime, revoke sessions, and pause invites until recovery and audit checks are healthy. |
Claims and role mapping
Role assignment fails closed when groups, workspace roles, or billing claims are unknown.
| Source claim | Target field | Validation |
|---|---|---|
| sub, NameID, or persistent identifier | externalSubjectId | Stable across logins and never reused for another person in the customer tenant. |
| Verified, lowercased, customer-owned domain unless an explicit guest exception exists. | ||
| name, given_name, family_name | displayName | Safe for UI display and not used for authorization decisions. |
| groups or memberOf | externalGroups | Group values are normalized and reviewed before they grant workspace roles. |
| buildr_plannr_role or group mapping | workspaceRole | Only allowed workspace roles are accepted; unknown roles fail closed. |
| billing_admin or finance group | billingAccess | Billing access is granted only to approved finance or workspace owner groups. |
SCIM provisioning
SCIM launch design treats deprovisioning as the critical path, not an afterthought.
Provisioning creates or updates memberships only after subject, email, group, and privileged-role checks pass. Deprovisioning disables workspace access, revokes sessions and tokens, preserves audit history, and reassigns open ownership before the customer treats the user as fully removed.
Configure tenant SCIM connector
Customer enables SCIM in their IdP or identity governance tool.
Identity owner: SCIM base URL, token handoff record, tenant ID, environment, and named owner.
Provision or update users
SCIM `User` create or patch includes an active user and verified email.
Workspace admin: External ID, normalized email hash, expected role, workspace membership, and audit event.
Sync groups to roles
SCIM `Group` create, patch, or membership change maps to workspace roles.
Security owner: Group ID, mapped role, approver, privileged-role review, and rejected unknown groups.
Deactivate and revoke access
SCIM `active=false`, group removal, IdP disablement, or delete request.
Security owner: Membership disabled timestamp, session revocation, API token revocation, and reassignment note.
Review launch and recurring evidence
Enterprise launch, quarterly access review, or identity incident.
Compliance owner: Provisioning sample, deprovisioning sample, exception list, and owner signoff.
| SCIM field | Target field | Validation |
|---|---|---|
| id or externalId | externalSubjectId | Stable per customer tenant and never reassigned after deprovisioning. |
| userName | Lowercased, verified, and matched to the SSO email claim before workspace access. | |
| name.formatted or displayName | displayName | Display-only and never used for authorization decisions. |
| active | membershipStatus | `false` disables the membership, revokes sessions, and blocks agent/API activity. |
| groups[].value | externalGroups | Only approved groups map to roles; unknown groups fail to read-only with audit evidence. |
| urn:buildr-plannr:role | workspaceRole | Optional extension must match the allowed role catalog and privileged review rules. |
| Trigger | Action | Evidence |
|---|---|---|
| `active=false`, user delete, or IdP suspension. | Disable workspace membership immediately while preserving immutable audit history. | Membership ID, external subject, trigger, timestamp, and actor. |
| Any user deactivation or privileged-role removal. | Revoke app sessions, Cognito refresh tokens where available, API keys, and agent tokens. | Revocation event IDs, affected token classes, and validation result. |
| Owner, admin, reviewer, or assignee is deprovisioned. | Move approvals, ownership, support escalations, and pending agent reviews to backup owners. | Old owner, new owner, affected records, and customer acceptance. |
| SCIM delete request for a user with audit, billing, or agent evidence. | Treat as disable unless legal deletion workflow is explicitly approved and evidenced. | Deletion decision, retention reason, and data protection owner. |
Testing and troubleshooting
Test login, callback, logout, claims, roles, and admin references before inviting broad customer users.
Validate IdP metadata and Cognito provider status
Auth owner: Provider ID, issuer/entity ID, certificate expiry, and app client binding.
Run login, callback, app redirect, and logout smoke tests
QA owner: Browser evidence for /login, callback return, /app, logout, and denied external redirects.
Verify claims and role assignment with test users
Security owner: Redacted token/assertion sample, expected role, actual role, and audit event.
Review admin surfaces before broad invites
Workspace admin: Workspace settings, admin diagnostics, support path, and emergency owner confirmation.
Rollback steps
Pause broad customer invites
Launch owner: Linear blocker, customer notification draft, and invite freeze timestamp.
Disable or detach the failing Cognito identity provider
Auth owner: Provider/app client change, previous config reference, and rollback approver.
Revoke affected sessions and reset fallback access
Security owner: Session revocation note, impacted users, and recovery path.
Restore the last known good callback/logout URL matrix
Infra owner: Environment, domain, callback URL, logout URL, and DNS status.
UI references
LoginCustom Cognito-backed login entry point for SSO and fallback auth smoke tests.Verify accountAccount verification surface used when Cognito-only fallback remains active.Workspace settingsProtected admin/user-facing control area for support, policy, API, migration, and SSO guidance.Admin diagnosticsProtected operational surface for auth, Cognito, audit, and integration readiness review.Security pagePublic control narrative for supervised automation, auth, agent tokens, and tenant boundaries.Enterprise SSO supportSupport path for identity blockers, callback issues, and role mapping failures.
Need help?
SSO support starts from provider, URL, claim, role, session, and audit evidence, not screenshots with tokens or private customer data.
Include the Linear blocker, environment, provider type, callback/logout URL matrix, redacted claim sample, expected role, actual role, and rollback owner.