Skip to main content

0019: API Gateway RBAC via External Authorization

Date: 2025-08-11

Status: Accepted

Context​

The API Gateway must perform coarse-grained Role-Based Access Control (RBAC). The initial strategy (ADR-0018) proposed a custom Traefik plugin, but this couples our authorization logic to a specific gateway, violating the core principle of being gateway-agnostic. We need a portable pattern that works across different gateway technologies like Traefik, Kong, and APISIX, and aligns with the goal of having a translatable configuration.

Decision​

We will implement RBAC at the edge using the standard External Authorization pattern (i.e., an "auth subrequest").

  1. Mechanism: For routes requiring RBAC, the API Gateway will be configured to pause the incoming request and make a subrequest to a dedicated, internal authorization service.

  2. Authorization Service: The iam-service will expose a dedicated, high-performance endpoint for this purpose (e.g., POST /api/iam/check-access). This leverages an existing P0 service that already has the necessary user and role context, and the name avoids collision with the standard OAuth2 /authorize endpoint.

  3. Flow:

    • The gateway will forward the original request's headers (including the Authorization header with the token) and method/path information to the authorization service.
    • The iam-service will verify or introspect the token against the upstream IdP to ensure its validity.
    • The iam-service will inspect the user's authorization claims (roles, tenant membership) from its internal policy database.
    • If the user is authorized for the requested resource, the service will respond with an HTTP 200 OK along with authorization headers (e.g., X-User-ID, X-Tenant-ID, X-User-Roles).
    • If the user is not authorized, it will respond with an HTTP 403 Forbidden.
    • Note: The token itself is not modified or enriched. The IAM service returns authorization claims as HTTP response headers.

  4. Gateway Action: The API Gateway will proceed with or deny the original client request based on the status code of the authorization subrequest.

Consequences​

Positive​

  • Gateway Agnostic: This pattern is a standard feature in virtually all modern API gateways, ensuring our architecture is portable.
  • Simplified Gateway Config: The gateway configuration becomes much simpler and more declarative. It only needs to know where to send the auth subrequest, not how to perform the logic. This makes it far easier to translate between different gateway syntaxes.
  • Centralized Logic: All RBAC logic is centralized in a standard microservice, which can be tested and maintained independently.

Negative​

  • Network Hop: This pattern introduces an additional network hop for authorization. However, this is typically a low-latency call on an internal network, and the security and portability benefits are a worthwhile trade-off.
  • Increased Responsibility for IAM Service: This adds real-time authorization checks to the iam-service's responsibilities, which must be designed for high performance and availability.