Cuemon.Extensions.AspNetCore.Authentication

Overview

Cuemon.Extensions.AspNetCore.Authentication adds ASP.NET Core-facing registration and pipeline helpers on top of Cuemon.AspNetCore.Authentication. It gives you builder extensions for Basic, Digest, and HMAC schemes, direct middleware registration helpers, and an authorization result handler that turns challenge and forbid outcomes into negotiated HTTP responses.

The package also includes the supporting registrations needed around those features, such as an in-memory digest nonce tracker and options that control how authorization failures are translated into HttpStatusCodeException responses. Use it when you want Cuemon authentication primitives to fit naturally into ASP.NET Core service configuration and request processing.

Key APIs

AddBasic registers BasicAuthenticationHandler on an AuthenticationBuilder under the Basic scheme and validates the supplied BasicAuthenticationOptions before the scheme is added.

AddDigestAccess registers DigestAuthenticationHandler on an AuthenticationBuilder under the Digest scheme and is the service-configuration entry point when you want digest authentication to run through ASP.NET Core authentication services.

AddHmac registers HmacAuthenticationHandler on an AuthenticationBuilder, but unlike the fixed Basic and Digest registrations it uses the configured HmacAuthenticationOptions.AuthenticationScheme value as the scheme name.

UseBasicAuthentication, UseDigestAccessAuthentication, and UseHmacAuthentication add the corresponding configurable middleware directly to an IApplicationBuilder pipeline through MiddlewareBuilderFactory.UseConfigurableMiddleware, which is useful when you want middleware-first composition instead of AuthenticationBuilder registration.

AddInMemoryDigestAuthenticationNonceTracker registers MemoryNonceTracker as the singleton INonceTracker implementation needed by the digest authentication handler and middleware.

AddAuthorizationResponseHandler registers AuthorizationResponseHandler as a singleton and also propagates the configured SensitivityDetails into shared ExceptionDescriptorOptions, so authorization failures and exception descriptors use the same disclosure policy.

AuthorizationResponseHandlerOptions controls the fallback authorization result handler, the delegate that maps an AuthorizationFailure into an HttpStatusCodeException, the sensitivity level of the serialized fault details, and the async cancellation settings inherited from AsyncOptions.

AuthorizationResponseHandler implements IAuthorizationMiddlewareResultHandler and first preserves the normal challenge or forbid flow, then tries to select a matching exception response formatter from the request Accept header before falling back to the default authorization middleware result handler if negotiated output fails.

Basic usage

Use this pattern when you want a single registration point for Cuemon's authorization result handler and its response-sensitivity policy before adding authentication schemes and authorization policies. It matters because the package wires both the handler registration and the shared exception descriptor options from the same configuration, which keeps authorization failure output consistent.

using System.Linq;
using Codebelt.Extensions.Xunit;
using Cuemon.Diagnostics;
using Cuemon.Extensions.AspNetCore.Authentication;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;
using Xunit;

namespace MyProject.Tests;

public class AuthorizationResponseHandlerRegistrationTest : Test
{
    public AuthorizationResponseHandlerRegistrationTest(ITestOutputHelper output) : base(output) { }

    [Fact]
    public void AddAuthorizationResponseHandler_ShouldShareConfiguredSensitivity()
    {
        var services = new ServiceCollection();
        services.AddAuthorizationResponseHandler(o => o.SensitivityDetails = FaultSensitivityDetails.All);
        using var provider = services.BuildServiceProvider();
        var handlerOptions = provider.GetRequiredService<IOptions<AuthorizationResponseHandlerOptions>>().Value;
        var descriptorOptions = provider.GetRequiredService<IOptions<ExceptionDescriptorOptions>>().Value;
        var handler = services.Single(sd => sd.ServiceType == typeof(AuthorizationResponseHandler));

        TestOutput.WriteLine($"Lifetime: {handler.Lifetime}; Sensitivity: {descriptorOptions.SensitivityDetails}");
        Assert.Equal(ServiceLifetime.Singleton, handler.Lifetime);
        Assert.Equal(FaultSensitivityDetails.All, handlerOptions.SensitivityDetails);
        Assert.Equal(FaultSensitivityDetails.All, descriptorOptions.SensitivityDetails);
        Assert.NotNull(handlerOptions.FallbackResponseHandler);
    }
}

Installation

dotnet add package Cuemon.Extensions.AspNetCore.Authentication

Usage guidance

Adopt this package when you want Cuemon's Basic, Digest, or HMAC authentication primitives to plug into ASP.NET Core through AuthenticationBuilder, direct middleware registration, or negotiated authorization-failure responses. If you only need the lower-level authentication types themselves, or you are staying with the default ASP.NET Core authorization response behavior, start with Cuemon.AspNetCore.Authentication or the built-in ASP.NET Core authentication stack instead.