Enterprise identity
Configure Cognito-backed SAML or OIDC for governed agent planning with explicit domain ownership, callback and logout URLs, claims mapping, workspace role assignment, testing evidence, troubleshooting, and rollback steps before broad customer invites.
SSO assumptions
The enterprise packet should say which mode is active, who accepted it, and which Linear blocker tracks any remaining SSO limitation.
Enterprise SAML federation terminates at Cognito and maps assertions into the workspace role model before the custom app session is issued.
Customer provides
Enterprise OIDC federation uses Cognito as the relying party, validates issuer metadata, and converts ID token claims into workspace membership fields.
Customer provides
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
Admin setup
| 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
| 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. |
Testing and troubleshooting
Auth owner: Provider ID, issuer/entity ID, certificate expiry, and app client binding.
QA owner: Browser evidence for /login, callback return, /app, logout, and denied external redirects.
Security owner: Redacted token/assertion sample, expected role, actual role, and audit event.
Workspace admin: Workspace settings, admin diagnostics, support path, and emergency owner confirmation.
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.
Need help?
Include the Linear blocker, environment, provider type, callback/logout URL matrix, redacted claim sample, expected role, actual role, and rollback owner.