core/identity-gateway/docs/architecture.md

Architecture

identity-gateway is an internal authority for identity across the SaaS platform. It sits between human users and internal services, issuing trusted JWTs for service-to-service access.

Core responsibilities

• Central authentication and authorization.
• RBAC and permission enforcement per tenant.
• Token issuance for trusted backend services.
• Provider-agnostic identity validation (local/external).

Components

• Auth module: Handles login, refresh, and logout flows.
• Users module: Maintains internal user identities and tenant membership.
• Roles & Permissions: Defines RBAC primitives and tenant-specific grants.
• Sessions: Stores refresh token sessions.
• Core guards: Enforces authentication, roles, and permissions.

Trust boundaries

• Only internal services validate JWTs issued by the gateway.
• JWTs are not intended for public client apps without a proxy.

Data flow

1. User authenticates with identity-gateway.
2. Gateway validates identity via provider and maps user to tenant.
3. Gateway issues access + refresh tokens.
4. Internal services validate access token claims.