Authlink.Identity.Client.Http 2.2.0

📦 Package Overview

Authlink.Identity.Client.Http provides a ready-to-use, production-grade implementation of the IIdentityClient abstraction defined in Authlink.Identity.Client.Core.

It handles:

• Token acquisition via client credentials and authorization code flows
• Refresh token lifecycle management
• Typed result models for easy integration
• Comprehensive error handling with detailed error information

🚀 Install

dotnet add package Authlink.Identity.Client.Http

Or via Package Manager:

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

🆕 What's New

v2.2.0

New Features - Registration Session Webhook Support:

• Added Rejected and PendingApproval values to RegistrationSessionStep enum
• These new steps support webhook-based registration approval workflows
• Completed enum value changed from 7 to 9

v2.1.0

New Features - User Registration Flow:

• ✅ ValidateInvitationCodeAsync - Validate invitation codes and create registration sessions
• ✅ GetRegistrationSessionAsync - Get current state of a registration session
• ✅ SubmitGovernmentIdentifierAsync - Submit government identifier for verification
• ✅ InitiateEmailVerificationAsync - Start email verification with OTP
• ✅ CompleteEmailVerificationAsync - Complete email verification with OTP
• ✅ InitiatePhoneNumberVerificationAsync - Start phone number verification with OTP
• ✅ CompletePhoneNumberVerificationAsync - Complete phone number verification with OTP
• ✅ SubmitProfileInformationAsync - Submit profile information (first name, last name)
• ✅ CompleteRegistrationAsync - Complete registration and create user account

v2.0.0

⚠️ BREAKING CHANGE: All methods now return ErrorOr<T> for rich error handling. See migration guide below.

🛠️ Usage Example

Setup

builder.Services.AddIdentityHttpClient(options =>
{
    options.Authority = "https://identity.authlink.co.za";
});

Basic Usage with Error Handling

public class MyService
{
    private readonly IIdentityClient _client;

    public MyService(IIdentityClient client)
    {
        _client = client;
    }

    public async Task<string?> AuthenticateAsync()
    {
        var result = await _client.TokenAsync(new TokenRequest
        {
            GrantType = "client_credentials",
            ClientId = "9c62ad86-cacf-4e8e-9915-8968327434c6",
            ClientSecret = "super-secret",
            Scope = "openid profile"
        });

        // Check for errors
        if (result.IsError)
        {
            var error = result.FirstError;
            Console.WriteLine($"Authentication failed: {error.Code} - {error.Description}");
            return null;
        }

        // Access the successful response
        var response = result.Value;
        Console.WriteLine("Access token: " + response.AccessToken);
        return response.AccessToken;
    }
}

Advanced Error Handling

public async Task<TokenResponse?> GetTokenWithRetryAsync()
{
    var result = await _client.TokenAsync(request);

    return result.Match(
        value => value,  // Success case
        errors =>
        {
            // Handle specific error types
            var error = errors.First();

            switch (error.Code)
            {
                case "IdentityClient.HttpRequestFailed":
                    _logger.LogError("HTTP request failed: {Description}", error.Description);
                    break;

                case "IdentityClient.ProtocolError":
                    _logger.LogError("OAuth/OIDC error: {Description}", error.Description);
                    break;

                case "IdentityClient.NetworkError":
                    _logger.LogWarning("Network error, retrying...");
                    // Implement retry logic
                    break;

                case "IdentityClient.OperationTimeout":
                    _logger.LogError("Request timed out");
                    break;

                default:
                    _logger.LogError("Unexpected error: {Code} - {Description}",
                        error.Code, error.Description);
                    break;
            }

            return null;
        });
}

All Available Methods

// Token endpoint
ErrorOr<TokenResponse> result = await client.TokenAsync(tokenRequest);

// JWKS endpoint
ErrorOr<JsonWebKeySetResponse> jwks = await client.JwksAsync();

// OpenID Configuration
ErrorOr<OpenIdConfigurationResponse> config = await client.ConfigurationAsync();

// UserInfo endpoint
ErrorOr<UserInfoResponse> userInfo = await client.UserInfoAsync(accessToken);

🔄 Migration from v1.x

Before (v1.x)

try
{
    var response = await _client.TokenAsync(request);
    UseToken(response.AccessToken);
}
catch (HttpRequestException ex)
{
    // Limited error context
    _logger.LogError(ex, "Failed to get token");
}

After (v2.0)

var result = await _client.TokenAsync(request);

if (result.IsError)
{
    // Rich error information with codes and detailed descriptions
    var error = result.FirstError;
    _logger.LogError("Failed to get token: {Code} - {Description}",
        error.Code, error.Description);
    return;
}

UseToken(result.Value.AccessToken);

🎯 Error Handling Benefits

• No more exceptions - Errors are values, making control flow explicit
• Detailed context - Every error includes the endpoint, status code, and detailed description
• OAuth/OIDC errors - Automatic parsing of protocol errors with error codes and descriptions
• Network errors - Clear distinction between timeouts, cancellations, and connection failures
• Type safety - Compiler ensures you handle errors before accessing values

📚 Documentation

https://docs.authlink.co.za

📄 License

MIT