Skip to content

0080-auth-graph-preview-internal-pipeline.md

Latest commit

 

History

History
79 lines (57 loc) · 3.37 KB

0080-auth-graph-preview-internal-pipeline.md

File metadata and controls

79 lines (57 loc) · 3.37 KB
Raw

ADR-0080: Auth Graph Preview — Internal vs External Pipeline

UMS-specific: No Evolith upstream. The auth graph preview pipeline reuses the same IAuthorizationGraphBuilder as production authentication — a design decision exclusive to UMS's internal architecture.

Status: Accepted
Date: 2026-06-03
Decision Owner: Architecture
Related:

Context

The UMS portal needs to let administrators preview the auth graph for a given profile without issuing a real authentication request. This is required for:

  • Validating that a profile's permission template and role assignment produce the expected graph before assigning it to live users.
  • Debugging access control issues during support sessions.

The naive approach would be a separate, simplified graph builder for the preview. However, building two independent graph builders means the preview can diverge from the real output, which defeats its diagnostic purpose.

Decision

Rule: preview uses the same IAuthorizationGraphBuilder

The internal preview endpoint GET /api/v1/profiles/{id}/auth-graph/preview calls PreviewProfileAuthGraphCommandHandler, which uses the same IAuthorizationGraphBuilder injection as the external POST /api/v1/client/authenticate flow.

There is one graph-building pipeline. The preview is distinguished from live authentication only by:

Aspect External auth (POST /client/authenticate) Internal preview (GET /profiles/{id}/auth-graph/preview)
Credential validation Yes — resolves and validates credentials Skipped — profile is looked up directly by ID
Auth method resolution Yes Not needed — profile already exists
Audit event Auth.Success / Auth.Failure Graph.Preview.Internal
Response header — X-Preview-Mode: internal-preview, X-Request-Id
Access control Public (token-based) Requires authenticated portal session (IUserContext.IsAuthenticated)

What is preserved

  • Graph format resolution (same IAuthGraphFormatProvider and IFactory<..., IAuthorizationGraphSerializer>).
  • Format override via ?format= query parameter — same logic as the external endpoint.
  • Tenant parameters (tenantId, tenantCode, authMethodUsed) propagated from the profile.
  • requestId field in the response for traceability.

Endpoint

GET /api/v1/profiles/{profileId:guid}/auth-graph/preview[?format=JSON|CBOR|...]
Authorization: X-User-Id / X-Tenant-Id headers (portal session)

Response:

{
  "format": "JSON",
  "graph": { ... },
  "requestId": "...",
  "previewMode": "internal-preview",
  "profileId": "...",
  "userId": "...",
  "tenantId": "...",
  "tenantCode": "...",
  "authMethodUsed": "..."
}

Consequences

  • Positive: Administrators see exactly what the external caller would see — no divergence risk.
  • Positive: Single code path to maintain and test.
  • Negative: Preview inherits the full graph-building cost; acceptable because it is an on-demand diagnostic tool, not a hot path.
  • Neutral: Credential resolution is the only external-only step; removing it from the preview path does not affect graph correctness.