Skip to main content

IAM and Access Service implemented

This page is the detailed engineering packet for the shared IAM and access boundary.

Scope​

IAM / Access owns:

  • organizations, departments, and projects
  • memberships and role bindings
  • scopes and entitlement-bearing identities
  • service accounts and API-key lineage
  • product authorization evidence

It does not own provider authentication truth for humans. Keycloak handles authentication and federation; platform IAM remains the product authorization authority.

Context​

Core Data Model​

The stable hierarchy is:

organization -> department -> project -> principal

Main principal classes:

  • human user
  • service account
  • group

Service accounts are project-scoped and should use short-lived tokens.

Main Contract Surfaces​

SurfacePurpose
/access/*user/admin access and membership surfaces
/iam/*platform IAM and read/write controls
service account APIsmachine principal lifecycle
scope registryproduct-scoped authorization vocabulary

Key Flows​

Human authorization​

  1. user authenticates with Keycloak or another upstream IdP
  2. API validates token locally
  3. platform IAM resolves membership, role, scope, and project authority
  4. product route applies ownership and authz checks

Service account flow​

  1. project admin creates service account
  2. service account receives scoped credential material
  3. automation mints short-lived bearer tokens
  4. API enforces project scope and route allowlist

Security Model​

  • provider IdP is authentication authority
  • platform IAM is authorization authority
  • service accounts are not MFA subjects
  • privileged mutations must be audited
  • cross-project or cross-tenant service accounts are not a default pattern

Failure / Recovery Model​

Failure classExpected posture
stale or invalid tokenfail closed
missing membership/scopefail closed
stale read model beyond budgetwrite paths reject or block
IdP unavailable but token still validlocal validation can continue within trust rules
Canonical sources