Skip to main content

06 — Authentication Flow

Status: 🔧 Partial — confirmed sections complete; C-001 sections pending ITS Technical session
Prerequisite: TD2, TD3, 01 — Service Decomposition
Next: 07 — Authorization Model

End-to-end authentication design — how a request from a module reaches a Core engine with verified identity. Covers the two-identity model, the Identity Bridge, ITS SSO token flow, API key validation, token lifecycle, and sequence diagrams.

Sections marked ⏳ are blocked on the ITS Technical session (C-001). Everything else is confirmed from TD2 and TD3.

1. The Two-Identity Model​

Every request that reaches Core carries one of two identity types. There is no third option.

Identity typeWho uses itCredentialSet by
Human identityA Mumin taking an action in a module UIITS bearer token (JWT)Module — attaches the user's ITS session token
System identityA module background process, batch job, or automated workflowAPI keyModule — uses the key issued by Platform Admin at onboarding

The Identity Bridge at the API Gateway determines which identity type is present based on the Authorization header, validates it, and strips the credential before routing the request downstream. Core engines never see the raw token or API key — they only see the clean headers the Bridge sets.

Confirmed in TD3: ITS is the only identity provider on the platform. Core does not maintain its own user database. Core does not handle login or session management. A module's users are always ITS users.

2. Identity Bridge​

The Identity Bridge is the authentication layer inside the API Gateway. It runs before every request reaches any Core engine.

What it does​

Module request
    │
    ▼
┌─────────────────────────────────────┐
│           Identity Bridge           │
│                                     │
│  1. Detect credential type          │
│     (ITS token vs API key)          │
│                                     │
│  2. Validate credential             │
│     (signature, expiry, revocation) │
│                                     │
│  3. Extract identity                │
│     (itsId or moduleId)             │
│                                     │
│  4. Strip credential from request   │
│                                     │
│  5. Set clean headers               │
│     X-Its-Id, X-Module-Id,          │
│     X-Correlation-Id                │
└─────────────────────────────────────┘
    │
    ▼
Core engine receives clean headers only

What the engine sees​

After the Bridge processes a user-initiated request:

X-Module-Id:      vms
X-Its-Id:         ITS-1234567
X-Correlation-Id: 550e8400-e29b-41d4-a716-446655440000

After the Bridge processes a system-initiated request:

X-Module-Id:      vms
X-Correlation-Id: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
(no X-Its-Id)

Engines that require a human context check for the presence of X-Its-Id. If it is absent on an endpoint that requires it, the engine returns AUTH_ITS_ID_REQUIRED (403).

X-Correlation-Id lifecycle​

The module generates a UUID and sends it as X-Request-Id. The Bridge copies this value into X-Correlation-Id and forwards it downstream. From that point:

  • Every engine writes it to its logs on every log line for that request
  • If an engine makes an internal call to another engine, it forwards the same X-Correlation-Id so the chain stays traceable
  • The engine echoes it back as requestId in the response envelope — the module receives the same UUID it sent
  • The value has no storage lifecycle — it exists only in logs and the in-flight request

This means a single UUID traces a user action from the module → Bridge → engine → any internal engine calls → back to the module. If something fails anywhere in that chain, the requestId in the error response is enough to pull the full trace from logs.

What the Bridge rejects before routing​

ConditionError returned to module
Authorization header missing entirelyAUTH_INVALID_API_KEY (401)
ITS token signature invalidAUTH_ITS_TOKEN_INVALID (401)
ITS token expiredAUTH_ITS_TOKEN_EXPIRED (401)
API key not recognisedAUTH_INVALID_API_KEY (401)
API key revoked in Platform AdminAUTH_API_KEY_REVOKED (401)
Module API key calling a write endpointAUTH_MODULE_NOT_PERMITTED (403)
X-Module-Id header missing or not matching the keyAUTH_INVALID_API_KEY (401)

Rejected requests never reach the Core engine — the Bridge returns the error directly.

3. User-Initiated Flow (ITS SSO Token)​

A human user takes an action in a module UI. The module calls Core with the user's ITS session token.

Sequence​

Key points​

  • The module backend attaches the user's ITS token to its Core call — the user is not calling Core directly
  • The ITS token is a short-lived JWT. The module is responsible for managing token refresh in its own session handling
  • The Bridge validates the token on every request — there is no session state in the Bridge itself
  • X-Its-Id is set by the Bridge, not by the module. A module that passes X-Its-Id in its own headers has it overwritten by the Bridge

4. System-Initiated Flow (API Key)​

An automated module process calls Core without a human user in context — batch jobs, scheduled syncs, background workflows.

Sequence​

Key points​

  • API keys are issued per module at onboarding — one key per module, managed in Platform Admin
  • API keys are read-only by default. Write endpoint calls with a module API key are rejected at the Bridge before reaching the engine
  • A revoked API key is rejected immediately — no grace period
  • There is no X-Its-Id on system-initiated calls. Engines that require human context reject these with AUTH_ITS_ID_REQUIRED (403)

5. API Key Management​

ConcernDetail
IssuancePlatform Admin issues one API key per module at onboarding
ScopeRead-only access to all module-facing Core endpoints. Write endpoints require Platform Admin credentials.
RotationModule teams request key rotation through Platform Admin. Old key is valid for a 24-hour overlap window to allow the module to deploy the new key without downtime.
RevocationPlatform Admin can revoke a key immediately. Revoked keys fail at the Bridge — no grace period.
StorageModule teams must store API keys in their secrets management system. Keys must not be committed to source code or placed in environment files that are checked in.

6. ITS Token Validation​

⏳ Blocked on C-001 — ITS Technical session

The exact validation mechanism depends on how ITS issues and signs its tokens. The following describes the expected pattern — to be confirmed and completed after the ITS Technical session.

Expected token format​

ITS tokens are expected to be JWTs (JSON Web Tokens) carrying claims that include at minimum:

ClaimExpected valueNotes
sub or itsIdITS-1234567The Mumin's ITS identifier — exact claim name TBC in C-001
expUnix timestampToken expiry — Bridge checks this on every request
issITS issuer URLBridge validates the issuer matches the configured ITS endpoint — exact URL TBC

Expected validation steps​

  1. Parse JWT header to identify signing algorithm
  2. Fetch ITS public key (via JWKS endpoint or pre-configured public key — TBC in C-001)
  3. Verify signature
  4. Check exp — reject if expired
  5. Check iss — reject if not the configured ITS issuer
  6. Extract itsId claim — set as X-Its-Id

Token lifecycle​

⏳ TBC in C-001

  • Whether ITS issues refresh tokens alongside access tokens
  • Whether Core needs to handle token refresh on behalf of modules, or whether modules handle this in their own session management
  • Maximum token TTL and whether it can be configured per Miqaat

7. Platform Admin Authentication​

Platform Admin users are Mumineen — they have ITS IDs. They authenticate via ITS SSO exactly like any other user. There is no separate credential system for Platform Admin.

How it works​

  1. A Platform Admin user logs in to the Platform Admin console via ITS SSO
  2. The console receives their ITS bearer token
  3. When the console calls Core APIs, it attaches the token — same flow as any module
  4. The Identity Bridge validates the token and sets X-Its-Id to their itsId
  5. The Gateway checks whether that itsId holds the PLATFORM_ADMIN role in Core's RBAC
  6. If the role is confirmed, the request is routed — including to write endpoints and internal-only endpoints
  7. If not, the request is rejected with AUTH_MODULE_NOT_PERMITTED (403) regardless of token validity

What the PLATFORM_ADMIN role grants​

AccessRegular module userPLATFORM_ADMIN role holder
Read endpoints (C-010 to C-019)✅✅
Write endpoints (POST /v1/miqaat, POST /v1/rbac/assign, etc.)❌✅
Internal-only endpoints (GET /v1/audit/query, GET /v1/its/mumin/{itsId}, etc.)❌✅
Module API key issuance and revocation❌✅
Role assignment for all other roles❌✅

PLATFORM_ADMIN is a platform-level role — not Miqaat-scoped​

All other RBAC roles in Core are scoped to a miqaatId (e.g. VMS_Coordinator for MQ-1447-KHI). PLATFORM_ADMIN is different — it is scoped at the platform level, not per Miqaat. A Platform Admin user has elevated access across all Miqaats.

Bootstrapping — the first Platform Admin​

PLATFORM_ADMIN role assignment normally goes through the RBAC Engine write endpoint (POST /v1/rbac/assign). But that endpoint itself requires a PLATFORM_ADMIN role to call. This is a bootstrapping problem — who assigns the first Platform Admin?

This requires a seed process at Core deployment: a one-time script run during initial infrastructure setup that directly writes the first PLATFORM_ADMIN role assignment into the RBAC data store, bypassing the API layer. Only the Core technical team runs this, once, at deployment. All subsequent Platform Admin assignments go through the normal API flow by an existing Platform Admin.

⏳ Exact seed process and tooling — Infrastructure session

Multiple Platform Admins​

More than one itsId can hold PLATFORM_ADMIN. Each holds it as an individual — there is no shared account. Audit logs record which itsId performed each write operation, so every Platform Admin action is attributable to a specific person.

PLATFORM_ADMIN can be revoked by any other active Platform Admin via POST /v1/rbac/revoke. The platform must always have at least one active Platform Admin — the system should warn (not block) if the last Platform Admin attempts to self-revoke.

8. Internal Engine-to-Engine Calls​

Core engines occasionally call each other during request processing — for example, the Allocation Engine calling the Rule Engine before confirming an allocation.

These internal calls do not pass through the Identity Bridge. They use internal network credentials scoped to the Core infrastructure. The originating itsId is propagated through the X-Correlation-Id header for tracing — not through a new token.

⏳ Exact internal credential model TBC — Infrastructure session

9. Open Questions​

QuestionBlocked On
Exact ITS JWT claim name for itsIdC-001 — ITS Technical session
ITS JWKS endpoint URL and key rotation policyC-001
Token TTL and refresh mechanismC-001
Whether Bridge caches JWKS or fetches per requestInfrastructure session (performance trade-off)
Internal engine-to-engine credential modelInfrastructure session
Token revocation — does ITS support token introspection for mid-session revocation?C-001
PLATFORM_ADMIN seed process tooling and who runs it at deploymentInfrastructure session
Minimum Platform Admin count enforcement — warn vs hard block on last-admin self-revokeArchitecture decision