Citadel IAM Authentication

Framework M provided native integration with Citadel IAM, a high-performance identity and access management service. This integration allows for enterprise-grade authentication and multi-tenancy resolution with minimal overhead.

---

Authentication Strategies

The Citadel Auth adapter supports two primary strategies, catering to different deployment architectures.

1. TRUST_PROXY (Internal/Legacy)

In this mode, Framework M trusts the upstream API gateway (like Nginx, Traefik, or a specialized IAM proxy) to handle authentication and populate identity headers.

Key Features:

• Performance: High performance as it avoids extra network calls for each request.
• Simplicity: Directly hydrates UserContext and TenantContext from headers.

Expected Headers:

• x-user-id: User's primary identity.
• x-service-id: Service identity (if no user is present).
• x-email: User's email address.
• x-user-roles: Comma-separated list of roles.
• x-scopes: Comma-separated list of service scopes.
• x-tenant-id: Verified primary tenant ID (set by IAM after validation).
• x-active-tenant-id: Selector/Hint passed by the user to request a specific tenant context.
• x-user-attributes: Base64-encoded JSON string containing user metadata.
• x-tenant-attributes: Base64-encoded JSON string containing tenant-level metadata.

2. ZERO_TRUST (Cloud-Native)

In this mode, Framework M extracts the user's Bearer token and performs a "Token Enrichment" call to the Citadel IAM service to validate and retrieve identity metadata.

Key Features:

• Security: Ensures every request is validated against the central IAM authority.
• Rich Context: Automatically populates advanced user attributes and organizational context.
• S2S Security: Uses a Service-to-Service (S2S) admin token to authorize enrichment requests.

---

Configuration

Citadel Auth can be configured via environment variables or the framework_config.toml file.

Environment Variables

Variable	Description	Default
AUTH_PROVIDER	Set to citadel to enable the provider.	default
CITADEL_IAM_STRATEGY	TRUST_PROXY or ZERO_TRUST.	ZERO_TRUST
CITADEL_IAM_SERVICE_URL	Base URL for the Citadel IAM service.	http://localhost:8080
CITADEL_S2S_TOKEN_ENDPOINT	URL to fetch the S2S admin token.	-
CITADEL_S2S_CLIENT_ID	Client ID for S2S authentication.	-
CITADEL_S2S_CLIENT_SECRET	Client Secret for S2S authentication.	-

Global Configuration (framework_config.toml)

[auth]
strategies = ["citadel", "bearer"]

[auth.citadel]
strategy = "ZERO_TRUST"
iam_url = "https://iam.your-domain.com"

---

Usage in Code

Authentication Chain

The Citadel strategy is automatically included in the authentication chain when configured. It will prioritize extracting identity from headers or tokens before falling back to standard JWT or Local auth.

from framework_m_standard.adapters.auth.strategies import create_auth_chain_from_config

# Factory creates the chain including CitadelAuth if set in config
auth_chain = create_auth_chain_from_config(jwt_secret="...")

# Middleware uses it to hydrate request.state.user
user_context = await auth_chain.authenticate(request.headers)

Context Mapping

The adapter automatically maps headers to the UserContext as follows:

• Identity: id is taken from x-user-id (if present) or x-service-id.
• Tenants: tenants is a list starting with x-active-tenant-id, followed by any additional IDs in x-tenant-id.
• Attributes:
  • x-user-attributes are decoded and merged directly into the root of UserContext.attributes.
  • x-tenant-attributes are decoded and placed under the tenant_attributes key in UserContext.attributes.
• Metadata: is_service and scopes are added to attributes if a service identity is used.

Token Enrichment (ZERO_TRUST)

When a Bearer token is received, the adapter calls: GET /api/iam/v1/system/enrich-token

The request includes:

• Authorization: Bearer <user_token>
• X-S2s-Token: <admin_token> (Managed by S2sClient)

The IAM response headers are then parsed using the same logic as the TRUST_PROXY mode, ensuring a consistent context regardless of the authentication path.