Intility.Extensions.HttpClientAuthorization 2025.5.7-preview-1

Intility.Extensions.HttpClientAuthorization

Extensions to help authenticate System.Net.Http.HttpClients and handle key rotation in web services and backends using delegated authentication scenarios.

Motivation

Microsoft Secure App Model requires a delegated access paradigm where service → service authentication scenarios are difficult to handle. The system administrator would need to sign in on behalf of the service and handle access-token and refresh-token rotation in the background.

This package aims to ease the pain with automatic token acquisition and rotation as well as renewal of Authorization headers on HttpClients respectively.

Installation

Install Intility.Extensions.HttpClientAuthorization with the NuGet package manager in Visual Studio or via CLI:

dotnet add package Intility.Extensions.HttpClientAuthorization

Configuring the http clients

The client configuration should be stored in appsettings.json and extracted at runtime.

appsettings.json

{
  "Clients": {
    "PartnerCenter": {
      "TenantId": "<your-tenant-id>",
      "ClientId": "<appid-with-delegated-permission>",
      "Scopes": [ "https://api.partnercenter.microsoft.com/user_impersonation" ]
    },
    "Graph": {
      "TenantId": "<your-tenant-id>",
      "ClientId": "<appid-with-delegated-permission>",
      "Scopes": [ "https://graph.microsoft.com/User.Read" ]
    }
  }
}

Program.cs / Startup.cs

services
    .AddHttpClient<IGraphService, GraphService>()
    .AddClientAuthentication(auth => 
        auth.UseDeviceCodeDelegation(options =>
            Configuration.GetSection("Clients:PartnerCenter").Bind(options)));

Notice that we are instrumenting a client for a specific service. This will ensure that when the GraphService requires an HttpClient in its contructor we will provide the configured client. This examples uses a TypedClient pattern, but other patters are also available. See Make HTTP requests using IHttpClientFactory in ASP.NET Core.

.AddClientAuthentication() ensures that your configuration in incorporated in the authentication policy. UseDeviceCodeDelegation is useful because it requires no browser on the host but instead prompts for a one-time-password for the system administrator to authenticate the client on another process/host.

NOTE

Authentication challenge will be prompted via the AspNet Logging mechanism and should output to the Console by default.

Required depdendencies

To store and protect the credentials the system uses configurable components from the AspNet ecosystem. IDistributedCache for storage and DataProtection for key protection.

IDistributedCache

IDistributedCache has a default InMemory implementation but can (and should) be configured to store cache off process. Some out-of-the box implementations can be installed with its own package:

• SQL Distributed Cache
• Redis Distributed Cache
• NCache Distributed Cache

DataProtection

To ensure that the cache is encrypted at rest we're using the DataProtection extensions to protect/unprotect the cache payload in the cache. Protection method is configurable with additional packages. See Configure ASP.NET Core Data Protection for more information.

Using the clients

The authorization negotiation and acquisition is handled inside the HttpMessageHandler and should not interfere with normal use. See examples below or a complete example in the /samples folder.

GraphService.cs

public interface IGraphService
{
    Task<string> GetMePayload();
}

public class GraphService : IGraphService
{
    private readonly HttpClient _httpClient;

    /// <summary>
    /// Receives a HttpClient from the dependency container.
    /// This client is configured with authentication policy 
    /// in Startup.cs
    /// </summary>
    /// <param name="httpClient"></param>
    public GraphService(HttpClient httpClient)
    {
        _httpClient = httpClient;
    }

    public async Task<string> GetMePayload()
    {
        var response = await _httpClient.GetAsync("https://graph.microsoft.com/v1.0/me");
        var json = await response.Content.ReadAsStringAsync();

        return json;
    }
}

GraphExampleController.cs

[ApiController]
[Route("[controller]")]
public class GraphExampleController : ControllerBase
{
    private readonly IGraphService _graphService;

    public GraphExampleController(IGraphService graphService)
    {
        _graphService = graphService;
    }

    [HttpGet]
    public async Task<IActionResult> Get()
    {
        var content = await _graphService.GetMePayload();
        return Content(content, "application/json");
    }
}