Functional Story 26: Preview Auth Graph from Profile Maintenance
1. Business Purpose
Authorization administrators need to verify that a profile’s permission configuration will produce the correct auth graph before the profile is used in live authentication. Without this capability, misconfigured profiles can only be detected after a real user attempts to authenticate and receives incorrect access.
2. Actors
| Actor |
Responsibility |
| Security Administrator |
Verifies profile auth graph before activating or assigning a profile. |
| SRE / Support Engineer |
Diagnoses permission issues for a specific profile. |
3. Business Preconditions
- The actor is authenticated in the UMS portal.
- The target profile exists.
- The actor has diagnostic access to profile data.
4. Main Functional Flow
- The actor opens a profile in the Profile Maintenance section.
- The actor triggers the auth graph preview.
- The system calls
GET /api/v1/profiles/{profileId}/auth-graph/preview.
- The system builds the auth graph using the same pipeline as a real authentication.
- The system returns the graph with metadata (format, requestId, tenantCode, authMethodUsed).
- The actor inspects the graph to verify expected permissions.
5. Alternative Flows and Exceptions
A. Unauthenticated Access
Requests without a valid portal session return HTTP 401 Unauthorized.
B. Profile Not Found
If the profile ID does not exist, the system returns HTTP 400 with an error message.
6. Business Rules
- The preview must use the same
IAuthorizationGraphBuilder pipeline as live authentication — no separate or simplified builder.
- Credential validation is skipped; the profile is resolved directly by ID.
- The preview emits audit event
Graph.Preview.Internal, not Auth.Success.
- The preview does not modify any permissions or profile state.
7. Acceptance Criteria
- Authenticated administrators can retrieve the auth graph preview for any accessible profile.
- The response contains
previewMode: "internal-preview", format, graph, requestId, profileId, tenantId.
- The response headers include
X-Preview-Mode: internal-preview and X-Request-Id.
- Unauthenticated requests return HTTP 401.
- The preview graph is identical to what live authentication would produce for the same profile.
8. Technical Requirements
- Endpoint:
GET /api/v1/profiles/{profileId}/auth-graph/preview[?format=JSON|CBOR|...]
- Handler:
PreviewProfileAuthGraphCommandHandler using injected IAuthorizationGraphBuilder.
- Format override supported via
?format= query parameter.
- Access guard:
IUserContext.IsAuthenticated check at the endpoint.
9. Traceability