HmacManager 2.5.1

HmacManager

• Quickstart
  • Register without built-in authentication flow
  • Register with built-in authentication flow
  • Register with an IConfigurationSection
  • Register HttpClient with HmacHttpMessageHandler
• In-Depth Tutorial
  • Event handling with the HmacEvents object
  • Dynamic policies with IHmacPolicyCollection
  • Dynamic policies with a scoped IHmacPolicyCollection
  • Enable consolidated headers
  • Custom signing content for Hmac

Quickstart

A short and sweet overview of how to register HmacManager to help you get up and running. There are two methods of dependency injection registration. You should choose the one appropriate for your situation and how much flexibility you might require.

• Register without built-in authentication flow
  • Registers only the HmacManager object through an IHmacManagerFactory service where you will be required to handle signatures and verification manually. An implementation of IHmacManagerFactory is registered with the DI container automatically. This is how you will instantiate HmacManager objects.
• Register with built-in authentication flow
  • Automatically registers an authentication handler and maps any authenticated request headers defined by a scheme to claims. This method handles verifying incoming requests without any additional setup.

Register without built-in authentication flow

Use the IServiceCollection extension method AddHmacManager to add all of the necessary components for HmacManager to the DI container.

builder.Services.AddHmacManager(options => ...);

Configure one or more policies with the options builder.

options.AddPolicy("SomePolicy", policy =>
{
    policy.UsePublicKey(...);
    policy.UsePrivateKey(...);
    policy.UseMemoryCache(...);
});

Access an instance of a HmacManager responsible for a specified policy from IHmacManagerFactory.

var hmacManager = hmacManagerFactory.Create("SomePolicy");

A policy can be extended with schemes. These schemes represent the required headers that must be present in a request. The values of these headers become a part of the signing content.

builder.Services.AddHmacManager(options =>
{
    options.AddPolicy("SomePolicy", policy =>
    {
        policy.UsePublicKey(...);
        policy.AddScheme("SomeScheme", scheme =>
        {
            scheme.AddHeader("X-UserId");
            scheme.AddHeader("X-Email");
        });
    });
});

Register with built-in authentication flow

The AddHmacManager extension method can be bypassed in favor of the IAuthenticationBuilder extension method AddHmac.

builder.Services
    .AddAuthentication()
    .AddHmac(options => options.AddPolicy("SomePolicy", policy => ...));

• The HmacAuthenticationHandler handles parsing incoming requests and authenticating the correct scheme.
  • By default, if there is a policy that matches the one defined in the request headers that can be successfully verified, then the handler returns a success. If more granular authentication is required, such as protecting routes with specific policies or schemes, then there are a couple options available:

    • Use HmacAuthenticateAttribute to specify exact policies and schemes required to authenticate a given endpoint.

        [HmacAuthenticate(Policy = "HmacPolicy", Scheme = "HmacScheme")]
        public class HomeController : Controller
      

    • Use HmacAuthenticateAttribute as an IAuthorizationRequirement to an authorization policy and register the HmacAuthorizationHandler to handle the requirement automatically.

        builder.Services.AddAuthorization(options => 
        {
            options.AddPolicy("RequireHmac", policy => 
                policy.AddRequirements(new HmacAuthenticateAttribute 
                { 
                    Policy = "HmacPolicy", 
                    Scheme = "HmacScheme"
                }));
        });
      

    • Use the AuthorizationPolicyBuilder extensions RequireHmacPolicy and RequireHmacScheme to add hmac policy and scheme requirements to an authorization policy.

        builder.Services.AddAuthorization(options => 
        {
            options.AddPolicy("RequireHmac", policy =>
            {
                policy.RequireHmacPolicy("HmacPolicy");
                policy.RequireHmacScheme("HmacScheme");
            });
        });
      

    • Use the AuthorizationPolicyBuilder extension RequireHmacAuthentication to add hmac policy and scheme requirements to an authorization policy.

        builder.Services.AddAuthorization(options => 
        {
            options.AddPolicy("RequireHmac", policy =>
            {
                policy.RequireHmacAuthentication("HmacPolicy", "HmacScheme");
            });
        });
      

Register with an IConfigurationSection

Both AddHmacManager and AddHmac have an overload which accepts an IConfigurationSection that corresponds to the json schema below. An example can be found here.

[
    {
        "Name": "Some_Policy",
        "Keys": {
            "PublicKey": "37e3e675-370a-4ba9-af74-68f99b539f03",
            "PrivateKey": "zvg29s2cQ4idOqbUJWETOw=="
        },
        "Algorithms": {
            "ContentHashAlgorithm": "SHA256",
            "SigningHashAlgorithm": "HMACSHA256"
        },
        "Nonce": {
            "CacheType": "Memory",
            "MaxAgeInSeconds": 100
        },
        "Schemes": [
            {
                "Name": "Some_Scheme",
                "Headers": [
                    {
                        "Name": "Some_Header_1",
                        "ClaimType": "Header_1_ClaimType"
                    }
                ]
            }
        ]
    }
]

The following properties are restricted to the following values.

Register HttpClient with HmacHttpMessageHandler

The AddHmacHttpMessageHandler extension method registers an instance of HmacDelegatingHandler to the specified HttpClient with the specified policy and the optional scheme. This handler will automatically sign outgoing requests for that client. If the request cannot be signed, then an HmacSigningException exception is thrown.

builder.Services.AddHttpClient("Hmac", client => ...)
    .AddHmacHttpMessageHandler("MyPolicy", "MyScheme");

In-Depth Tutorial

This is where you can find a comprehensive guide on all of the functionality available to your disposal. This is currently a work in progress.

Event handling with the HmacEvents object

One or more event handlers can be defined within the AuthenticationBuilder extension method AddHmac.

options.Events = new HmacEvents
{
    OnValidateKeysAsync = (context, keys) => {...},
    OnAuthenticationSuccessAsync = (context, hmacResult) => {...},
    OnAuthenticationFailureAsync = (context, hmacResult) => {...}
};

If using the IConfigurationSection overload of AddHmac then there is an optional second parameter for HmacEvents.

builder.Services.AddAuthentication()
    .AddHmac(configurationSection, new HmacEvents
    {
        OnValidateKeysAsync = (context, keys) => {...},
        OnAuthenticationSuccessAsync = (context, hmacResult) => {...},
        OnAuthenticationFailureAsync = (context, hmacResult) => {...}
    });

Events are executed through user defined delegates at different points within the HmacAuthenticationHandler flow.

Dynamic Policies with IHmacPolicyCollection

An implementation of IHmacPolicyCollection can be requested through the DI container and manipulated at runtime.

• A policy can be added by constructing a new HmacPolicy.

    Policies.Add(new HmacPolicy {...});
  

• A policy can be removed by specifying the name of the policy to remove.

    Policies.Remove("Some Policy");
  

Dynamic policies with a scoped IHmacPolicyCollection

Scoped policies can be enabled through both AddHmac and AddHmacManager extension methods. If scoped policies are enabled, all other policy configurations are disregarded. The IServiceProvider is available so that policies can be pulled from a database (or anywhere, really) if the ability to add and remove policies on a per request basis is required.

services.AddHmacManager(options =>
{
    options.EnableScopedPolicies(serviceProvider =>
    {
        var policies = new HmacPolicyCollection();

        // Create one or more policies
        var builder = new HmacPolicyBuilder(...);

        builder.UsePublicKey(...);
        builder.UsePrivateKey(...);

        // Continue policy configurations

        // Add policy to the collection
        policies.Add(builder.Build());

        return policies;
    });
});

Enable consolidated headers

By default, HmacManager adds the following headers in order to verify a signature.

These can be configured to be consolidated into a single header with the name Hmac-Options and the value as a Base64 encoded concatenation of the headers described in the table above.

.AddHmacManager(options =>
{
    options.EnableConsolidatedHeaders();
});

Custom Signing Content for an Hmac

The signing content for an Hmac can be configured per policy. This allows user defined structures to be used as the input to the signature hash function.

policy.UseSigningContentBuilder(context => 
{
    var method = context.Request.Method;
    var suffix = $"{context.DateRequested}:{context.Nonce}";
    return $"{method}:{suffix}";
});