Skip to main content

api-gateway-rbac-strategy

ARCHIVED AND SUPERSEDED

This ADR is obsolete and has been superseded by ADR-0019: API Gateway RBAC via External Auth. The content below is for historical purposes only.

0018: API Gateway RBAC Strategy

Date: 2025-08-11

Status: Superseded by ADR-0019

Context​

This ADR proposed implementing RBAC via a custom Traefik plugin. This approach was rejected because it couples the authorization logic to a specific gateway technology, which violates the project's goal of being gateway-agnostic.

The API Gateway is responsible for initial, coarse-grained authorization. While the iam-service issues tokens with user roles, the gateway needs a standard mechanism to enforce access control based on these roles before forwarding a request to an upstream service. This prevents unauthorized requests from even reaching the internal network, providing a critical layer of defense.

Decision​

We will implement Role-Based Access Control (RBAC) on the API Gateway using a middleware that inspects the roles claim of the validated JWT.

  1. JWT roles Claim: The iam-service will issue JWTs containing a roles claim. This claim will be an array of strings, where each string is a role name (e.g., ["user", "admin", "accountant"]).

  2. Gateway Middleware: A middleware (e.g., a custom Traefik plugin or a standard claims-checking middleware) will be applied to routes that require role-based authorization.

  3. Route Configuration: Routes requiring specific roles will be annotated with the required role(s). For example, a Kubernetes HTTPRoute might have an annotation like:

    metadata:
      annotations:
        citadel.castlecraft.co.in/required-role: "admin"

  4. Enforcement Logic:

    • The middleware will extract the roles array from the JWT payload.
    • It will check if the array contains the role specified in the route's configuration.
    • If the required role is present, the request is forwarded to the upstream service.
    • If the required role is not present, the gateway will immediately reject the request with an HTTP 403 Forbidden status code.

Consequences​

Positive​

  • Defense in Depth: Provides a strong security layer at the edge, protecting internal services from unauthorized traffic.
  • Declarative: Authorization rules are declared alongside routes, making the security policy easy to understand and audit.
  • Efficient: Offloads basic authorization checks from every upstream service.

Negative​

  • Coarse-Grained Only: This mechanism is only suitable for coarse-grained checks. Fine-grained, attribute-based access control (ABAC) remains the responsibility of the individual services.
  • Configuration Management: Requires a disciplined approach to managing route annotations to keep the security policy consistent.