authn.login.started
authn.login.succeeded
authn.login.failed
authn.mfa.challenge.created
authn.mfa.challenge.succeeded
authn.mfa.challenge.failed
authn.passkey.registered
authn.password.changed
authn.account.locked
authn.account.recovered
authn.session.created
authn.session.terminated

oauth.authorization.started
oauth.authorization.consent.granted
oauth.authorization.consent.denied
oauth.token.issued
oauth.token.refreshed
oauth.token.revoked
oauth.refresh_token.reuse_detected
oauth.client.authentication.failed
oauth.client.secret.rotated
oauth.jwk.rotated

authz.decision.permitted
authz.decision.denied
authz.decision.step_up_required
authz.policy.changed
authz.policy.published
authz.sod.violation.detected
authz.tenant_scope_mismatch
authz.object_access.denied

entitlement.request.submitted
entitlement.request.approved
entitlement.request.rejected
entitlement.provisioned
entitlement.revoked
entitlement.expired
access_review.campaign.started
access_review.item.certified
access_review.item.revoked
break_glass.activated
break_glass.expired
break_glass.review.completed

delegation.consent.granted
delegation.consent.revoked
impersonation.started
impersonation.action.performed
impersonation.ended
obo.token_exchanged
support_mode.activated
support_mode.denied

tenant.created
tenant.disabled
tenant.admin.assigned
tenant.config.changed
tenant.identity_provider.changed
admin.user.created
admin.role.assigned
admin.policy.override.created

public record SecurityAuditEvent(
        AuditEventId eventId,
        String eventType,
        Instant occurredAt,
        String sourceService,
        String environment,
        Correlation correlation,
        Actor actor,
        Actor effectiveActor,
        ClientContext client,
        ResourceRef resource,
        ActionRef action,
        DecisionRef decision,
        TenantRef tenant,
        Map<String, String> attributes,
        Sensitivity sensitivity,
        EventOutcome outcome,
        String schemaVersion
) {}

Human user directly acts.
Support agent impersonates customer.
Service acts on behalf of human user.
Batch job acts as workload.
Policy automation revokes access.
Break-glass admin performs emergency action.

public record Actor(
        String actorType,
        String subjectId,
        String accountId,
        String displayNameHash,
        String assuranceLevel,
        List<String> authenticationMethods
) {}

public record ActorChain(
        Actor originalActor,
        Actor effectiveActor,
        DelegationRef delegation,
        ImpersonationRef impersonation,
        WorkloadRef workload
) {}

actor = customer-123

originalActor = support-agent-456
effectiveActor = customer-123
impersonationId = imp-789
purpose = customer-support-ticket-555

public record AuthorizationDecisionEvidence(
        DecisionId decisionId,
        SubjectId subjectId,
        Action action,
        ResourceDescriptor resource,
        TenantId tenantId,
        DecisionResult result,
        List<String> matchedPolicies,
        String policyVersion,
        List<String> reasonCodes,
        Instant decidedAt,
        long latencyMillis
) {}

Good reason code: tenant_scope_mismatch
Bad detail: user tried tenant bank-b but token tenant bank-a and internal SQL predicate was ...

public record Correlation(
        String traceId,
        String spanId,
        String requestId,
        String correlationId,
        String causationId,
        String decisionId,
        String sessionIdHash,
        String tokenIdHash
) {}

public final class CorrelationFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain filterChain
    ) throws ServletException, IOException {
        String requestId = Optional.ofNullable(request.getHeader("X-Request-Id"))
                .filter(this::isValidRequestId)
                .orElse(UUID.randomUUID().toString());

        try (MDC.MDCCloseable ignored = MDC.putCloseable("request_id", requestId)) {
            response.setHeader("X-Request-Id", requestId);
            filterChain.doFilter(request, response);
        }
    }

    private boolean isValidRequestId(String value) {
        return value.length() <= 128 && value.matches("[a-zA-Z0-9._:-]+\\z");
    }
}

{
  "schema_version": "security-audit-v1",
  "event_id": "evt-01J0...",
  "event_type": "authz.decision.denied",
  "occurred_at": "2026-06-28T10:15:30Z",
  "source_service": "case-api",
  "environment": "prod",
  "trace_id": "7b3f...",
  "request_id": "req-123",
  "tenant_id": "tenant-a",
  "actor_type": "human",
  "subject_id": "user-123",
  "client_id": "case-web-bff",
  "action": "case.approve",
  "resource_type": "case",
  "resource_id_hash": "sha256:...",
  "decision_id": "dec-789",
  "decision_result": "deny",
  "reason_codes": ["sod_conflict", "case_creator_cannot_approve"],
  "policy_version": "policy-2026.06.15",
  "outcome": "denied"
}

public interface AuditPublisher {
    void publish(SecurityAuditEvent event);
}

@Service
public class OutboxAuditPublisher implements AuditPublisher {

    private final AuditOutboxRepository repository;
    private final ObjectMapper objectMapper;

    @Override
    public void publish(SecurityAuditEvent event) {
        try {
            String payload = objectMapper.writeValueAsString(event);
            repository.save(new AuditOutboxRecord(
                    event.eventId().value(),
                    event.eventType(),
                    payload,
                    event.occurredAt(),
                    OutboxState.PENDING
            ));
        } catch (JsonProcessingException ex) {
            throw new AuditSerializationException("Failed to serialize audit event", ex);
        }
    }
}

@Transactional
public void revokeEntitlement(EntitlementId id, AuthenticatedActor actor) {
    Entitlement entitlement = entitlementRepository.findForUpdate(id)
            .orElseThrow();

    Entitlement revoked = entitlement.revoke(actor.subjectId(), Instant.now());
    entitlementRepository.save(revoked);

    auditPublisher.publish(SecurityAuditEvents.entitlementRevoked(revoked, actor));
}

public final class TokenFingerprint {
    public static String fingerprint(String token, SecretKey key) {
        // Use keyed hash for correlation. Do not expose raw token.
        byte[] mac = hmacSha256(key, token.getBytes(StandardCharsets.UTF_8));
        return "hmac-sha256:" + Base64.getUrlEncoder().withoutPadding().encodeToString(mac);
    }
}

public enum Sensitivity {
    PUBLIC_OPERATIONAL,
    INTERNAL_SECURITY,
    CONFIDENTIAL_IDENTITY,
    RESTRICTED_PRIVILEGED,
    REGULATED_PERSONAL_DATA
}

public final class AuditEventValidator {

    public void validate(SecurityAuditEvent event) {
        requireNonBlank(event.eventType(), "eventType");
        requireNonNull(event.occurredAt(), "occurredAt");
        requireNonNull(event.eventId(), "eventId");
        requireNonBlank(event.schemaVersion(), "schemaVersion");

        if (event.eventType().startsWith("authz.decision")) {
            requireNonNull(event.actor(), "actor");
            requireNonNull(event.action(), "action");
            requireNonNull(event.resource(), "resource");
            requireNonNull(event.decision(), "decision");
        }

        if (containsRawSecret(event)) {
            throw new InvalidAuditEventException("audit_event_contains_secret_like_value");
        }
    }
}

@Test
void authzDeniedEventContainsRequiredFields() {
    SecurityAuditEvent event = SecurityAuditEvents.authorizationDenied(sampleDecision());

    assertThat(event.eventType()).isEqualTo("authz.decision.denied");
    assertThat(event.decision().reasonCodes()).contains("tenant_scope_mismatch");
    assertThat(event.correlation().traceId()).isNotBlank();
}

public final class AuditedAuthorizationService {

    public AuthorizationDecision decide(AuthorizationRequest request) {
        DecisionId decisionId = DecisionId.newId();
        Instant started = Instant.now();

        AuthorizationDecision decision = policyEngine.decide(request.withDecisionId(decisionId));

        auditPublisher.publish(SecurityAuditEvents.authorizationDecision(
                decisionId,
                request,
                decision,
                Duration.between(started, Instant.now())
        ));

        return decision;
    }
}

authn_login_success_total{tenant, client}
authn_login_failure_total{tenant, reason}
oauth_token_issued_total{client, grant_type}
oauth_refresh_reuse_detected_total{client}
authz_decision_total{service, action, result, reason}
authz_decision_latency_ms{service, action}
entitlement_active_total{risk_tier, tenant}
break_glass_activation_total{tenant}
impersonation_active_total{tenant}
access_review_overdue_total{tenant}

More than 10 refresh token reuse detections in 5 minutes.
Global admin entitlement created in production.
Break-glass activated outside incident window.
Tenant scope mismatch spikes after deployment.
Authorization policy errors > 0 in production.
Deny rate for one endpoint increases 10x.
Service account token issuance from unusual network.

Span current = Span.current();
current.setAttribute("enduser.id", principal.subjectId().value());
current.setAttribute("app.tenant_id", principal.tenantId().value());
current.setAttribute("authz.action", request.action().value());
current.setAttribute("authz.result", decision.result().name());

event.category: authentication | authorization | iam | api | admin
event.type: start | success | failure | denial | change | info
event.action: authz.decision.denied
user.id: user-123
user.effective.id: customer-456
client.id: case-web-bff
service.name: case-api
tenant.id: tenant-a
source.ip: 203.0.113.10
http.request.method: POST
url.path: /cases/{id}/approve
resource.type: case
resource.id_hash: hmac-sha256:...
authz.action: case.approve
authz.result: deny
authz.reason: sod_conflict
policy.version: policy-2026.06.15
trace.id: ...

evidencePackageId: evp-123
action: case.approve_final_sanction
actor:
  subjectId: user-123
  assurance: aal2
  authMethods: [pwd, otp]
resource:
  type: enforcement_case
  idHash: hmac-sha256:...
  tenant: tenant-a
authorization:
  decisionId: dec-456
  result: permit
  policies:
    - case-final-approval-v7
  reasonCodes:
    - supervisor_role_active
    - not_case_creator
    - tenant_scope_match
entitlement:
  id: ent-789
  role: CASE_SUPERVISOR
  scope: tenant-a/project-x
  validUntil: 2026-07-01T00:00:00Z
request:
  traceId: trace-abc
  requestId: req-def
outcome:
  status: succeeded
  committedAt: 2026-06-28T10:20:00Z

public record AuditBatch(
        String batchId,
        String previousBatchHash,
        List<SecurityAuditEvent> events,
        String batchHash,
        Instant closedAt
) {}

public record EventTime(
        Instant occurredAt,
        Instant observedAt,
        Instant ingestedAt
) {}

@Component
public class AuditOutboxRelay {

    @Scheduled(fixedDelayString = "PT5S")
    public void publishPending() {
        List<AuditOutboxRecord> records = repository.findPendingBatch(100);

        for (AuditOutboxRecord record : records) {
            try {
                broker.publish(record.eventType(), record.payload());
                repository.markPublished(record.id(), Instant.now());
            } catch (Exception ex) {
                repository.markFailedAttempt(record.id(), ex.getClass().getSimpleName(), Instant.now());
            }
        }
    }
}

SELECT occurred_at, subject_id, client_id, action, decision_result, reason_codes
FROM security_audit_event
WHERE tenant_id = 'tenant-a'
  AND resource_type = 'case'
  AND resource_id_hash = :case_id_hash
  AND event_type IN ('authz.decision.permitted', 'authz.decision.denied')
ORDER BY occurred_at;

SELECT occurred_at, subject_id, scope, attributes->>'reason' AS reason
FROM security_audit_event
WHERE event_type = 'break_glass.activated'
  AND occurred_at >= now() - interval '30 days'
ORDER BY occurred_at DESC;

SELECT subject_id, client_id, count(*) AS attempts
FROM security_audit_event
WHERE event_type = 'authz.tenant_scope_mismatch'
  AND occurred_at >= now() - interval '24 hours'
GROUP BY subject_id, client_id
ORDER BY attempts DESC;

@Test
void deniedAuthorizationPublishesAuditEvent() {
    AuthorizationRequest request = sampleRequest(Action.CASE_APPROVE);
    when(policyEngine.decide(request)).thenReturn(AuthorizationDecision.deny("sod_conflict"));

    assertThatThrownBy(() -> securedCaseService.approve(caseId, request.actor()))
            .isInstanceOf(AccessDeniedException.class);

    verify(auditPublisher).publish(argThat(event ->
            event.eventType().equals("authz.decision.denied")
                    && event.decision().reasonCodes().contains("sod_conflict")
                    && event.actor().subjectId().equals("user-123")
    ));
}

Given authz.decision.denied
Then required fields exist:
  event_id
  event_type
  occurred_at
  actor.subject_id
  action
  resource.type
  decision.result
  decision.reason_codes
  trace_id

@Test
void auditEventMustNotContainBearerToken() throws Exception {
    SecurityAuditEvent event = sampleEventWithAttributes(Map.of(
            "authorization_header", "Bearer abc.def.ghi"
    ));

    assertThatThrownBy(() -> validator.validate(event))
            .isInstanceOf(InvalidAuditEventException.class);
}

WHEN oauth.refresh_token.reuse_detected count > 0
THEN create high-priority security alert
AND revoke related grant/session

WHEN authz.tenant_scope_mismatch occurs repeatedly for same subject/client
THEN alert potential tenant probing or client bug

WHEN policy.published OR admin.role.assigned outside approved change window
THEN alert platform security owner

WHEN break_glass.activated
THEN notify incident channel immediately
AND create post-use review task

WHEN service account token issued from new network/location
OR token issuance volume spikes
THEN alert owner

GET /internal/audit-events?tenantId=tenant-a&subjectId=user-123&from=2026-06-01T00:00:00Z&to=2026-06-30T00:00:00Z
Authorization: Bearer ...

@GetMapping("/internal/audit-events")
public Page<AuditEventView> search(AuditSearchRequest request, Authentication authentication) {
    AuthenticatedActor actor = actorFactory.from(authentication);

    AuditSearchAuthorizationDecision decision = auditSearchAuthorizer.authorize(actor, request);
    if (!decision.permitted()) {
        throw new AccessDeniedException("audit_search_denied");
    }

    auditPublisher.publish(SecurityAuditEvents.auditSearchPerformed(actor, request));
    return auditSearchService.search(request, decision.visibleFields());
}

User did thing
Access denied
Policy failed