Skip to content

5.4 Refresh-Token Rotation and Reuse Detection

Sprint: Sprint 05 - Security and Identity
Feature ID: 5.4
Subtasks: 5.4.1, 5.4.2

Objective

Deliver "Refresh-Token Rotation and Reuse Detection" within Sprint 05 - Security and Identity.

Dependencies

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

  • 5.3.1
  • 5.4.1
  • 5.6.1

Subtasks

Per ADR-011, refresh-token rotation and reuse detection are Keycloak realm features, not custom code. This feature configures and verifies them. The Redis-blacklist mechanism from the original brief (FR-IAM-05) is superseded by Keycloak's built-in rotation/revocation.

5.4.1 Enable refresh-token rotation in the realm

  • ID: 5.4.1
  • Title: Configure Keycloak refresh-token rotation
  • Description: Enable "Revoke Refresh Token" / rotation in the telco-crm realm so each refresh issues a new refresh token and invalidates the prior one (FR-IAM-05). Keycloak owns this, not identity-service.
  • Business Purpose: Single-use refresh tokens (FR-IAM-05).
  • Inputs: FR-IAM-05, ADR-011, docs/architecture/keycloak-and-auth.md.
  • Outputs: Realm refresh-rotation configuration.
  • Acceptance Criteria:
  • A refresh returns a new refresh token and the prior token is no longer valid.
  • Dependencies: 5.3.1
  • Complexity: S

5.4.2 Verify reuse detection and revocation

  • ID: 5.4.2
  • Title: Verify Keycloak reuse detection revokes the session
  • Description: Verify that presenting an already-rotated (reused) refresh token is rejected and the session is revoked per the realm policy; record the security-relevant event in the audit log (FR-IAM-05).
  • Business Purpose: Contain stolen-token replay (FR-IAM-05).
  • Inputs: FR-IAM-05.
  • Outputs: Reuse-detection verification (test) + audit hook.
  • Acceptance Criteria:
  • Reusing a rotated refresh token fails, forces re-authentication, and writes an audit record.
  • Dependencies: 5.4.1, 5.6.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

  • Realm refresh-rotation configuration.
  • Reuse-detection verification + audit hook.

Definition of Done

  • Both subtasks (5.4.1, 5.4.2) completed and their acceptance criteria verified.
  • All listed dependencies satisfied.
  • Build and tests green per the global conventions in ../README.md (Section 3).