Energinet.DataHub.MarketParticipant.Authorizations.Client 1.0.517

Authorizations Client

.NET client package for the Authorizations API (v1).

Installation

dotnet add package Energinet.DataHub.MarketParticipant.Authorizations.Client

Registration

Register the client in your dependency injection container using one of the two available overloads.

Using the ambient IConfiguration (recommended)

Reads options from the IConfiguration already registered in the DI container:

services.AddAuthorizationClient();

Using an explicit IConfiguration instance

Useful when you want to pass a specific configuration object:

services.AddAuthorizationClient(configuration);

Both overloads register AuthorizationsClient as a typed HttpClient and validate the options at startup.

Configuration

Options are bound from the AuthorizationClient section of your configuration (e.g. appsettings.json):

{
  "AuthorizationClient": {
    "BaseUrl": "https://authorizations.example.com"
  }
}

Options

HTTP timeout behavior is configured through the AuthorizationsHttpClientResilience section.

Resilience options

The client uses AddStandardResilienceHandler() and binds HttpStandardResilienceOptions from the AuthorizationsHttpClientResilience section.

The effective resilience settings are built by merging:

1. Internal defaults from the client package.
2. Values from your AuthorizationsHttpClientResilience configuration section.

This means you can provide only the values you want to override.

Default resilience values

Example override

{
  "AuthorizationsHttpClientResilience": {
    "Retry": {
      "MaxRetryAttempts": 7,
      "Delay": "00:00:05"
    }
  }
}

In this example, BackoffType and UseJitter still come from the defaults.

Usage

This client supports two primary usage patterns:

1. Getting Authorization Tokens (Origin System)

Retrieve an AuthorizationContext that can be passed to downstream systems:

public class AuthorizationTokenService(AuthorizationsClient client)
{
    public async Task<AuthorizationContext> GetTokenForSubjectAsync(Guid subjectId, CancellationToken ct = default)
    {
        return await client.AuthorizationContextForSubjectAsync(subjectId, ct);
    }

    public async Task<AuthorizationContext> GetTokenForActorAsync(string gln, MarketRoles role, CancellationToken ct = default)
    {
        return await client.AuthorizationContextForActorAsync(gln, role, ct);
    }
}

The returned AuthorizationContext contains the token (signature) and claims, which should be transmitted to downstream systems.

2. Validating Tokens & Extracting Policies (Downstream System)

Use PolicyFactory to validate an incoming AuthorizationContext and resolve policies:

public class AuthorizationService(PolicyFactory policyFactory)
{
    public async Task<MeteringPointAccessPolicy> ValidateAndGetPolicyAsync(
        AuthorizationContext context, 
        CancellationToken ct = default)
    {
        return await policyFactory.GetPolicy<MeteringPointAccessPolicy>(context, ct);
    }
}

The PolicyFactory will:

• Retrieve the public key from the provider
• Validate the authorization context signature
• Extract and return the strongly-typed policy

If validation fails, an InvalidOperationException is thrown.

Testing Environment

For testing scenarios where signature verification should be bypassed, register the test double after the main client registration:

public void ConfigureServices(IServiceCollection services)
{
    services
        .AddAuthorizationClient(configuration)
        .AddBypassSignatureVerificationForTesting();
}

This substitutes the standard key provider with one that accepts all signatures, allowing you to focus on business logic validation without dealing with cryptographic concerns.

⚠️ Never use in production — this is test-only functionality.

A context can be created with AuthorizationContextBuilder for testing purposes:

    var context = var policy = AuthorizationContextBuilder.Create()
            .WithMeteringPointAccess("mp-1", MeteringPointSubjectRelation.Occupancy, TestTime.AddDays(-1), TestTime.AddDays(1))
            .WithMeteringPointAccess("mp-2", MeteringPointSubjectRelation.Occupancy, TestTime.AddDays(-1), TestTime.AddDays(1))
            .BuildContext();

If needed, you can then pass this context to the PolicyFactory to get a policy instance for testing:

    var policy = await BypassSignaturePolicyFactory.Instance
        .GetPolicy<MeteringPointAccessPolicy>(context, CancellationToken.None);

For maintainers

How this package is published

The client code in this project is automatically generated from the file-based OpenAPI contract at ../Energinet.DataHub.MarketParticipant.Authorizations.Api/OpenApi/Energinet.DataHub.MarketParticipant.Authorizations.Api.json (via NSwag). You never edit AuthorizationsClient.g.cs by hand.

The contract file is produced by building Energinet.DataHub.MarketParticipant.Authorizations.Api (code-first controllers + OpenAPI generation).

When you build the client and the contract file is missing, an MSBuild bootstrap target in the client automatically builds the API first to generate the contract file.

Typical local flow:

1. Build the API project to refresh the OpenAPI contract file.
2. Build the client project to regenerate AuthorizationsClient.g.cs from that contract.

Publishing is handled by the CI workflow .github/workflows/publish-authorizations-client-bundle.yml. It triggers automatically when any file under Authorizations.Api/ or Authorizations.Client/ is merged to main, and:

1. Builds the full Authorizations solution (which regenerates the OpenAPI contract and then regenerates the client from that file contract).
2. Runs unit tests.
3. Packs and pushes the NuGet package.

You do not need to do anything manually to publish a new version.

Versioning

Versioning is handled automatically by Nerdbank.GitVersioning. The published version is derived from the base version in version.json combined with the git commit height (number of commits on main since the repo root):

When to edit version.json

version.json only needs to be edited for intentional breaking or significant changes that warrant a major or minor version bump. The patch number is always automatic.

To bump, open version.json and change the version field:

{
  "$schema": "https://raw.githubusercontent.com/dotnet/Nerdbank.GitVersioning/master/src/NerdBank.GitVersioning/version.schema.json",
  "version": "2.0",
  "publicReleaseRefSpec": [
    "^refs/heads/main$"
  ]
}

Note: A PR that changes version.json will automatically trigger the version guard workflow (.github/workflows/ci-authorizations-client-version-guard.yml), which queries NuGet.org and fails the PR if the major.minor combination is already in use.