Authorization

builder.Services.AddAuthorizationBuilder()

    // A role, named once so endpoints do not repeat the string
    .AddPolicy("HrStaff", policy =>
        policy.RequireRole("HrAdministrator", "HrOfficer"))

    // A claim with specific values
    .AddPolicy("CanEditSalary", policy =>
        policy.RequireClaim("permission", "salary:write"))

    // Arbitrary logic over the caller's claims
    .AddPolicy("CompletedDataTraining", policy =>
        policy.RequireAssertion(context =>
            context.User.HasClaim(c =>
                c.Type == "training" && c.Value == "data-handling-2025")))

    // Applied to every endpoint unless it opts out
    .SetFallbackPolicy(new AuthorizationPolicyBuilder()
        .RequireAuthenticatedUser()
        .Build());

// ---

[ApiController]
[Route("api/employees")]
public sealed class EmployeesController(IEmployeeService employees) : ControllerBase
{
    [HttpGet]
    [Authorize(Policy = "HrStaff")]
    public async Task<ActionResult<IReadOnlyList<EmployeeResponse>>> List(
        CancellationToken cancellationToken)
    {
        return Ok(await employees.ListAsync(cancellationToken));
    }

    [HttpPut("{id:int}/salary")]
    [Authorize(Policy = "CanEditSalary")]
    public async Task<IActionResult> UpdateSalary(
        int id,
        UpdateSalaryRequest request,
        CancellationToken cancellationToken)
    {
        await employees.UpdateSalaryAsync(id, request.AnnualSalary, cancellationToken);
        return NoContent();
    }

    [HttpGet("public-directory")]
    [AllowAnonymous]
    public async Task<ActionResult<IReadOnlyList<DirectoryEntry>>> PublicDirectory(
        CancellationToken cancellationToken)
    {
        return Ok(await employees.ListDirectoryAsync(cancellationToken));
    }
}

// The requirement carries no logic, only intent.
public sealed class CanManageEmployeeRequirement : IAuthorizationRequirement
{
}

public sealed class CanManageEmployeeHandler
    : AuthorizationHandler<CanManageEmployeeRequirement, Employee>
{
    protected override Task HandleRequirementAsync(
        AuthorizationHandlerContext context,
        CanManageEmployeeRequirement requirement,
        Employee employee)
    {
        string? subject = context.User.FindFirst("sub")?.Value;

        bool isOwnRecord = subject is not null && employee.UserSubject == subject;
        bool isTheirLineManager = subject is not null && employee.LineManagerSubject == subject;
        bool isHrAdministrator = context.User.IsInRole("HrAdministrator");

        if (isOwnRecord || isTheirLineManager || isHrAdministrator)
        {
            context.Succeed(requirement);
        }

        // Do nothing on failure. Another handler for the same requirement
        // may still succeed it.
        return Task.CompletedTask;
    }
}

// Registration
builder.Services.AddSingleton<IAuthorizationHandler, CanManageEmployeeHandler>();

// ---

[HttpPut("{id:int}")]
public async Task<IActionResult> Update(
    int id,
    UpdateEmployeeRequest request,
    [FromServices] IAuthorizationService authorization,
    CancellationToken cancellationToken)
{
    Employee? employee = await employees.GetEntityAsync(id, cancellationToken);

    if (employee is null)
    {
        return NotFound();
    }

    AuthorizationResult decision = await authorization.AuthorizeAsync(
        User, employee, new CanManageEmployeeRequirement());

    if (!decision.Succeeded)
    {
        return Forbid();
    }

    await employees.UpdateAsync(employee, request, cancellationToken);

    return NoContent();
}