Authlink.Policy.Client.Http 1.3.0

Package Overview

Authlink.Policy.Client.Http provides a concrete HTTP implementation of the IPolicyClient abstraction from Authlink.Policy.Client.Core, enabling seamless integration with Authlink's Policy Decision Point (PDP) over REST. It leverages System.Net.Http and HttpClientFactory to deliver a resilient, configurable client for decision requests.

It is intended to be consumed alongside:

• Authlink.Policy.Client.Core

Optionally paired with:

• Authlink.Policy.ServiceStack (for ServiceStack integration)
• Authlink.Policy.AspNetCore (for ASP.NET Core integration)

Install

dotnet add package Authlink.Policy.Client.Http

Or via Package Manager:

PM> Install-Package Authlink.Policy.Client.Http

Purpose

This package delivers:

• A PolicyHttpClient that implements IPolicyClient over HTTP
• Transparent JSON (de)serialization of PolicyDecisionRequest / PolicyDecisionResponse
• Obligations on allow decisions (row filters, property masks, audit/reason flags), with the obligation expression grammar version surfaced via ObligationsGrammarVersion (since 1.3.0)
• Configurable endpoint, timeout, and default client/audience IDs via PolicyHttpClientOptions
• Bearer token authentication with flexible token provider support
• Fail-closed behavior on HTTP errors (non-200 ⇒ Deny)
• Easy registration with IServiceCollection

Usage

1. Register in Startup or Program

Basic registration (no authentication)

builder.Services.AddPolicyHttpClient(options =>
{
    options.BaseUrl = "https://policy.authlink.co.za";
    options.ClientId = new Guid("11111111-2222-3333-4444-555555555555");
    options.AudienceId = new Guid("66666666-7777-8888-9999-000000000000");
});

With static access token

builder.Services.AddPolicyHttpClient(options =>
{
    options.BaseUrl = "https://policy.authlink.co.za";
    options.ClientId = new Guid("11111111-2222-3333-4444-555555555555");
    options.AccessToken = "your-bearer-token";
});

With custom token provider

For dynamic token scenarios (e.g., token refresh), register a custom IAccessTokenProvider before calling AddPolicyHttpClient:

// Register custom token provider first
builder.Services.AddSingleton<IAccessTokenProvider, MyCustomTokenProvider>();

// Then register the policy client
builder.Services.AddPolicyHttpClient(options =>
{
    options.BaseUrl = "https://policy.authlink.co.za";
    options.ClientId = new Guid("11111111-2222-3333-4444-555555555555");
});

Updating tokens at runtime

The default MutableAccessTokenProvider allows updating tokens at runtime:

public class TokenRefreshService
{
    private readonly MutableAccessTokenProvider _tokenProvider;

    public TokenRefreshService(IAccessTokenProvider tokenProvider)
    {
        _tokenProvider = (MutableAccessTokenProvider)tokenProvider;
    }

    public void UpdateToken(string newToken)
    {
        _tokenProvider.SetAccessToken(newToken);
    }
}

2. Inject and call

public class InvoiceService
{
    private readonly IPolicyClient _policy;

    public InvoiceService(IPolicyClient policyClient)
    {
        _policy = policyClient;
    }

    public async Task<bool> CanCreateInvoiceAsync(Guid userId)
    {
        var request = new PolicyDecisionRequest
        {
            SubjectId = userId,
            PermissionKey = "create-invoice",
            ResourceKey = "invoice"
        };

        var result = await _policy.DecideAsync(request);

        if (result.IsError)
            return false; // Fail-closed on errors

        // Fail-closed on obligations too: an allow decision may carry obligations (row filters,
        // property masks, audit/reason flags) the caller MUST enforce before completing the
        // operation. A consumer that does not implement obligation enforcement must treat a
        // decision that carries them as a deny.
        if (result.Value.Obligations.Count > 0)
            return false;

        return result.Value.Decision == Decision.Allow;
    }
}

Enforcing obligations

Consumers that do enforce obligations should first check the grammar contract, then compile each obligation. ObligationsGrammarVersion is present whenever a decision carries obligations; deny if it (or any obligation's version attribute) names a version you do not support:

var response = result.Value;

if (response.Decision != Decision.Allow)
    return Deny();

if (response.Obligations.Count > 0 && response.ObligationsGrammarVersion != "1")
    return Deny(); // Unsupported obligation contract — fail closed

foreach (var obligation in response.Obligations)
{
    switch (obligation.Kind)
    {
        case ObligationType.RowFilter:
            // Compile attributes["expression"] (obligation expression grammar v1) into your query.
            break;
        case ObligationType.MaskProperties:
            // Mask every property matched by attributes["properties"].
            break;
        case ObligationType.RequireAudit:
            // Record an audit entry for the operation.
            break;
        case ObligationType.RequireReason:
            // Capture a caller-supplied reason before completing the operation.
            break;
        default:
            return Deny(); // Unknown obligation kind — fail closed
    }
}

The normative grammar reference (ABNF, semantics, limits) lives in the Authlink repository at docs/specifications/obligation-expression-grammar-v1.md.

Configuration Options

Authentication

The package supports three authentication modes:

1. Custom IAccessTokenProvider: Register your own implementation before calling AddPolicyHttpClient. This takes precedence over other options.

2. Static token via options: Set PolicyHttpClientOptions.AccessToken in the configure delegate. A MutableAccessTokenProvider will be registered automatically.

3. No authentication: If neither is provided, requests are made without authentication headers.

Documentation

For more information, visit: https://docs.authlink.co.za

License

MIT