Skip to main content

IAM Service

The IAM (Identity and Access Management) service is a foundational component within the Citadel platform, primarily serving as a Policy and Claims Enrichment Engine. It provides administrative APIs for managing Citadel-specific authorization policies and enriches user claims from an upstream Identity Provider (IdP) for consumption by other services.

Important: This service is not an OIDC provider and does not handle user authentication or credential management. The upstream IdP is the single source of truth for identity.

Key Responsibilities​

The iam-service has three core responsibilities:

  1. Policy Management: The service is the authoritative source for managing Citadel-specific authorization policies. This includes the data models and administrative APIs for Tenants, Users (as policy objects), and Roles.

    • Data Model: Tenant, UserPolicy, Role.
    • Administrative APIs: RESTful endpoints for CRUD operations on these policy objects.

  2. Claims Enrichment: At runtime, the service's key responsibility is to enrich authorization tokens with Citadel-specific context. The API Gateway, after validating a user's token from the upstream IdP, will make a sub-request to the iam-service. The iam-service will then look up the user's policy and return enriched claims (e.g., x-tenant-id, x-user-roles).

  3. IdP Provisioning (Administrative): The service performs limited, administrative interactions with the upstream IdP, exclusively for the purpose of provisioning and managing OAuth2 clients.

API Contract: Claims Enrichment Endpoint​

The primary runtime interaction is between the API Gateway and the iam-service via the POST /v1/system/enrich-token endpoint.

  • Endpoint: POST /v1/system/enrich-token
  • Description: Internal endpoint called by the API Gateway to enrich a validated upstream JWT with Citadel-specific policy claims.
  • Input: The API Gateway forwards the original request's Authorization: Bearer <token> header. For multi-tenant operations, it also forwards an X-Active-Tenant-ID header provided by the client.
  • Output (Success): On success, the iam-service returns a 200 OK response with the enriched claims set as response headers. The API Gateway copies these headers to the original request before forwarding it to the downstream service. The response body is ignored.
    • X-Tenant-ID: tenant-123
    • X-User-ID: user-abc
    • X-User-Roles: tenant-123:admin,tenant-123:user,global-role
  • Error Handling:
    • 403 Forbidden: Returned if the user is not a member of the tenant specified in X-Active-Tenant-ID.
    • 500 Internal Server Error: Returned for any unexpected server-side errors.
    • Note: If no X-Active-Tenant-ID is provided, the service returns a 200 OK with an X-User-ID header containing the upstream user ID, but with empty X-Tenant-ID and X-User-Roles headers. This allows context-less operations like GET /me/tenants.

Scoped Role Names​

To prevent tenants from creating roles with the same name as a global role (e.g., "Super Admin"), the X-User-Roles header uses a scoped format for tenant-specific roles: tenant_id:role_name. Global roles are passed by their name without a scope. Downstream services must parse these scoped names to make authorization decisions.

Integration into the Overall System​

The iam-service plays a crucial role in the Citadel platform's authorization flow:

  1. User Authentication: Handled by the upstream IdP.
  2. Client Provides Context: The client application sends the IdP token and an X-Active-Tenant-ID header to the API Gateway.
  3. Claims Enrichment: The API Gateway calls the iam-service's /system/enrich-token endpoint. The iam-service validates the user's membership in the hinted tenant and returns the appropriate claims.
  4. Internal Authorization: The API Gateway adds the returned claims as X- headers to the original request and forwards it to the downstream service.

This design ensures a clear separation of concerns, with the iam-service focusing solely on policy management and claims enrichment, while the upstream IdP handles core identity functions.