Duende.Labs.IdentityModel 2026.922.37

IdentityModel for .NET

Modern OpenID Connect and OAuth 2.0 client library for .NET 10+.

Installation

dotnet add package Duende.Labs.IdentityModel

Note This package is experimental/preview. For production scenarios, consider Duende.IdentityModel.

Typed client

IdentityModel uses named HttpClient instances and named options. Register an authority once:

services.AddIdentityModelClient(options =>
{
    options.Authority = new Uri("https://demo.duendesoftware.com");
    options.DefaultClientCredential = new ClientCredential("m2m", "secret");
    options.Scope = "api";
});

Inject IIdentityModelClientFactory and asynchronously create an initialized client:

public sealed class Worker(IIdentityModelClientFactory factory)
{
    public async Task RunAsync(CancellationToken ct)
    {
        var creation = await factory.CreateAsync(ct);
        if (!creation.IsSuccess)
        {
            // Inspect creation.Error.
            return;
        }

        var client = creation.Client;
        if (!client.SupportsClientCredentials)
        {
            return;
        }

        var token = await client.RequestClientCredentialsTokenAsync(ct);
    }
}

The factory retrieves and validates discovery, resolves protocol endpoints, and returns an immutable client snapshot. Calls do not require callers to copy endpoint URIs out of discovery or construct endpoint-bearing request objects.

Capabilities

The initialized client exposes capabilities such as SupportsClientCredentials, SupportsUserInfo, SupportsDeviceAuthorization, and SupportsPushedAuthorization.

Capability validation is strict by default. Strict mode checks endpoint presence and relevant advertised metadata, including grant types and client authentication methods. An unsupported call fails locally with ProtocolErrorType.UnsupportedFeature.

Providers with incomplete discovery documents can use relaxed mode:

services.AddIdentityModelClient(options =>
{
    options.Authority = new Uri("https://provider.example.com");
    options.CapabilityValidationMode = CapabilityValidationMode.Relaxed;
});

Relaxed mode requires a resolved endpoint but does not block a call because other advertised metadata is missing.

Endpoint overrides and limited clients

Explicit endpoint overrides take precedence over discovery and may be absolute or relative to the authority:

services.AddIdentityModelClient(options =>
{
    options.Authority = new Uri("https://provider.example.com");
    options.TokenEndpoint = new Uri("/oauth/token", UriKind.Relative);
});

If discovery fails but one or more explicit endpoints are usable, creation succeeds with a limited client. DiscoveryError preserves the failure and only explicitly configured capabilities are available. Creation fails when discovery fails and no usable override exists.

Named clients

services.AddIdentityModelClient("customers", options => { /* ... */ });
services.AddIdentityModelClient("partners", options => { /* ... */ });

var customers = await factory.CreateAsync("customers", ct);

Each factory call uses the current named options and creates a fresh discovery snapshot. The factory does not retain typed clients or impose a discovery cache lifetime.

Per-call customization

Overloads accept a transform for operation-specific values:

var result = await client.RequestClientCredentialsTokenAsync(
    request => request with { Scope = "api.read" },
    ct);

The client supplies endpoint and configured defaults before invoking the transform.

HTTP handlers, resilience, and caching

AddIdentityModelClient returns the backing IHttpClientBuilder, so handlers apply to discovery and protocol requests:

services
    .AddIdentityModelClient(options => { /* ... */ })
    .AddHttpMessageHandler<MyHandler>()
    .AddStandardResilienceHandler();

IdentityModel does not cache discovery or protocol responses. Applications choose caching policy, storage, and handler ordering through the normal HttpClient pipeline. The Caching sample demonstrates RFC 9111 response caching.

Configuration binding

services.AddIdentityModelClient(builder.Configuration.GetSection("IdentityProvider"));

Recognized keys include Authority, ClientId, ClientSecret, ClientCredentialStyle, Scope, CapabilityValidationMode, and endpoint overrides. Values are read explicitly to preserve trimming and Native AOT compatibility.

Features

The typed client supports:

• Discovery and JSON Web Keys
• Client credentials, authorization code, and refresh token requests
• Token introspection and revocation
• UserInfo
• Device authorization
• Pushed Authorization Requests and Rich Authorization Requests
• CIBA backchannel authentication
• Dynamic client registration and RFC 7592 registration management

Generic SetBearerToken helpers remain available for setting an OAuth bearer token on an HttpClient or HttpRequestMessage.

License

IdentityModel is open source under the Apache 2.0 license.