AuthorizationInterceptor 6.1.0

Authorization Interceptor

A lightweight .NET library that automatically manages HTTP authentication headers for HttpClient. When a request receives a 401 response, the interceptor re-authenticates and retries with fresh headers — no manual token management required.

Features

• Automatic retry on auth failure — intercepts 401 responses and retries with fresh headers
• OAuth2 refresh token support — reuse existing tokens via RefreshToken flow
• Custom header support — return any key-value authorization headers
• Multiple cache backends — in-memory, distributed (Redis/NCache), or hybrid caching
• Deduplicated authentication — concurrent requests share a single authentication call per cache key
• Extensible interceptor chain — compose your own caching and logging strategies
• Multi-target framework support — .NET 8+

Quick Start

Install the core package:

dotnet add package AuthorizationInterceptor

Step 1: Implement authentication logic

Create a class that implements IAuthenticationHandler:

public class TargetApiAuth : IAuthenticationHandler
{
    private readonly HttpClient _client;

    public TargetApiAuth(HttpClient client)
    {
        _client = client;
    }

    public async ValueTask<AuthorizationHeaders?> AuthenticateAsync(
        AuthorizationHeaders? expiredHeaders, CancellationToken ct)
    {
        if (expiredHeaders == null)
        {
            // First login — request a fresh token
            var response = await _client.PostAsync("auth", content: null, ct);
        }
        else
        {
            // Token expired — refresh it using the existing refresh token
            // This step is only applicable to APIs integrating with OAuth refresh tokens
            var refreshToken = expiredHeaders.OAuthHeaders!.RefreshToken;
            var response = await _client.PostAsync($"refresh?refresh={refreshToken}", content: null, ct);
        }

        var json = await response.Content.ReadAsStringAsync(ct);
        var tokens = JsonSerializer.Deserialize<UserTokens>(json)!;

        return new OAuthHeaders(
            accessToken: tokens.AccessToken,
            tokenType: tokens.TokenType,
            expiresIn: tokens.ExpiresIn,
            refreshToken: tokens.RefreshToken,
            refreshTokenExpiresIn: tokens.RefreshAccessTokenExpiresIn);
    }
}

public record UserTokens(string AccessToken, string TokenType, int ExpiresIn, string RefreshToken, int RefreshAccessTokenExpiresIn);

Step 2: Register the handler

builder.Services.AddHttpClient("TargetApi")
    .AddAuthorizationInterceptorHandler<TargetApiAuth>()
    .ConfigureHttpClient(c => c.BaseAddress = new Uri("https://targetapi.com"));

That's it. Calls to this HttpClient will automatically retry with fresh authorization headers when a 401 is received.

Caching & Interceptors

By default, without any cache interceptor, a new access token is generated on every expiration. For production deployments, use one of the cache interceptors below to avoid redundant authentication calls.

Available Packages

Recommended configuration: Hybrid Cache

builder.Services.AddHttpClient("TargetApi")
    .AddAuthorizationInterceptorHandler<TargetApiAuth>(options =>
    {
        options.UseHybridCacheInterceptor(); // memory → distributed → auth handler
    })
    .ConfigureHttpClient(c => c.BaseAddress = new Uri("https://targetapi.com"));

This uses an in-memory cache first (fastest), falls back to distributed cache, then calls the authentication handler only when no cached token exists. Instances share the same token through the distributed layer, which avoids redundant login calls.

Concurrency

When several requests need headers at the same time and none are cached, only one of them calls the authentication handler. The others wait, then reuse whatever it stored in the interceptors. The same applies after an unauthenticated response: a request only refreshes the token if no one else has already replaced the one that was rejected.

This deduplication is scoped to the process, and to the HttpClient name plus the CacheKeyBuilder suffix — different cache keys never block each other. Across instances it is the shared cache, not a lock, that keeps authentication calls down: with a cold distributed cache, two instances can still authenticate at the same time. If your provider invalidates the previous token on every issuance, keep that in mind when scaling out.

Deduplication requires at least one cache interceptor. Without one there is nothing to share, so every request authenticates on its own.

Options & Customization

Retry on 403 as well as 401

Some APIs return 403 instead of 401 when tokens expire:

builder.Services.AddHttpClient("TargetApi")
    .AddAuthorizationInterceptorHandler<TargetApiAuth>(options =>
    {
        options.UnauthenticatedPredicate = response =>
            response.StatusCode is HttpStatusCode.Forbidden or HttpStatusCode.Unauthorized;
    });

Multiple HttpClient instances with different auth data

When you need to pass extra dependencies into your authentication handler:

builder.Services.AddHttpClient("TargetApi")
    .AddAuthorizationInterceptorHandler((sp) =>
        ActivatorUtilities.CreateInstance<TargetApiAuth>(sp, someOtherDependency));

Per-request cache keys

When the same HttpClient is used for the same target API, but authorization headers must be cached separately by a request value, configure CacheKeyBuilder.

This is useful when a single integration can authenticate on behalf of different users, tenants, stores, organizations, or any other request-scoped identifier. The value returned by CacheKeyBuilder is appended to the cache key used by the configured cache interceptor.

Example using the authenticated user:

builder.Services.AddHttpClient("TargetApi")
    .AddAuthorizationInterceptorHandler<TargetApiAuth>(options =>
    {
        options.UseHybridCacheInterceptor();
        options.CacheKeyBuilder = accessor =>
            accessor.HttpContext?.User.FindFirst("sub")?.Value;
    });

Example using a route or query value:

builder.Services.AddHttpClient("TargetApi")
    .AddAuthorizationInterceptorHandler<TargetApiAuth>(options =>
    {
        options.UseDistributedCacheInterceptor();
        options.CacheKeyBuilder = accessor =>
        {
            var httpContext = accessor.HttpContext;
            var storeId = httpContext?.Request.RouteValues["storeId"]?.ToString()
                ?? httpContext?.Request.Query["storeId"].ToString();

            return string.IsNullOrWhiteSpace(storeId) ? null : storeId;
        };
    });

With this configuration, requests using the same HttpClient but different HttpContext.Request values will not share the same cached authorization headers.

If CacheKeyBuilder returns null or an empty value, the interceptor uses the default cache key for the HttpClient name.

Interceptors receive the two halves already combined, as a single key parameter: the HttpClient name on its own when no suffix applies, or {name}_{suffix} when one does.

Custom interceptors

Add custom logic steps to the interceptor chain:

builder.Services.AddHttpClient("TargetApi")
    .AddAuthorizationInterceptorHandler<TargetApiAuth>(options =>
    {
        options.UseMemoryCacheInterceptor();
        options.UseCustomInterceptor<MyLoggingInterceptor>();
    });

Implement IAuthorizationInterceptor:

public class MyLoggingInterceptor : IAuthorizationInterceptor
{
    public ValueTask<AuthorizationHeaders?> GetHeadersAsync(
        string key, CancellationToken ct)
        => new(new AuthorizationHeaders());

    public ValueTask UpdateHeadersAsync(
        string key, AuthorizationHeaders? expiredHeaders,
        AuthorizationHeaders? newHeaders, CancellationToken ct)
    {
        // Log or transform headers between cache and auth handler
        return default;
    }
}

The interceptor chain becomes: MemoryCache → MyLoggingInterceptor → AuthHandler → MyLoggingInterceptor → MemoryCache. Build your own cache backend by targeting AuthorizationInterceptor.Extensions.Abstractions.

Sample Applications

Run a working demo with a mock API endpoint:

cd samples
dotnet run --project TargetApi   # starts mock auth server on :5001
# in another terminal:
dotnet run --project SourceApi   # calls the mock API with interceptor enabled

Source: Samples

License

This project is licensed under the MIT License. See LICENSE.