Audit Trails for Authorization Decisions

In this lesson, you will learn how to instrument your authorization logic to generate transparent, actionable logs explaining exactly why a user was granted or denied access.

Why Log Authorization Decisions?

When you use Policy-Based Authorization, the decision-making process can become complex, involving multiple requirements, claims, and external state checks. If a user is denied access, "Access Denied" is rarely enough information for debugging or compliance audits. To build robust security, you need to capture the reasoning behind the decision at the moment it happens.

Implementing Contextual Logging

The most effective way to audit these decisions is to inject an ILogger into your AuthorizationHandler. Instead of simply calling context.Succeed() or doing nothing, you should explicitly log the evaluation path.

Consider a requirement that checks if a user has a specific clearance level:

public class ClearanceHandler : AuthorizationHandler<ClearanceRequirement>
{
    private readonly ILogger<ClearanceHandler> _logger;

    public ClearanceHandler(ILogger<ClearanceHandler> logger) => _logger = logger;

    protected override Task HandleRequirementAsync(
        AuthorizationHandlerContext context, ClearanceRequirement requirement)
    {
        var userEmail = context.User.FindFirst(ClaimTypes.Email)?.Value;
        var userClearance = context.User.FindFirst("ClearanceLevel")?.Value;

        if (userClearance != null && int.Parse(userClearance) >= requirement.MinLevel)
        {
            _logger.LogInformation("Authorization Succeeded: User {Email} met clearance requirement.", userEmail);
            context.Succeed(requirement);
        }
        else
        {
            _logger.LogWarning("Authorization Failed: User {Email} has clearance {Level}, required {Min}", 
                userEmail, userClearance ?? "None", requirement.MinLevel);
        }

        return Task.CompletedTask;
    }
}

Best Practices for Audit Trails

1. Identify the Actor: Always log the user’s identity (e.g., Email, Sub, or UserID) so you can reconstruct their history.
2. Log the Policy Name: When using policy-based authorization, include the name of the policy being evaluated.
3. Avoid Sensitive Data: Log the reason for failure, but never log sensitive claim values (like passwords or tokens) that might violate privacy regulations (PII).
4. Structured Logging: Use structured logging templates (as shown above) so your monitoring tools can aggregate and alert on "Access Denied" patterns across your distributed services.

By surfacing the decision logic in your logs, you transform a "black box" security check into a transparent, auditable process.

Key Takeaway: Always log the specific claims or conditions that triggered a success or failure within your AuthorizationHandler to create a verifiable audit trail for every security decision.