Intility.Extensions.HttpClientAuthorization 1.0.3

Intility.Extensions.HttpClientAuthorization

A .NET library providing HTTP client extensions for delegated authentication scenarios with automatic token acquisition, rotation, and header renewal.

Motivation

Microsoft's secure app model relies on delegated access, complicating service-to-service authentication. Administrators must manage interactive sign-ins and token (access and refresh) rotation. This library automates:

• Access token acquisition via device-code flow
• Transparent token and header renewal
• Secure caching and key protection

Installation

Install via NuGet:

dotnet add package Intility.Extensions.HttpClientAuthorization

Configuration

Define your HTTP clients in appsettings.json:

{
  "Clients": {
    "PartnerCenter": {
      "TenantId": "<YOUR_TENANT_ID>",
      "ClientId": "<CLIENT_WITH_DELEGATED_PERMISSIONS>",
      "Scopes": ["https://api.partnercenter.microsoft.com/user_impersonation"]
    }
  }
}

Register and configure your clients in Program.cs or Startup.cs:

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

This registers a typed client (PartnerService) and injects an HttpClient preconfigured with the device-code authentication handler.

Note: Authentication prompts appear via ASP.NET Core logging (e.g., console output).

Dependencies

Token persistence and protection rely on ASP.NET Core components:

• IDistributedCache: Default in-memory cache; recommend configuring a distributed provider as described in ASP.NET Core Distributed Cache documentation or otherwise lose tokens on service restarts.
• Data Protection: Encrypts cached tokens at rest. Configure data protection per ASP.NET Core Data Protection documentation.

Usage

Authentication is handled transparently in the HTTP pipeline. Use injected HttpClient instances as usual.

Example: PartnerService

public interface IPartnerService
{
    Task<string> GetCustomers();
}

public class PartnerService(HttpClient _httpClient) : IPartnerService
{
    public async Task<string> GetCustomers()
    {
        var response = await _httpClient.GetAsync("https://api.partnercenter.microsoft.com/v1/customers");
        response.EnsureSuccessStatusCode();

        return await response.Content.ReadAsStringAsync();
    }
}

Samples

See the samples/ directory for complete implementations.

Contributing

We welcome contributions from engineers within our organization to enhance and expand the capabilities of the Intility.Extensions.HttpClientAuthorization library. Please follow the guidelines below to ensure a smooth contribution process:

Branch Protection

The main branch is protected. All contributions must go through a pull request (PR) process. Edits made directly to the main branch will get blocked.

Workflow for Contributions

1. Create a Feature Branch: Clone the repository and create a new branch from main to house your feature or fix. Use descriptive names for your branches, preferably related to the issue or enhancement you are working on.

2. Commit Changes Using Conventional Commits: When committing changes, adhere to conventional commit standards to make changelog generation straightforward. This helps in automating the release process.

3. Open a Pull Request: Once your changes are ready, open a PR back to the main branch. Ensure your PR includes relevant descriptions, references to any issues, and testing documentation where applicable.

4. Automated Build and Test: Upon submitting a PR, GitHub Actions will automatically trigger the Build and Test workflow (.github/workflows/pr.yaml). It's imperative to ensure that all checks pass successfully before considering a merge.

5. Review and Merge: After the PR is approved and merges into main, it initiates a subsequent release pipeline. This pipeline creates a release PR with a generated changelog, based on your conventional commits, and a prerelease (timestamped) package on nuget.org.

6. Updating Release PR: If multiple feature branches are merged into main, the release PR will automatically update with additional changelog entries, reflecting the cumulative changes and updated prerelease packages.

7. Verification: At this stage, you have the opportunity to verify the functionality and reliability of the prerelease package. Thorough testing and validation should be carried out to ensure the package performs as expected in a production-like environment.

8. Release: Once satisfied with the prerelease, merge the generated release PR. This will result in a semantic version tag and trigger the Release Package workflow (.github/workflows/release.yaml) which publishes a proper NuGet release.