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 two 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 Attributes.

    • Data Model: Tenant, UserPolicy, Attribute.
    • 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).

API Contract: System Endpoints​

The iam-service exposes system-level endpoints for the API Gateway and other internal services.

1. Claims Enrichment​

  • 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
    • Note: Roles are now implemented as attributes. There is no separate X-User-Roles header.
  • 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. This allows context-less operations like GET /me/tenants.

2. User Query​

  • Endpoint: POST /v1/system/users/query
  • Description: Allows internal services to query user information based on various criteria (e.g., upstream ID, tenant ID).
  • Input: JSON body with query filters.
  • Output: JSON array of matching user objects.

3. Tenant Query​

  • Endpoint: POST /v1/system/tenants/query
  • Description: Allows internal services to query tenant information.
  • Input: JSON body with query filters.
  • Output: JSON array of matching tenant objects.

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.