Audit log for authorization decisions

src/ServiceControl.AcceptanceTesting/OpenIdConnect/MockOidcServer.cs

@@ -184,9 +184,13 @@ public string GenerateToken(
         {
             var credentials = new SigningCredentials(securityKey, SecurityAlgorithms.RsaSha256);
 
+            // sub + preferred_username are required by PermissionVerbHandler for the audit log;
+            // defaulting them here keeps callers concise. Callers that need to test the
+            // missing-claim path pass an explicit additionalClaim with an empty value to override.
             var claims = new List<Claim>
             {
                 new(JwtRegisteredClaimNames.Sub, subject),
+                new("preferred_username", subject),
                 new(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString())
             };
 

src/ServiceControl.Audit.UnitTests/ApprovalFiles/APIApprovals.PlatformSampleSettings.approved.txt

@@ -12,6 +12,8 @@
     "ValidateLifetime": true,
     "ValidateIssuerSigningKey": true,
     "RequireHttpsMetadata": true,
+    "SubjectIdClaim": "sub",
+    "SubjectNameClaim": "preferred_username",
     "ServicePulseAuthority": null,
     "ServicePulseClientId": null,
     "ServicePulseApiScopes": null,

src/ServiceControl.Hosting/Auth/HostApplicationBuilderExtensions.cs

@@ -7,6 +7,7 @@
     using Microsoft.AspNetCore.Authentication.JwtBearer;
     using Microsoft.AspNetCore.Http;
     using Microsoft.Extensions.DependencyInjection;
+    using Microsoft.Extensions.DependencyInjection.Extensions;
     using Microsoft.Extensions.Hosting;
     using Microsoft.IdentityModel.Tokens;
     using ServiceControl.Infrastructure;
@@ -21,6 +22,11 @@ public static void AddServiceControlAuthentication(this IHostApplicationBuilder
                 return;
             }
 
+            // Shared with the authorization services and the claims transformation below; registered
+            // once so it can be constructor-injected rather than captured. TryAdd keeps it idempotent
+            // with AddServiceControlAuthorization, which registers the same instance.
+            hostBuilder.Services.TryAddSingleton(oidcSettings);
+
             _ = hostBuilder.Services.AddAuthentication(options =>
             {
                 options.DefaultScheme = "Bearer";
@@ -104,9 +110,8 @@ public static void AddServiceControlAuthentication(this IHostApplicationBuilder
 
             // Normalise per-IdP role claim shapes (Keycloak's nested realm_access.roles, Entra app
             // roles, Cognito groups) into canonical "roles" claims for the verb handler. The source
-            // path is configurable via Authentication.RolesClaim.
-            hostBuilder.Services.AddSingleton<IClaimsTransformation>(
-                new RolesClaimsTransformation(oidcSettings.RolesClaim));
+            // path is configurable via Authentication.RolesClaim, read off the injected settings.
+            hostBuilder.Services.AddSingleton<IClaimsTransformation, RolesClaimsTransformation>();
         }
 
         static string GetErrorMessage(JwtBearerChallengeContext context)

src/ServiceControl.Hosting/Auth/PermissionAuthorizationExtensions.cs

@@ -3,9 +3,10 @@ namespace ServiceControl.Hosting.Auth;
 
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.DependencyInjection.Extensions;
 using Microsoft.Extensions.Hosting;
-using Microsoft.Extensions.Options;
 using ServiceControl.Infrastructure;
+using ServiceControl.Infrastructure.Auth;
 
 /// <summary>
 /// Registers the permission-based policy authorization services: a dynamic
@@ -25,6 +26,10 @@ public static void AddServiceControlAuthorization(this IHostApplicationBuilder h
     {
         var services = hostBuilder.Services;
 
+        // The settings are shared by every auth service below (and the authentication wiring), so they
+        // are registered once in DI and constructor-injected rather than captured in factory lambdas.
+        services.TryAddSingleton(oidcSettings);
+
         // Ensure the authorization core services and options are present (idempotent).
         services.AddAuthorization();
 
@@ -34,9 +39,15 @@ public static void AddServiceControlAuthorization(this IHostApplicationBuilder h
         // request to an annotated endpoint. When RBAC is disabled the provider returns allow-all
         // policies (no requirement), so anonymous-to-the-policy calls pass through and the verb
         // handler is unnecessary.
-        services.AddSingleton<IAuthorizationPolicyProvider>(sp =>
-            new PermissionPolicyProvider(sp.GetRequiredService<IOptions<AuthorizationOptions>>(), oidcSettings));
+        services.AddSingleton<IAuthorizationPolicyProvider, PermissionPolicyProvider>();
 
-        services.AddSingleton<IAuthorizationHandler>(_ => new PermissionVerbHandler(oidcSettings.RolesClaim));
+        // The provider only emits a PermissionRequirement when RBAC is enabled, so the handler is the
+        // only thing that evaluates one. It is registered alongside the provider (cheap singleton, never
+        // invoked when no requirement is produced). The handler emits an audit-log entry for every
+        // decision through IAuthorizationAuditLog so the platform can show, after the fact, who attempted
+        // what and how the system responded. The subject-id and subject-name claim names are read off the
+        // injected OpenIdConnectSettings so the handler can match them on the principal.
+        services.AddSingleton<IAuthorizationAuditLog, AuthorizationAuditLog>();
+        services.AddSingleton<IAuthorizationHandler, PermissionVerbHandler>();
     }
 }

src/ServiceControl.Hosting/Auth/PermissionVerbHandler.cs

@@ -1,42 +1,90 @@
 #nullable enable
 namespace ServiceControl.Hosting.Auth;
 
+using System;
 using System.Linq;
+using System.Security.Claims;
 using System.Threading.Tasks;
 using Microsoft.AspNetCore.Authorization;
+using ServiceControl.Infrastructure;
 using ServiceControl.Infrastructure.Auth;
 
 /// <summary>
 /// Verb-level authorization handler for <see cref="PermissionRequirement"/>. It resolves the user's
 /// roles and checks them against the hardcoded <see cref="RolePermissions"/> policy: the user must hold
-/// a role (e.g. <c>reader</c> / <c>writer</c>) that grants the requested permission.
+/// a role (e.g. <c>reader</c> / <c>writer</c>) that grants the requested permission. Every decision is
+/// captured through <see cref="IAuthorizationAuditLog"/> for compliance.
 /// <para>
 /// Only registered — and only reached — when OIDC is enabled. When it is disabled,
 /// <see cref="PermissionPolicyProvider"/> returns an allow-all policy that carries no
 /// <see cref="PermissionRequirement"/>, so this handler is not needed.
 /// </para>
 /// </summary>
-public sealed class PermissionVerbHandler : AuthorizationHandler<PermissionRequirement>
+public sealed class PermissionVerbHandler(
+    IAuthorizationAuditLog auditLog,
+    OpenIdConnectSettings oidcSettings)
+    : AuthorizationHandler<PermissionRequirement>
 {
-    public PermissionVerbHandler(string rolesClaimName)
-    {
-        RoleClaimType = rolesClaimName;
-    }
+    // The per-IdP variability of the source claim is absorbed by RolesClaimsTransformation, which
+    // reads from the path configured in Authentication.RolesClaim and emits canonical "roles" claims.
+    const string RoleClaimType = "roles";
 
     protected override Task HandleRequirementAsync(
         AuthorizationHandlerContext context,
         PermissionRequirement requirement)
     {
-        var roles = context.User.FindAll(RoleClaimType).Select(claim => claim.Value);
+        // Unauthenticated requests have no subject and no roles. The framework will challenge with
+        // 401 because the policy also includes RequireAuthenticatedUser; skipping here keeps the
+        // audit log restricted to identified principals.
+        if (context.User.Identity?.IsAuthenticated != true)
+        {
+            return Task.CompletedTask;
+        }
+
+        var subjectId = RequireClaim(context.User, oidcSettings.SubjectIdClaim, "Authentication.SubjectIdClaim");
+        var subjectName = RequireClaim(context.User, oidcSettings.SubjectNameClaim, "Authentication.SubjectNameClaim");
+        var roles = context.User.FindAll(RoleClaimType).Select(claim => claim.Value).ToArray();
+        var permission = requirement.Permission;
 
-        if (RolePermissions.IsGranted(roles, requirement.Permission))
+        if (RolePermissions.IsGranted(roles, permission))
         {
+            auditLog.Decision(
+                subjectId,
+                subjectName,
+                permission,
+                resource: null,
+                allowed: true,
+                reason: roles.Length == 0
+                    ? $"User holds '{permission}'"
+                    : $"User holds '{permission}' via role(s) [{string.Join(", ", roles)}]");
+
             context.Succeed(requirement);
+            return Task.CompletedTask;
         }
 
-        // Otherwise leave the requirement unmet → the request is denied (403/401).
+        auditLog.Decision(
+            subjectId,
+            subjectName,
+            permission,
+            resource: null,
+            allowed: false,
+            reason: roles.Length == 0
+                ? $"User has no roles granting '{permission}'"
+                : $"None of the user's role(s) [{string.Join(", ", roles)}] grants '{permission}'");
+
+        // Leave the requirement unmet → the framework forbids (403).
         return Task.CompletedTask;
     }
 
-    internal string RoleClaimType = "roles";
-}
+    static string RequireClaim(ClaimsPrincipal user, string claimType, string settingName)
+    {
+        var value = user.FindFirst(claimType)?.Value;
+        if (string.IsNullOrEmpty(value))
+        {
+            throw new InvalidOperationException(
+                $"Authenticated principal is missing the required '{claimType}' claim configured by {settingName}. " +
+                "Configure the identity provider to emit this claim, or point the setting at the claim the IdP actually emits.");
+        }
+        return value;
+    }
+}

src/ServiceControl.Hosting/Auth/RolesClaimsTransformation.cs

@@ -5,6 +5,7 @@ namespace ServiceControl.Hosting.Auth;
 using System.Security.Claims;
 using System.Threading.Tasks;
 using Microsoft.AspNetCore.Authentication;
+using ServiceControl.Infrastructure;
 using ServiceControl.Infrastructure.Auth;
 
 /// <summary>
@@ -18,7 +19,7 @@ namespace ServiceControl.Hosting.Auth;
 /// claim makes the transformation idempotent and returns the same principal on subsequent calls.
 /// </para>
 /// </summary>
-public sealed class RolesClaimsTransformation(string rolesClaimPath) : IClaimsTransformation
+public sealed class RolesClaimsTransformation(OpenIdConnectSettings oidcSettings) : IClaimsTransformation
 {
     const string SentinelClaimType = "_roles_transformed";
     // The sentinel's value is irrelevant; only the claim's presence matters. A non-empty
@@ -34,7 +35,7 @@ public Task<ClaimsPrincipal> TransformAsync(ClaimsPrincipal principal)
             return Task.FromResult(principal);
         }
 
-        var roles = RolesClaimExtractor.Extract(principal, rolesClaimPath);
+        var roles = RolesClaimExtractor.Extract(principal, oidcSettings.RolesClaim);
 
         var claims = new Claim[roles.Count + 1];
         claims[0] = new Claim(SentinelClaimType, SentinelClaimValue);

src/ServiceControl.Infrastructure.Tests/Auth/AuthorizationAuditLogTests.cs

@@ -0,0 +1,98 @@
+#nullable enable
+namespace ServiceControl.Infrastructure.Tests.Auth;
+
+using System;
+using System.Text.Json;
+using Microsoft.Extensions.Logging;
+using NUnit.Framework;
+using ServiceControl.Infrastructure.Auth;
+
+[TestFixture]
+public class AuthorizationAuditLogTests
+{
+    [Test]
+    public void Decision_allow_emits_one_entry_on_audit_category()
+    {
+        var provider = new RecordingLoggerProvider();
+        var factory = LoggerFactory.Create(b => b.AddProvider(provider));
+        var auditLog = new AuthorizationAuditLog(factory);
+
+        auditLog.Decision("alice-sub-001", "Alice Smith", "error:messages:retry", "acme.sales", allowed: true, reason: "role:reader matched");
+
+        var entries = provider.EntriesFor("ServiceControl.Audit");
+        Assert.That(entries, Has.Count.EqualTo(1));
+        var ecs = JsonDocument.Parse(entries[0].Message).RootElement;
+        Assert.That(ecs.GetProperty("event").GetProperty("type")[0].GetString(), Is.EqualTo("allowed"));
+        Assert.That(ecs.GetProperty("event").GetProperty("outcome").GetString(), Is.EqualTo("success"));
+        Assert.That(ecs.GetProperty("user").GetProperty("id").GetString(), Is.EqualTo("alice-sub-001"));
+        Assert.That(ecs.GetProperty("user").GetProperty("name").GetString(), Is.EqualTo("Alice Smith"));
+        Assert.That(ecs.GetProperty("event").GetProperty("action").GetString(), Is.EqualTo("error:messages:retry"));
+        Assert.That(entries[0].Level, Is.EqualTo(LogLevel.Information));
+    }
+
+    [Test]
+    public void Decision_deny_emits_one_entry_on_audit_category()
+    {
+        var provider = new RecordingLoggerProvider();
+        var factory = LoggerFactory.Create(b => b.AddProvider(provider));
+        var auditLog = new AuthorizationAuditLog(factory);
+
+        auditLog.Decision("bob-sub-002", "Bob Jones", "error:messages:retry", null, allowed: false, reason: "no matching role");
+
+        var entries = provider.EntriesFor("ServiceControl.Audit");
+        Assert.That(entries, Has.Count.EqualTo(1));
+        var ecs = JsonDocument.Parse(entries[0].Message).RootElement;
+        Assert.That(ecs.GetProperty("event").GetProperty("type")[0].GetString(), Is.EqualTo("denied"));
+        Assert.That(ecs.GetProperty("event").GetProperty("outcome").GetString(), Is.EqualTo("failure"));
+        Assert.That(ecs.GetProperty("user").GetProperty("id").GetString(), Is.EqualTo("bob-sub-002"));
+        Assert.That(ecs.GetProperty("servicecontrol").GetProperty("resource").ValueKind, Is.EqualTo(JsonValueKind.Null));
+        Assert.That(entries[0].Level, Is.EqualTo(LogLevel.Warning));
+    }
+
+    [Test]
+    public void Decision_does_not_appear_on_other_categories()
+    {
+        var provider = new RecordingLoggerProvider();
+        var factory = LoggerFactory.Create(b => b.AddProvider(provider));
+        var auditLog = new AuthorizationAuditLog(factory);
+
+        auditLog.Decision("carol-sub-003", "Carol White", "error:endpoints:view", null, allowed: true, reason: "role:reader matched");
+
+        Assert.That(provider.EntriesFor("ServiceControl.SomeOtherCategory"), Is.Empty);
+    }
+
+    [Test]
+    public void Multiple_decisions_accumulate_in_order()
+    {
+        var provider = new RecordingLoggerProvider();
+        var factory = LoggerFactory.Create(b => b.AddProvider(provider));
+        var auditLog = new AuthorizationAuditLog(factory);
+
+        auditLog.Decision("alice-sub-001", "alice", "error:messages:view", null, allowed: true, "role matched");
+        auditLog.Decision("alice-sub-001", "alice", "error:messages:retry", "acme.finance", allowed: false, "out of scope");
+
+        var entries = provider.EntriesFor("ServiceControl.Audit");
+        Assert.That(entries, Has.Count.EqualTo(2));
+        Assert.That(JsonDocument.Parse(entries[0].Message).RootElement.GetProperty("event").GetProperty("type")[0].GetString(), Is.EqualTo("allowed"));
+        Assert.That(JsonDocument.Parse(entries[1].Message).RootElement.GetProperty("event").GetProperty("type")[0].GetString(), Is.EqualTo("denied"));
+    }
+
+    [TestCase(null, "Alice", "error:messages:retry", "reason")]
+    [TestCase("", "Alice", "error:messages:retry", "reason")]
+    [TestCase("alice-sub-001", null, "error:messages:retry", "reason")]
+    [TestCase("alice-sub-001", "", "error:messages:retry", "reason")]
+    [TestCase("alice-sub-001", "Alice", null, "reason")]
+    [TestCase("alice-sub-001", "Alice", "", "reason")]
+    [TestCase("alice-sub-001", "Alice", "error:messages:retry", null)]
+    [TestCase("alice-sub-001", "Alice", "error:messages:retry", "")]
+    public void Decision_throws_when_required_argument_is_null_or_empty(string? subjectId, string? subjectName, string? permission, string? reason)
+    {
+        var provider = new RecordingLoggerProvider();
+        var factory = LoggerFactory.Create(b => b.AddProvider(provider));
+        var auditLog = new AuthorizationAuditLog(factory);
+
+        Assert.That(
+            () => auditLog.Decision(subjectId!, subjectName!, permission!, resource: null, allowed: true, reason: reason!),
+            Throws.InstanceOf<ArgumentException>());
+    }
+}

src/ServiceControl.Infrastructure.Tests/Auth/RecordingLoggerProvider.cs

@@ -0,0 +1,59 @@
+#nullable enable
+namespace ServiceControl.Infrastructure.Tests.Auth;
+
+using System;
+using System.Collections.Concurrent;
+using System.Collections.Generic;
+using System.Linq;
+using Microsoft.Extensions.Logging;
+
+/// <summary>
+/// In-memory <see cref="ILoggerProvider"/> that captures log entries for test assertions.
+/// Thread-safe. Use <see cref="Entries"/> for all captured entries; <see cref="EntriesFor(string)"/>
+/// to filter by category.
+/// </summary>
+sealed class RecordingLoggerProvider : ILoggerProvider
+{
+    readonly ConcurrentQueue<LogEntry> entries = new();
+
+    public IReadOnlyList<LogEntry> Entries => entries.ToArray();
+
+    public IReadOnlyList<LogEntry> EntriesFor(string category) =>
+        entries.Where(e => e.Category == category).ToArray();
+
+    public ILogger CreateLogger(string categoryName) =>
+        new RecordingLogger(categoryName, entries);
+
+    public void Dispose() { }
+}
+
+sealed record LogEntry(
+    string Category,
+    LogLevel Level,
+    EventId EventId,
+    string Message,
+    Exception? Exception);
+
+sealed class RecordingLogger(string category, ConcurrentQueue<LogEntry> sink) : ILogger
+{
+    public IDisposable? BeginScope<TState>(TState state) where TState : notnull => NullScope.Instance;
+
+    public bool IsEnabled(LogLevel logLevel) => logLevel != LogLevel.None;
+
+    public void Log<TState>(
+        LogLevel logLevel,
+        EventId eventId,
+        TState state,
+        Exception? exception,
+        Func<TState, Exception?, string> formatter)
+    {
+        var message = formatter(state, exception);
+        sink.Enqueue(new LogEntry(category, logLevel, eventId, message, exception));
+    }
+
+    sealed class NullScope : IDisposable
+    {
+        public static readonly NullScope Instance = new();
+        public void Dispose() { }
+    }
+}