Skip to main content

Multi-Identity Provider (IdP) Support

Citadel's API Gateway is designed to support multiple Identity Providers (IdPs), allowing for flexible authentication flows based on the incoming request context. This document outlines how the API Gateway integrates with various IdPs, handles IdP discovery, and passes relevant context to downstream services.

Overview​

The API Gateway acts as a central point for routing authentication requests to the correct IdP and ensuring that the iam-service receives the necessary context to validate tokens and enrich claims. This multi-IdP capability is crucial for scenarios involving different user bases, organizational structures, or compliance requirements.

IdP Discovery Mechanism​

The API Gateway employs a URL-based discovery mechanism to identify the appropriate upstream IdP for an incoming request. This allows for distinct authentication flows or user populations to be served by different IdPs.

  • URL-based IdP Identification: The gateway analyzes the incoming request's URL (e.g., subdomain or a fixed path segment) to determine which IdP should handle the authentication. This enables routing requests for tenant-a.citadel.com to IdP A, and tenant-b.citadel.com to IdP B.

  • Default IdP Fallback: If the API Gateway cannot identify a specific IdP from the request URL, it is configured to fall back to a pre-configured default IdP. This ensures that requests without explicit IdP context are still handled gracefully.

Passing IdP Context to IAM Service​

Once an IdP is identified (either explicitly or via fallback), the API Gateway passes an explicit identifier for that IdP to the iam-service. This is typically done via a custom HTTP header, allowing the iam-service to perform IdP-specific token validation and claim enrichment.

  • X-Upstream-IdP-ID Header: The API Gateway injects an X-Upstream-IdP-ID HTTP header into the request before forwarding it to the iam-service. The value of this header is a unique identifier for the determined IdP.

Caching for Performance​

To optimize performance and reduce the load on the iam-service, the API Gateway implements caching mechanisms for IdP-related configurations and token validation results.

  • IdP Configuration Caching: Frequently accessed IdP configurations (e.g., public keys, issuer URLs) are cached at the gateway level.
  • Token Validation Caching: Results of token validation (e.g., whether a JWT is valid and unexpired) can be cached for a short duration, reducing redundant calls to the iam-service for subsequent requests with the same token.

These caching strategies significantly improve the responsiveness of the API Gateway and the overall user experience.

Configuration Example (Traefik)​

While the exact Traefik configuration will depend on the specific IdP setup, the following conceptual example illustrates how the gateway might be configured to handle IdP discovery and context passing:

# Example Traefik Router for a specific IdP
http:
  routers:
    my-app-idp-a:
      rule: "Host(`tenant-a.citadel.com`)"
      service: my-app-service
      middlewares:
        - idp-a-middleware@file

  middlewares:
    idp-a-middleware:
      headers:
        customRequestHeaders:
          X-Upstream-IdP-ID: "idp-a-identifier"
      # ... other authentication/authorization middlewares

# Example Traefik Router for the default IdP
    my-app-default-idp:
      rule: "HostRegexp(`{host:.+}`)" # Matches any host not matched by more specific rules
      service: my-app-service
      middlewares:
        - default-idp-middleware@file

  middlewares:
    default-idp-middleware:
      headers:
        customRequestHeaders:
          X-Upstream-IdP-ID: "default-idp-identifier"
      # ... other authentication/authorization middlewares

Note: The actual implementation may involve more complex routing rules, ForwardAuth configurations, and custom plugins depending on the specific requirements and Traefik version.