Skip to content

5.3 Authentication

Sprint: Sprint 05 - Security and Identity
Feature ID: 5.3
Subtasks: 5.3.1, 5.3.2

Objective

Deliver "Authentication" within Sprint 05 - Security and Identity.

Dependencies

Aggregated from the subtasks below (prerequisite task IDs and enablers):

  • 5.2.2
  • 4.3.2
  • 5.3.1

Subtasks

Per ADR-011, authentication is a Keycloak realm feature. identity-service does NOT implement a login endpoint or mint JWTs. This feature configures and verifies the Keycloak flow.

5.3.1 Configure the Keycloak realm for authentication

  • ID: 5.3.1
  • Title: Configure telco-crm realm clients, token policy, and role-to-claim mapping
  • Description: In the telco-crm Keycloak realm (infra/docker/keycloak), configure the telco-web (public, Authorization Code + PKCE) and telco-gateway (confidential) clients, access/refresh token lifespans, and the telco-roles mapper exposing realm roles as a flat roles claim. Keycloak issues and refreshes tokens (ADR-011). See docs/architecture/keycloak-and-auth.md.
  • Business Purpose: Authenticate users via the platform IdP (FR-IAM-01).
  • Inputs: FR-IAM-01, ADR-011, docs/architecture/keycloak-and-auth.md.
  • Outputs: Realm client + token + claim-mapper configuration.
  • Acceptance Criteria:
  • A user obtains an access + refresh token from the Keycloak realm token endpoint; the access token carries sub, a flat roles claim, issuer, and expiry.
  • Dependencies: 4.3.2
  • Complexity: M

5.3.2 Verify authentication end to end through the gateway

  • ID: 5.3.2
  • Title: Verify Keycloak login -> gateway JWKS validation -> identity propagation
  • Description: Verify a Keycloak-issued token is accepted by the gateway (JWKS validation), identity headers are propagated downstream, and an unauthenticated request is rejected. No custom login endpoint exists in identity-service.
  • Business Purpose: Confirm authenticated access works platform-wide (FR-IAM-01, FR-IAM-02).
  • Inputs: 5.3.1, 4.3.2, 4.3.3.
  • Outputs: End-to-end authentication verification (test/runbook).
  • Acceptance Criteria:
  • A request with a valid Keycloak token reaches a protected route with X-User-Id/X-User-Roles set; a missing/invalid token returns 401 at the gateway.
  • Dependencies: 5.3.1
  • Complexity: S

Acceptance Criteria

Each subtask above carries its own objective, testable acceptance criteria. This feature is complete when every subtask's acceptance criteria are met.

Deliverables

  • Keycloak realm client/token/claim-mapper configuration.
  • End-to-end authentication verification.

Definition of Done

  • Both subtasks (5.3.1, 5.3.2) completed and their acceptance criteria verified (Keycloak realm configured; end-to-end auth verified). No custom JWT issuer is built (ADR-011).
  • All listed dependencies satisfied.
  • Build and tests green per the global conventions in ../README.md (Section 3).