Managing Authentication Tokens in .NET Core with HttpClientFactory and DelegatingHandlers

Introduction

In the modern development world, the use of RESTful APIs is prevalent. One of the most common issues encountered during the development and consumption of these APIs is the management of authentication tokens. In this post, we will explore a robust and efficient method for handling authentication tokens using the HttpClientFactory and DelegatingHandler features in .NET Core.

The Problem

When dealing with RESTful APIs, one common way of handling authentication is using bearer tokens. The workflow is simple - the client requests a token from the server, which is then included in the headers of subsequent requests for authentication.

The challenge arises when we need to manage these tokens effectively, ensuring they are available for each request and refreshed when necessary. Using HttpClient directly can lead to problems, such as socket exhaustion, as well as difficulties in managing the lifecycle of tokens.

The Solution: HttpClientFactory and DelegatingHandler

.NET Core offers the HttpClientFactory, which is designed to manage HttpClient instances efficiently. It handles the pooling of HttpMessageHandler instances, avoiding the mentioned socket exhaustion issue, and it allows for more granular control over the configuration of HttpClient instances.

DelegatingHandler is another feature of .NET Core that comes in handy. These handlers form a part of the HttpClient’s message handler pipeline and can be used to operate on the HttpRequestMessage or HttpResponseMessage, making them an excellent place to handle our token management.

Thread Safety

In .NET, HttpClient is intended to be instantiated once and reused throughout the life of an application. However, while HttpClient is thread-safe, it doesn’t mean that all properties of HttpClient are thread-safe. For instance, if you set properties such as DefaultRequestHeaders in different threads, it can cause race conditions and lead to unexpected behavior.

HttpClientFactory helps manage HttpClient instances’ lifecycle, ensuring that each outgoing request gets a new HttpClient instance and thus a clean state. This also allows safe manipulation of HttpClient properties per request while still benefiting from the HttpClient’s internal connection pooling and socket reuse, providing an efficient and thread-safe way to handle outgoing HTTP requests.

services.AddHttpClient("MyClient", c =>
    {
        c.BaseAddress = new Uri("https://myapi.com/");
    })
    .AddHttpMessageHandler<AuthorizationHeaderHandler>();

In the example above, the HttpClientFactory provides a new HttpClient instance for each “MyClient” request, ensuring that any configuration applied to the HttpClient is local to that request.

Performance Implications

The HttpClient class is used to send HTTP requests and receive HTTP responses from a resource identified by a URI. However, when used incorrectly, it can lead to socket exhaustion on the host system. This happens because each time an HttpClient instance is created, a new socket is created. If the HttpClient instances are not properly managed or disposed, these sockets may linger and eventually exhaust the available sockets on the host.

The HttpClientFactory mitigates this issue by pooling and reusing HttpClient instances, reducing the chance of socket exhaustion. Each HttpClient instance created by the HttpClientFactory shares a single HttpMessageHandler, which, in turn, shares a single socket. This not only prevents socket exhaustion but also makes the sending of HTTP requests more efficient.

services.AddTransient<AuthorizationHeaderHandler>();

services.AddHttpClient("MyClient", c =>
    {
        c.BaseAddress = new Uri("https://myapi.com/");
    })
    .AddHttpMessageHandler<AuthorizationHeaderHandler>();

In the example above, the HttpClientFactory provides a new HttpClient instance for each “MyClient” request but shares the underlying HttpMessageHandler and, by extension, the socket, thus ensuring efficient usage of system resources.

Implementing a DelegatingHandler for Token Management

We will create a DelegatingHandler that will run just before the HTTP request is sent, where we can set the Authorization header for every HTTP request made by the HttpClient instance.

public class AuthorizationHeaderHandler : DelegatingHandler
{
    private readonly IMyTokenService _myTokenService;

    public AuthorizationHeaderHandler(IMyTokenService myTokenService)
    {
        _myTokenService = myTokenService;
    }

    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
    {
        string accessToken = await _myTokenService.GetAccessTokenAsync();
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
        return await base.SendAsync(request, cancellationToken);
    }
}

In this example, we inject a token service (IMyTokenService) responsible for retrieving the access token. The handler sets the “Authorization” header with the “Bearer” scheme followed by the access token.

Registering Our Handler

To use our new DelegatingHandler, we need to register it in the Startup.ConfigureServices method.

services.AddTransient<AuthorizationHeaderHandler>();

services.AddHttpClient("MyClient", c =>
    {
        c.BaseAddress = new Uri("https://myapi.com/");
    })
    .AddHttpMessageHandler<AuthorizationHeaderHandler>();

In this example, we register the handler as a transient service, aligning with the lifetime of HttpClient. It ensures that each HttpClient instance gets its own fresh handler instance, avoiding any concerns about thread-safety or state being inadvertently shared between different requests.

Troubleshooting

If you encounter any issues while implementing this solution, here are some common problems and their respective solutions:

1. Issue: “Authentication token is not being refreshed” - This might be due to the token expiration time not being considered in the ShouldRenewToken method of your TokenHandler class. Make sure you subtract an appropriate buffer time before the token’s actual expiration time to account for any delays.

2. Issue: “I’m getting 401 Unauthorized responses” - This might be because the new token is not being attached to the outgoing request. Ensure that the AttachTokenToRequest method in your TokenHandler class is correctly setting the Authorization header of the request.

3. Issue: “The token service is not generating new tokens” - This could be due to an issue with the ITokenService implementation. Verify that the service is correctly calling the token endpoint and handling the response.

Remember, it’s crucial to log any exceptions or errors that occur during these processes. This will make it easier to diagnose and resolve any issues that come up.

If you’re still facing problems after checking these common issues, please feel free to reach out for further assistance.

Further Reading

If you want to delve further into managing Authentication tokens and related topics, here are some recommended resources:

1. HttpClientFactory in ASP.NET Core 2.1: A detailed blog post by Steve J Gordon, explaining the purpose and benefits of HttpClientFactory.
2. DelegatingHandler in ASP.NET Web API: This Microsoft documentation page provides an in-depth explanation of DelegatingHandler.

Conclusion

The HttpClientFactory and DelegatingHandler features in .NET Core provide a powerful and efficient way to manage authentication tokens when consuming RESTful APIs. By implementing a custom DelegatingHandler, we can centralize our token management logic, ensuring that every request made by our HttpClient instances includes the necessary tokens for authentication. This approach helps to write cleaner, more maintainable code and avoid common pitfalls associated with HttpClient usage and token management.

Feedback and Questions

We’d love to hear your feedback on this tutorial! If you have any questions or suggestions for improvement, please don’t hesitate to reach out. You can leave a comment below, or you can contact us through the following channels:

1. Email: shady@shadynagy.com
2. Twitter: @ShadyNagy_
3. LinkedIn: Shady Nagy
4. GitHub: ShadyNagy

We’ll do our best to address any questions or concerns you may have. We look forward to hearing from you and helping you make the most of HttpClientFactory and DelegatingHandlers in .NET Core!