RossWright.MetalGuardian 8.0.0-beta016

Ross Wright's Metal Guardian

by Ross Wright

Copyright 2023 Pross Co. All Rights Reserved.

Description

Metal Guardian is a library to help implement authentication for HTTP connections using JWT and serve as a lightweight and flexible alternative to ASP.NET Identity. Metal Guardian is even more powerful when combined with MetalNexus.

Client Setup

Reference the RossWright.MetalGuardian package in your project and in your program.cs call builder.Services.AddMetalGuardianBlazor()

On Blazor, setup your HttpClient with builder.Services.AddMetalGuardianHttpClient(/* your server's base url goes here */);

Otherwise, if you are using Metal Guardian with a client other than a Blazor project (for example from a server), you must register an implementation of IAuthenticationTokenRepository before the call to AddMetalGuardianHttpClient to store tokens between sessions.

Server Setup

On your ASP.NET server, the Metal Guardian service requires a appsettings to be added to the configuration:

"MetalGuardian": {
   "JwtIssuer": "https://rosswright.com", // fill in your company url
   "JwtAudience": "https://app.rosswright.com", // fill in your application's client url
   "JwtIssuerSigningKey": "sJKLh678hl_jkh5", // fill in your application's signing key - a very long random alphanumeric string
   "RefreshTokenExpireMins": 10080, // The number of minutes it should take a refresh token to expire, 10080 is 1 week
   "JwtAccessTokenExpireMins": 1440, // The number of minutes it should take an access token to expire, 1440 is 1 day
}

The library is initialized in program.cs by calling: builder.AddMetalGuardian<AuthorizationRepository>() where AuthorizationRepository is your implementation of IAuthorizationRepository

public interface IAuthUserRepository
{
    Task<IAuthenticationUser?> GetUser(string userIdentity, CancellationToken cancellationToken, Func<IAuthenticationUser, bool>? updateUser = null);
    Task AddRefreshToken(Guid userId, string refreshToken, CancellationToken cancellationToken);
    Task<IAuthenticationUser?> RefreshToken(Guid userId, string refreshToken, CancellationToken cancellationToken);
    Task ClearToken(Guid userId, string refreshToken, CancellationToken cancellationToken);
}

public interface IAuthenticationUser
{
    Guid UserId { get; }
    string Name { get; }
    IEnumerable<(string, string)>? Claims { get; }
    string PasswordSalt { get; set; }
    string PasswordHash { get; set; }
    public string? OneTimePasswordSalt { get; set; }
    public string? OneTimePasswordHash { get; set; }
    public DateTimeOffset? OneTimePasswordExpiresAt { get; set; }
}

if the updaterUser parameter to GetUser is not null, it must be called with an object implementing IAuthenticationUser for modification and the modification must be persisted if the return from the Func is true. Ensure multiple refresh tokens can be associated with a user to enable users to sign in from different locations/browsers simultaneously

All of this enables you to inject the IMetalGuardianService:

public interface IMetalGuardianService
{
    Task<AuthenticationTokens> Login(string userIdentity, string password, CancellationToken cancellationToken = default);
    Task Logout(AuthenticationTokens tokens, CancellationToken cancellationToken = default);
    Task<AuthenticationTokens> Refresh(AuthenticationTokens tokens, CancellationToken cancellationToken = default);
    Task<string> GetOneTimePassword(string userIdentifier, int? expirationInMinutes = null, CancellationToken cancellationToken = default);
    Task<AuthenticationTokens> LoginWithOneTimePassword(string userIdentifier, string oneTimePassword, CancellationToken cancellationToken = default);
}

You can implment a controller or MetalNexus request handlers that call the Metal Guardian Service to handle all these concerns. You can decorate your controllers and actions with [Authorize] attributes as usual and access information about the logged in user via the Controller.User property or by injecting IHttpContextAccessor as normal.

On the Blazor client side, in program.cs call builder.Services.AddMetalGuardianHttpClient({baseAddress}) where baseAddress is the base url of your server. Now when you inject an HttpClient, it will be setup with security. You can support connections to multiple servers by specifying a connection name builder.Services.AddMetalGuardianHttpClient({baseAddress}, {connectionName}) which you can then consume by injecting the IHttpClientFactory and calling CreateClient on that service passing the same connectionName.

Licensing

A license must be purchased to use RossWright.Metal libaries in a production environment. For development enviroments, using the libraries without a license will show a console message on initialization and cease functioning after one hour. To install your license file include it in the executable project with the Build Action set to Embedded Resource. The file can be renamed as needed, but must end with the extension .license.