Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/adolfok3/authorizationinterceptor
A simple and lightweight .NET package designed to streamline HttpClient authenticated requests
https://github.com/adolfok3/authorizationinterceptor
api auth authentication authorization cache chsarp distributed dotnet dotnet-core headers httpclient interceptor memory request response rest
Last synced: about 2 months ago
JSON representation
A simple and lightweight .NET package designed to streamline HttpClient authenticated requests
- Host: GitHub
- URL: https://github.com/adolfok3/authorizationinterceptor
- Owner: Adolfok3
- License: mit
- Created: 2024-03-27T22:56:45.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2024-04-27T03:44:02.000Z (9 months ago)
- Last Synced: 2024-08-04T09:39:25.912Z (5 months ago)
- Topics: api, auth, authentication, authorization, cache, chsarp, distributed, dotnet, dotnet-core, headers, httpclient, interceptor, memory, request, response, rest
- Language: C#
- Homepage:
- Size: 116 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Authorization Interceptor: A simple and lightweight .NET package designed to streamline HttpClient authenticated requests
[](https://github.com/Adolfok3/AuthorizationInterceptor/actions)
[](./LICENSE)
[](https://coveralls.io/github/Adolfok3/authorizationinterceptor?branch=main)
[](https://www.nuget.org/packages/AuthorizationInterceptor)
## What is Authorization Interceptor?
Authorization Interceptor is a custom handler added to your HttpClient builder. With it, there's no need to worry about the expiration time and management of the authorization headers of your requests. Offering the possibility to use OAuth2 with RefreshToken or custom headers, whenever a request is sent and its response is a status code 401 (Unauthorized), the Interceptor will update the authorization headers and resend the same request with the updated authorization headers.
Authorization Interceptor can use MemoryCache to store authorization headers according to their expiration time, thus, it's not necessary to login or generate authorization every time you need to send a request to the API.
Authorization Interceptor can also share the same authorization headers with other instances of the application (if your application runs in a dockerized environment with Kubernetes) using the idea of distributed cache, avoiding concurrency among instances to log in or generate authorization headers with the API by reusing the authorization generated by the primary instance.
## Getting started
### Installation
Authorization Interceptor is installed [from NuGet](https://nuget.org/packages/authorizationinterceptor). Just run the following command in package manager console:
```
PM> Install-Package AuthorizationInterceptor
```
Or from the .NET CLI as:
```
dotnet add package AuthorizationInterceptor
```
### Setup
When adding a new HttpClient, call the extension method `AddAuthorizationInterceptorHandler`, passing in the authentication class for the target API:
```csharp
services.AddHttpClient("TargetApi")
.AddAuthorizationInterceptorHandler()
```
This will make the `TargetApi` HttpClient use the Authorization Interceptor handler to generate and manage authorization headers.
> By default, the package will not use any interceptor to store authorization headers so the recommendation is to use at least [AuthorizationInterceptor.Extensions.MemoryCache](https://nuget.org/packages/AuthorizationInterceptor.Extensions.MemoryCache) package to store and manage the authorization headers lifecycle. Checkout [Interceptors section](#interceptors).
The `TargetApiAuthClass` must implement the `IAuthenticationHandler` interface, so that the package can perform the necessary dependency injection and know where and when to generate the authorization. An example implementation of the class would look like this:
```csharp
public class TargetApiAuthClass : IAuthenticationHandler
{
public async Task AuthenticateAsync()
{
//The login call to the target API should be placed here, and it should return the authorization headers.
var authorization = LoginToMyTargetApi();
return new OAuthHeaders(authorization.AccessToken, authorization.TokenType, authorization.ExpiresIn, authorization.RefreshToken);
}
public async Task UnauthenticateAsync(AuthorizationHeaders? expiredHeaders)
{
//This method is called when the interceptor captures a response with a status code of 401. It is most commonly used for integrations with APIs that use RefreshToken. If the target API does not have the refresh token functionality, you should implement the same call as in the `AuthenticateAsync` method.
var newHeaders = LoginWithRefreshToMyTargetApi(expiredHeaders.OAuthHeaders.RefreshToken);
return new OAuthHeaders(newHeaders.AccessToken, newHeaders.TokenType, newHeaders.ExpiresIn, newHeaders.RefreshToken);
}
}
```
In the example above, we showed the `TargetApiAuthClass` class, which must implement the authentication methods with the target API. Initially, the authorization headers do not exist, so the package will call the `AuthenticateAsync` method just once and will store the authorization in memory cache (if the MemoryCache package was installed and configured), always consulting it from there. However, if there is a response with status code 401 (unauthorized), the package will call the `UnauthenticateAsync` method, passing the old/expired authorization and will return the new authorization.
> Note that in the `AuthenticateAsync` and `UnauthenticateAsync` methods the return type is `AuthorizationHeaders` but in the example above an `OAuthHeaders` is returned, because in this example we are assuming that the target API uses the OAuth2 authentication mechanism. However, if your target API does not have this functionality you can return a new object of type `AuthorizationHeaders` that inherits from a class `Dictionary`. In practice, it would look like this:
```csharp
public async Task AuthenticateAsync()
{
return new AuthorizationHeaders
{
{ "MyCustomAuthorizationHeader", "MytokenValue" },
{ "SomeOtherAuthorizationHeader", "OtherValue" }
};
}
```
### Custom Options
Assuming that your target API is legacy and it returns not only the status code 401 (unauthorized) for requests without authorization or with expired authorization but also returns 403 (forbidden). For this situation, there is a property in the options class called `UnauthenticatedPredicate` that customizes the type of predicate the package should evaluate for unauthorized requests.
In the extension method `AddAuthorizationInterceptorHandler`, pass this custom configuration in the following way:
```csharp
services.AddHttpClient("TargetApi")
.AddAuthorizationInterceptorHandler(options =>
{
opts.UnauthenticatedPredicate = response => response.StatusCode == System.Net.HttpStatusCode.Forbidden ||
response.StatusCode == System.Net.HttpStatusCode.Unauthorized;
})
```
Now, whenever there is a response with status code 401 or 403, the package will consider the authorization to be expired and will perform a new authentication.
### Interceptors
By default, no interceptors is configured so the recommendation is to use at least [AuthorizationInterceptor.Extensions.MemoryCache](https://nuget.org/packages/AuthorizationInterceptor.Extensions.MemoryCache) package to store and manage the authorization headers lifecycle in a memory cache system.
After install it, its simple to use:
```csharp
services.AddHttpClient("TargetApi")
.AddAuthorizationInterceptorHandler(options =>
{
options.UseMemoryCacheInterceptor();
})
```
#### Available Interceptors
- [AuthorizationInterceptor.Extensions.MemoryCache](https://github.com/Adolfok3/AuthorizationInterceptor.Extensions.MemoryCache)
- [AuthorizationInterceptor.Extensions.Redis](https://github.com/Adolfok3/AuthorizationInterceptor.Extensions.Redis)
> If you need an specific interceptor integration and doesnt exists here, checkout the [AuthorizationInterceptor.Extensions.Abstractions](https://github.com/Adolfok3/AuthorizationInterceptor.Extensions.Abstractions) to create your own interceptor
#### Concurrency
When we have a scalable application running in a dockerized environment with Kubernetes, there can be more than one instance of the same application. This can lead to authentication concurrency issues between instances and divergent authorization headers among them. To solve this, it is recommended to use a custom interceptor that implements the idea of distributed cache. Therefore, in addition to saving the authorization headers in memory, the application will also save them in a distributed cache so that other instances of the application can reuse the authorization already generated by a primary instance. This avoids multiple authentication calls and divergent authorizations.
In practice, simply choose from the available libraries for the package that implement [DistributedCache](https://learn.microsoft.com/en-us/aspnet/core/performance/caching/distributed) and install it in your project. Checkout the [available interceptors section](#available-interceptors).
Let's assume you have installed the [AuthorizationInterceptor.Extensions.Redis](https://github.com/Adolfok3/AuthorizationInterceptor.Extensions.Redis) extension package. In the constructor of the Authorization Interceptor, call the respective extension method. In the example below, we will use the Redis integration to implement the distributed cache.
```csharp
services.AddHttpClient("TargetApi")
.AddAuthorizationInterceptorHandler(options =>
{
options.UseMemoryCacheInterceptor();
options.UseStackExchangeRedisCacheInterceptor(redisOptions =>
{
redisOptions.Configuration = "MyRedisConStr";
redisOptions.InstanceName = "SampleInstance";
})
})
.ConfigureHttpClient(opt => opt.BaseAddress = new Uri("https://targetapi.com"));
```
Adding a MemoryCache with a DistributedCache is a perfect match and recommended way to perform the authorized requests nicely. With this configuration, the Authorization Interceptor will create a sequence with: `MemoryCache > DistributedCache > AuthenticationHandler > DistributedCache > MemoryCache`.
### Custom Interceptors
It's possible to add custom interceptors in the sequence of interceptors. Create your Interceptor class and have it inherit from the interface `IAuthorizationInterceptor`. After that, add it to the constructor of the Authorization Interceptor through the method `UseCustomInterceptor`, e.g.:
```csharp
services.AddHttpClient("TargetApi")
.AddAuthorizationInterceptorHandler(options =>
{
options.UseMemoryCacheInterceptor();
options.UseStackExchangeRedisCacheInterceptor(redisOptions =>
{
redisOptions.Configuration = "MyRedisConStr";
redisOptions.InstanceName = "SampleInstance";
})
options.UseCustomInterceptor();
})
.ConfigureHttpClient(opt => opt.BaseAddress = new Uri("https://targetapi.com"));
```
`MyCustomInterceptor` class:
```csharp
public class MyCustomInterceptor : IAuthorizationInterceptor
{
public async Task GetHeadersAsync(string name)
{
//Do something and return the headers if exists in this context
}
public async Task UpdateHeadersAsync(string name, AuthorizationHeaders? expiredHeaders, AuthorizationHeaders? newHeaders)
{
//Do something with expired headers if necessary and update with newHeaders
}
}
```
With this configuration, the Authorization Interceptor will create a sequence of: `MemoryCache > DistributedCache > MyCustomInterceptor > AuthenticationHandler > DistributedCache > MyCustomInterceptor > MemoryCache`.
> The 'name' parameter refers to the name of the configured HttpClient. With this parameter you can differentiate between multiple httpclients configured using the same interceptor.