PanoramicData.HealthChecks.BasicAuthentication 1.1.15

PanoramicData.HealthChecks

Heath checks that support checking the versions of items in the deployed application.

Usage

All of the code to enable use of health checks goes in Program.cs (or Startup.cs on older systems).

Add the Nuget package

Add the PanoramicData.HealthChecks.Versions nuget package to the host application.

Enable the required healthchecks

Add the required health checks using the extension methods to the WebApplicationBuilder class:

builder.Services.AddVersionHealthCheck();
builder.Services.AddAssembliesHealthCheck();

Add only those healthchecks in whose results you are interested. Adding more than you need exposes potentially sensitive information unnecessarily, as well as bloating the JSON response sent for every request.

Enable authentication and authorization

Define an authorization scheme using a policy name to which we can refer later. Any form of authentication can be used as you prefer; we use Basic Authentication for this demo so that the demo is standalone.

const string HEALTHCHECKS_AUTHPOLICY = "HeathChecksPolicy";
builder.Services
    .AddHealthChecksBasicAuthentication(builder.Configuration, HEALTHCHECKS_AUTHPOLICY);

The AddHealthChecksBasicAuthentication extension method is part of the optional package PanoramicData.HealthChecks.BasicAuthentication. If you want to make use of this authentication method then you must additionally add this Nuget package to your solution, and supply security credentials in the secrets for the application. The structure of the secrets can be seen in userSecrets.example.json in the Demo project.

Warning Basic Authentication is not a recommended authentication method, as the secret is sent in plain text - it is only encoded on the wire to enable the use of a wide character set. The need to send the password requires that the password be available to the consuming code, which is the weakness in this approach.

If you choose to make use of Basic Authentication then you MUST require SSL, so that the password cannot be detected and decoded as it traverses the network between the consumer and the server.

Next, we must ensure that authentication and authorization are enabled, so add them to the pipeline if they are not already part of it:

app.UseAuthentication();
app.UseAuthorization();

Define the healthchecks endpoint

Finally, define the healthcheck endpoint, specifying its URL and the authorization policy to be applied:

app.MapHealthChecks("_secureHealth", new() 
    { 
        ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse 
    })
    .RequireAuthorization(HEALTHCHECKS_AUTHPOLICY);

You can specify any authorization policy as part of the call to RequireAuthorization - there is no limitation to the type of the policy or the authentication scheme with which that policy is asssociated.

Note that we must specify a custom response writer in the MapHealthChecks method to enable output of custom data from the health checks. If no custom writer is defined then only the enum denoting the overall status of each healthcheck will be returned to the caller. It is this custom response writer that adds the custom data exposed by the health check to the caller.

Warning Enabling writing of custom data to the response risks exposing sensitive data captured by other health checks that are not in your control. Be sure to check the contents of responses each time you add a new healthcheck, to minimise the risk that sensitive information is exposed to callers to whom it is not appropriate.