Skip to content

Authentication & IAM Spec (v0)

Date: 2026-02-07

Summary

Introduce a unified IAM service that provides authentication for human principals, tenant-scoped SSO, local users, API tokens, and MFA. IAM owns permissions and scopes as the single source of truth.

Goals

  • API-first authentication for human users.
  • Support local users and tenant-scoped SSO (OIDC + SAML).
  • Provide user-created API tokens with scoped permissions.
  • Require MFA for sensitive actions based on tenant policy.
  • Record MFA signals from IdP assertions for auditability.

Non-Goals (v0)

  • Service accounts or machine identities (M2M).
  • Full SCIM provisioning (future).
  • Passwordless login (future).
  • Multi-IdP per tenant (future).

Architectural Recommendation

IAM Service (Authn + Authz integration)

Start with a unified IAM service for velocity and fewer dependencies. Internally separate authn and authz modules to allow a future split only if required.

Future Split (Optional)

If scale or org structure demands it later, consider a split. Ensure token formats and contracts remain stable to avoid breaking changes.

Tenancy & IdP Model

  • One IdP configuration per tenant (v0).
  • Each tenant can be configured for either OIDC or SAML (or both, but one active at a time).
  • Login discovery via explicit tenant slug or email domain routing.

Tenancy & Isolation Requirements

  • All IAM data is tenant-scoped; user actions are additionally workspace-scoped where applicable.
  • Tokens must include tenant_id and active workspace_id context for downstream authorization.
  • API handlers must reject tenant/workspace mismatch between token context and requested target objects.
  • Cross-tenant user, token, role, and policy access is out of scope for v0 product flows.
  • Tenant Admin operations that span workspaces must be explicit and auditable (for example, workspace owner transfer).

Identity Model

  • User: human principal.
  • ExternalIdentity: IdP subject linkage.
  • APIToken: user-created token with scopes.
  • MFACredential: TOTP (v0), WebAuthn (v1).

Authentication Methods

Local Auth

  • Email/username + password.
  • Password reset (email + token).
  • MFA policy enforced per tenant.

SSO

  • OIDC Authorization Code + PKCE.
  • SAML 2.0 SP-initiated.
  • IdP is responsible for MFA policy. IAM records MFA assertion details when provided.

MFA (Local)

Phase 1 (v0): TOTP + Backup Codes

  • TOTP enrollment with QR code.
  • Backup codes generated and stored hashed.
  • MFA required for sensitive actions per tenant policy.

Phase 2 (v1): WebAuthn/Passkeys

  • Add support for passkeys and security keys.
  • Used as alternative or additional factor.

MFA Policy (Tenant-Level)

  • mfa_mode: OFF | OPTIONAL | REQUIRED
  • mfa_required_actions: list of actions requiring MFA for local users.

Recommended defaults: - mfa_mode = REQUIRED - mfa_required_actions = [LOGIN, CREATE_PAT, ROTATE_PAT, REVOKE_PAT, CHANGE_PASSWORD, MANAGE_USERS, UPDATE_IDP_CONFIG]

API Tokens (PATs)

Format

  • Opaque, random token. Stored hashed.
  • Returned once at creation.
  • Default expiration: 90 days.
  • Rotatable and revocable.

Scope Model

  • Token scopes map to registered permissions from IAM.
  • Effective permissions:
  • user_permissions ∩ token_scopes

Validation Rules

  • Token hash match.
  • Not revoked.
  • Not expired.

JWTs

  • JWTs used only for short-lived access tokens (15-60 minutes).
  • PATs are not JWTs.

Authz Integration

  • IAM resolves authenticated user and token scopes.
  • Authz evaluates permissions using existing registry.
  • Services enforce locally using middleware with consistent permission names.

Data Model (Conceptual)

User

  • id
  • tenant_id
  • email
  • status (active/disabled)
  • password_hash (local only)
  • created_at, updated_at

ExternalIdentity

  • id
  • user_id
  • provider_type (oidc|saml)
  • issuer
  • subject
  • created_at

APIToken

  • id
  • user_id
  • name
  • token_hash
  • scopes (list)
  • expires_at
  • created_at, last_used_at
  • revoked_at

MFACredential (TOTP)

  • id
  • user_id
  • type (totp)
  • secret_encrypted
  • enabled_at
  • last_used_at

MFABackupCode

  • id
  • user_id
  • code_hash
  • used_at

TenantIdPConfig

  • tenant_id
  • provider_type (oidc|saml)
  • issuer (oidc)
  • client_id
  • client_secret_encrypted
  • saml_metadata
  • created_at, updated_at

TenantMfaPolicy

  • tenant_id
  • mfa_mode
  • required_actions (list)
  • created_at, updated_at

API Surface (v0)

Authentication

  • POST /auth/login (local)
  • POST /auth/logout
  • POST /auth/password/forgot
  • POST /auth/password/reset

SSO

  • GET /auth/sso/:tenant/start (OIDC or SAML)
  • POST /auth/sso/:tenant/callback
  • GET /auth/sso/:tenant/metadata (SAML)

MFA (Local)

  • POST /mfa/enroll/start
  • POST /mfa/enroll/confirm
  • POST /mfa/challenge
  • POST /mfa/backup-codes/regen

Token Management

  • POST /tokens
  • GET /tokens
  • POST /tokens/:id/rotate
  • DELETE /tokens/:id

Permissions (from IAM)

  • GET /permissions

User & Tenant Admin

  • GET /me
  • GET /users/:id
  • POST /users
  • PATCH /users/:id
  • POST /users/:id/disable
  • POST /workspaces/:id/owner-transfer
  • GET /tenants/:id/idp
  • POST /tenants/:id/idp
  • PATCH /tenants/:id/idp
  • DELETE /tenants/:id/idp
  • GET /tenants/:id/mfa-policy
  • PATCH /tenants/:id/mfa-policy

Flows

Local Login (with MFA)

1) User submits credentials. 2) IAM validates password. 3) If tenant policy requires MFA for LOGIN, issue MFA challenge. 4) On success, issue short-lived JWT + refresh token or session.

PAT Creation (MFA Required)

1) User requests new PAT with scopes. 2) If MFA required for CREATE_PAT, challenge. 3) IAM creates token, returns full token once.

SSO Login

1) Redirect to IdP (OIDC/SAML). 2) IAM validates assertion and extracts subject, email, and MFA details. 3) JIT provision or link user. 4) Issue short-lived JWT/refresh token.

MFA Assertion Logging (SSO)

  • Capture MFA data from OIDC claims (acr, amr) or SAML context.
  • Store on login event for auditing and support diagnostics.

Auditing & Observability

  • Log: login success/failure, MFA events, token create/rotate/revoke, IdP config updates, workspace owner transfer.
  • Metrics: login failure rate, MFA failure rate, token usage rate.

Security Requirements

  • Password hashing: Argon2 or bcrypt.
  • Rate limiting on auth endpoints.
  • Token hashing and secure storage for secrets.
  • Enforce token expiration (90 days default).
  • Encrypt IdP client secrets and MFA secrets at rest.

Open Questions

  • Do we require step-up MFA for SSO sessions on sensitive actions?
  • Should refresh tokens be rotated on every use?
  • Default session model for UI vs API-only clients?

Next Steps

  • Confirm MFA step-up policy for SSO.
  • Define exact permission registry schema for token scopes.
  • Decide on refresh token design (rotating vs fixed).