Modify Auth Service to Replace Token with User Metadata Headers #5

New issue

Closed

opened 2025-04-22 23:03:03 +00:00 by abed.alrahman · 2 comments

abed.alrahman commented

2025-04-22 23:03:03 +00:00

Member

Ref epic: #13

Goal: Enhance the forward authentication process so that the auth-service, upon successfully authenticating and authorizing a request, instructs Traefik to remove the original user token and inject user metadata (like ID, groups, roles) as headers before forwarding the request to the backend service.

Background:
To simplify backend microservices, we want them to receive clear information about the authenticated user directly via headers, rather than needing to parse and validate JWTs themselves. The auth-service, acting as the Traefik forwardAuth endpoint, is the ideal place to perform this token validation, extraction, and header preparation.

Description:
This ticket should modify the request processing flow. The auth-service should extract the user's token, verify it, and transform it into an object containing user information (username, email, groups, permissions, etc.). This metadata, represented as headers, will be handed off to downstream services, replacing the original token, so they can directly use this information for their internal permission checks.

Prerequisites:

The auth-service is implemented with a working /auth endpoint for Traefik forwardAuth. #3
Traefik is configured to use the auth-service for forward authentication for target services. #4

What needs to be done:

Modify auth-service (/auth endpoint logic):
    After successfully validating the incoming token and determining that the request should be allowed:
        Extract required user metadata from the validated token payload (or from a Keycloak userinfo call if needed). Define which fields are essential (e.g., User ID/Username, Email, Group Memberships, Realm Roles).
        Define a standard set of HTTP header names to carry this information (e.g., X-User-Id, X-User-Email, X-User-Groups, X-User-Roles). Ensure formats are consistent (e.g., comma-separated lists for groups/roles).
        Modify the /auth endpoint's success response (e.g., 200 OK) to include these defined headers with the extracted user metadata. (The auth-service doesn't modify the request directly; it sends these headers back to Traefik).
Update Traefik Configuration (via Labels):
    Modify the forwardAuth middleware definition in the Docker Swarm YAML labels for all services protected by the auth-service:
        Add or update the authResponseHeaders option to explicitly list the custom headers (e.g., X-User-Id, X-User-Email, X-User-Groups, X-User-Roles) that Traefik should copy from the auth-service's response onto the request being sent to the backend service.
        Ensure the original Authorization header is not included in authResponseHeaders.
        Verify Traefik's behavior regarding stripping the original client Authorization header after successful forward auth (this is usually the default).
Documentation:
    Document the new standard X-User-* headers (names, format, content).
    Clearly state that backend services protected by this mechanism must be updated to read these headers for user context and permission checks, instead of expecting a JWT.

Key Considerations:

Backend Service Impact: This change requires mandatory updates to all backend services relying on this authentication mechanism. They must adapt to consume the new headers.
Header Naming: Use a consistent prefix (like X-User- or X-Auth-) to avoid conflicts.
Data Selection: Only include necessary user metadata in headers to avoid excessive header size.

Deliverables:

Updated the auth-service source code.
Updated Docker Swarm YAML file(s) with modified Traefik forwardAuth labels for relevant services. // new ticket in IM repo
Documentation detailing the new headers and the required changes for backend services.

Ref epic: [#13](https://git.cleverthis.com/clevermicro/user-management/issues/13) Goal: Enhance the forward authentication process so that the auth-service, upon successfully authenticating and authorizing a request, instructs Traefik to remove the original user token and inject user metadata (like ID, groups, roles) as headers before forwarding the request to the backend service. Background: To simplify backend microservices, we want them to receive clear information about the authenticated user directly via headers, rather than needing to parse and validate JWTs themselves. The auth-service, acting as the Traefik forwardAuth endpoint, is the ideal place to perform this token validation, extraction, and header preparation. Description: This ticket should modify the request processing flow. The auth-service should extract the user's token, verify it, and transform it into an object containing user information (username, email, groups, permissions, etc.). This metadata, represented as headers, will be handed off to downstream services, replacing the original token, so they can directly use this information for their internal permission checks. Prerequisites: The auth-service is implemented with a working /auth endpoint for Traefik forwardAuth. #3 Traefik is configured to use the auth-service for forward authentication for target services. #4 What needs to be done: Modify auth-service (/auth endpoint logic): After successfully validating the incoming token and determining that the request should be allowed: Extract required user metadata from the validated token payload (or from a Keycloak userinfo call if needed). Define which fields are essential (e.g., User ID/Username, Email, Group Memberships, Realm Roles). Define a standard set of HTTP header names to carry this information (e.g., X-User-Id, X-User-Email, X-User-Groups, X-User-Roles). Ensure formats are consistent (e.g., comma-separated lists for groups/roles). Modify the /auth endpoint's success response (e.g., 200 OK) to include these defined headers with the extracted user metadata. (The auth-service doesn't modify the request directly; it sends these headers back to Traefik). Update Traefik Configuration (via Labels): Modify the forwardAuth middleware definition in the Docker Swarm YAML labels for all services protected by the auth-service: Add or update the authResponseHeaders option to explicitly list the custom headers (e.g., X-User-Id, X-User-Email, X-User-Groups, X-User-Roles) that Traefik should copy from the auth-service's response onto the request being sent to the backend service. Ensure the original Authorization header is not included in authResponseHeaders. Verify Traefik's behavior regarding stripping the original client Authorization header after successful forward auth (this is usually the default). Documentation: Document the new standard X-User-* headers (names, format, content). Clearly state that backend services protected by this mechanism must be updated to read these headers for user context and permission checks, instead of expecting a JWT. Key Considerations: Backend Service Impact: This change requires mandatory updates to all backend services relying on this authentication mechanism. They must adapt to consume the new headers. Header Naming: Use a consistent prefix (like X-User- or X-Auth-) to avoid conflicts. Data Selection: Only include necessary user metadata in headers to avoid excessive header size. Deliverables: Updated the auth-service source code. Updated Docker Swarm YAML file(s) with modified Traefik forwardAuth labels for relevant services. // new ticket in IM repo Documentation detailing the new headers and the required changes for backend services.

abed.alrahman added the

labels

2025-04-22 23:03:03 +00:00

stanislav.hejny added the

Type

Task

label

2025-04-29 10:36:09 +00:00

stanislav.hejny commented

2025-04-29 10:36:22 +00:00

Member

depends on / is blocked by 'have independent keycloak instance deployed' in CleverThis company context, as a DEVELOPMENT env instance (identity-management project task)

stanislav.hejny added the

Rows
Columns