Another.OAuth2.ClientUtility.ClientCredentialsFlow 1.0.0

Another OAuth2 Client Credentials Utility

A modular .NET 8 library that provide an OAuth2 client credentials token acquisition, in-memory caching and HttpClient bearer injection

• Automatic access token retrieval and refresh.
• Caching of tokens (in-memory by default).
• Plug-in architecture for token storage (e.g. future Redis) implementing the IAccessTokenCache interface.
• Simple service registration via extension methods.
• Seamless bearer injection using a delegating handler.

You can reuse a named HttpClient across your application, the first outbound request triggers token acquisition, subsequent requests reuse the cached token until refresh is required.

Why this library exists

This project was born from a practical limitation encountered when integrating with an OAuth 2.0 authorization server that did not expose a valid OpenID Connect Discovery document (the .well-known/openid-configuration endpoint).

Because of this missing endpoint, it wasn’t possible to use MSAL.NET - Microsoft’s official library - even though the latest versions of MSAL now support the Client Credentials flow for non-Azure OAuth 2.0 providers. This library therefore provides a lightweight and fully configurable alternative, allowing you to:

• Work with any OAuth 2.0 server that supports the Client Credentials flow, even without OpenID Connect metadata
• Plug in your own endpoints for token acquisition
• Keep a clean separation between token management, caching, and HTTP request logic
• Is possible to extend the OAuth 2.0

Use it when your identity provider doesn’t fully implement OpenID Connect discovery or when you simply prefer a minimal, dependency-free solution focused on server-to-server authentication.

Extensibility

Although this library currently focuses on the Client Credentials flow, its architecture was designed with extensibility in mind.
You can easily extend it to support additional OAuth 2.0 grant types or custom authentication mechanisms by:

• Implementing your own IAccessTokenProvider to handle alternative flows (e.g. Resource Owner Password, JWT Bearer, or Device Code)
• Reusing the same caching and injection infrastructure already in place
• Registering your provider through the existing dependency injection extensions

This makes the library a flexible foundation for building modular authentication clients that can adapt to different OAuth 2.0 scenarios.

Contents

• NuGet Package
• Projects
• Quick Start
• Configuration
• Sample Console App
• How Automatic Token Injection Works
• Multiple Clients
• Redis / Distributed Cache Extension (For future implementation)
• Extensibility Points
• Diagnostics & Logging
• Security Considerations
• Troubleshooting
• Roadmap / Ideas / Contributions needed
• License

NuGet Package

Install the package via NuGet Package Manager Console:

dotnet add package Another.OAuth2.ClientUtility.ClientCredentialsFlow.NuGet

The package includes:

• In-memory token caching by default.
• Automatic token refresh before expiration.
• HttpClient integration via delegating handler.
• Extensible architecture for custom token providers and cache implementations.

Projects in this repository

Quick Start

1. Prepare configuration (appsettings.json):

{
"OAuthClients":{
   "SampleApi":{
      "TokenEndpoint":"https://demo.duendesoftware.com/connect/token",
      "ClientId":"m2m",
      "ClientSecret":"secret",
      "Scope":"api",
      "RefreshBeforeExpiration":"00:00:05"
   }
},
"ProtectedApis":{
   "SampleApi":{
      "BaseUrl":"https://demo.duendesoftware.com/"
   }
}
}

2. Register services in Program.cs:

services.AddClientCredentialsHttpClient( "SampleApi", configuration.GetSection("OAuthClients:SampleApi")) .ConfigureHttpClient((sp, client) => { var baseUrl = configuration.GetValue<string>("ProtectedApis:SampleApi:BaseUrl"); client.BaseAddress = new Uri(baseUrl); });

3. Inject and use HttpClient:

public class MyService { 

private readonly HttpClient _httpClient; 

public MyService(HttpClient httpClient) { _httpClient = httpClient; } 

public async Task CallApiAsync() { 

    var response = await _httpClient.GetAsync("api/data"); 
    response.EnsureSuccessStatusCode(); 

    var content = await response.Content.ReadAsStringAsync(); 
    Console.WriteLine(content); 
 } 
}

4. Run your application, the first API call will automatically handle token acquisition and injection.

Configuration

ClientCredentialsOptions (named options per client):

• TokenEndpoint (required) – full token endpoint URL (e.g. https://demo.duendesoftware.com/connect/token)
• ClientId, ClientSecret (required)
• Scope (optional) – space-delimited or single scope
• Audience (optional)
• AdditionalBodyParameters / AdditionalHeaders (optional dictionaries)
• RefreshBeforeExpiration – subtract time from token expiry to refresh early
• Timeout – per token request

Protected API settings (SampleClientSettings in sample) supply base URL only.

Sample Console App

Entry point: SampleConsoleRunner:

var client = _httpClientFactory.CreateClient(SampleConsoleRunner.SampleClientName); 
var json = await client.GetStringAsync("api/test"); 

_logger.LogInformation("Protected API response: {Response}", json);

How Automatic Token Injection Works

1. You register a named HttpClient via AddClientCredentialsHttpClient.
2. The extension:
   • Adds the token provider (for contacting the OAuth token endpoint).
   • Registers a keyed internal token manager (one per client name).
   • Attaches ClientCredentialsDelegatingHandler.
3. On first outbound request:
   • Handler sees no Authorization header.
   • Requests a token via the manager & provider.
   • Injects Authorization: Bearer <token>.
4. Subsequent requests reuse cached token until near expiry.
5. On expiry or pre-refresh moment, a new token is fetched (single-threaded via semaphore).

Multiple Clients

Register multiple:

services.AddClientCredentialsHttpClient("CatalogApi", config.GetSection("OAuthClients:CatalogApi")) .ConfigureHttpClient((_, c) => c.BaseAddress = new Uri(config["ProtectedApis:CatalogApi:BaseUrl"]));
services.AddClientCredentialsHttpClient("ReportsApi", config.GetSection("OAuthClients:ReportsApi")) .ConfigureHttpClient((_, c) => c.BaseAddress = new Uri(config["ProtectedApis:ReportsApi:BaseUrl"]));

Use via named HttpClient:

var catalogClient = _httpClientFactory.CreateClient("CatalogApi");
var reportsClient = _httpClientFactory.CreateClient("ReportsApi");

Each client has isolated options, cache, and refresh lifecycle.

Redis / Distributed Cache Extension (Not implemented, this is an example on how to use third parties caching systems)

Introduce an abstraction already defined:

public interface IAccessTokenCache { Task<AccessToken?> GetAsync(string clientName, CancellationToken ct = default); Task SetAsync(string clientName, AccessToken token, CancellationToken ct = default); }

Create a Redis implementation (example):

public sealed class RedisAccessTokenCache : IAccessTokenCache { private readonly IConnectionMultiplexer _redis; public RedisAccessTokenCache(IConnectionMultiplexer redis) => _redis = redis;

public async Task<AccessToken?> GetAsync(string clientName, CancellationToken ct)
{
    var db = _redis.GetDatabase();
    var raw = await db.StringGetAsync($"oauth:token:{clientName}");
    if (raw.IsNullOrEmpty) return null;
    var parts = raw.ToString().Split('|', 2);
    return parts.Length == 2 && DateTimeOffset.TryParse(parts[1], out var exp)
        ? new AccessToken(parts[0], exp)
        : null;
}

public async Task SetAsync(string clientName, AccessToken token, CancellationToken ct)
{
    var db = _redis.GetDatabase();
    var value = $"{token.Value}|{token.ExpiresAt:O}";
    var ttl = token.ExpiresAt - DateTimeOffset.UtcNow;
    await db.StringSetAsync($"oauth:token:{clientName}", value, ttl > TimeSpan.Zero ? ttl : TimeSpan.FromMinutes(5));
}
}

Wire it in place of the memory cache:

services.AddSingleton<IAccessTokenCache, RedisAccessTokenCache>();

Done, whitout any change to handlers or consumers.

Extensibility Points

You can also add a proactive refresh background service if you need zero latency on first post-expiration call (optional).

Diagnostics & Logging

Log levels:

• Trace: token reuse / header injection decisions.
• Debug: token request boundaries.
• Error: token endpoint failures.

Security Considerations

• Store ClientSecret securely (user secrets, environment variables, Azure Key Vault).
• Avoid logging the full token; truncate if needed.
• Prefer HTTPS for both token and resource endpoints (enforced by Uri usage).
• Rotate client secrets periodically.
• If using distributed cache, consider encrypting access tokens at rest.

Troubleshooting

Roadmap / Ideas / Contributions needed

• Adding Unit Test coverage.
• Proactive token refresh service that refreshes before expiry in background.
• Metrics (events: token requested / reused / expired).
• Polly integration for transient token endpoint retry logic, because now it fails immediately on error responses, which may be too harsh for some scenarios, maybe is better to retry a few times.
• Redis / Memory hybrid fallback cache (try Redis, fallback to memory).
• Find a way that makes third party cache easier to integrate with minimal code (e.g. via NuGet).

License

See LICENSE file.

Disclaimer

The sample uses the public Duende demo (https://demo.duendesoftware.com), intended for development only. Do not rely on demo credentials or endpoints in production.

Feedback or contributions are super-welcome, feel free to open issues or pull requests. Happy coding 😊