Pacem.IdentityModel 0.10.11

Pacem.IdentityModel

Shared OAuth 2.0 / OpenID Connect protocol vocabulary for Pacem.Id — the wire-format types (constants, request/response DTOs, protocol exceptions, the IdToken/JwtToken/UserInfoResponse claims models) plus a small set of typed HTTP clients, so that both the identity provider itself and any relying party written in C# share one vocabulary instead of each hand-rolling it.

What's in here

• Protocol constants — KnownGrantTypes, KnownResponseTypes, KnownOidcScopes, KnownClientAuthenticationMethods, and the parameter-name constants for each request kind (KnownTokenRequestParameters, KnownAuthenticationRequestParameters, etc.).
• Request/response DTOs — AuthenticationRequest, TokenRequest/TokenResponse, IntrospectionRequest/IntrospectionResponse, RevocationRequest, DiscoveryDocument, PublicJwk/PublicJwkSet, Claim.
• Protocol exceptions — OAuthException and its four subtypes (AuthenticationRequestException, TokenRequestException, IntrospectionRequestException, RevocationRequestException), each mapping to a standard OAuth error code.
• Claims models — JwtToken/IJwtToken, a lightweight typed wrapper over a JWT claims dictionary; the abstract IdToken (readonly claim accessors per the ID Token spec — built by IdTokenBuilder server-side, in Pacem.Id); and UserInfoResponse, the same shape for the UserInfo response.

Typed clients

AddPacemIdentityModelClient() registers IClientFactory — every client, IDiscoveryClient included, is obtained from it:

services.AddPacemIdentityModelClient();

Every client is built around ClientOptions.DiscoveryDocumentUrl — the full url of an OpenID Connect discovery document — so the same IClientFactory works against any spec-compliant OIDC provider, not just Pacem.Id. ClientOptions offers three ways to get one, from most to least Pacem.Id-specific:

• ClientOptions.FromAuthorityAndTenant(authority, tenantId) — Pacem.Id is multi-tenant, and a single consuming service may well need to talk to several tenants (or several authorities) over its lifetime, each with its own credentials; this derives the url from that pair.
• ClientOptions.FromIssuerUrl(issuerUrl) — derives the url from a bare issuer per the OIDC Discovery convention ({issuerUrl}/.well-known/openid-configuration), for any other spec-compliant provider.
• new ClientOptions(discoveryDocumentUrl) — takes the exact url verbatim, for a provider whose discovery document isn't at the derivable location, or when you already have it (e.g. from configuration).

IClientFactory factory = provider.GetRequiredService<IClientFactory>();

// Pacem.Id: authority + tenant
ClientOptions discovery = ClientOptions.FromAuthorityAndTenant("https://id.pacem.it", "acme");
// any other OIDC provider, from its bare issuer:
// ClientOptions discovery = ClientOptions.FromIssuerUrl("https://accounts.example.com");
// or the exact discovery url, verbatim:
// ClientOptions discovery = new("https://accounts.example.com/.well-known/openid-configuration");

ITokenClient tokenClient = factory.CreateTokenClient(new ClientAuthenticationOptions(discovery)
{
    ClientId = "my-client",
    ClientSecret = "...",
});

TokenResponse tokens = await tokenClient.RequestTokenAsync(new TokenRequest
{
    GrantType = KnownGrantTypes.AuthorizationCode,
    Code = code,
    RedirectUri = redirectUri,
});

Each factory method takes the narrowest options type that client actually needs, rather than one type carrying every client's properties:

• CreateDiscoveryClient — plain ClientOptions (discovery url only). Every other method already resolves the endpoint it needs through one of these internally; call this directly only when you want the discovery document itself, or to force a refetch via IDiscoveryClient.Refresh().
• CreateUserInfoClient — plain ClientOptions (discovery url only; UserInfo authenticates with the bearer access token itself, no separate credential).
• CreateTokenClient / CreateRevocationClient — ClientAuthenticationOptions (adds ClientId/ ClientSecret/ClientAuthenticationMethod; both authenticate as an OAuth client).
• CreateIntrospectionClient — IntrospectionClientOptions (adds ApiName/ApiSecret; introspection authenticates as an API resource, not as a client).

None of the endpoint URLs are hardcoded beyond that: every client resolves the endpoint it calls from its provider's discovery document, whose own well-known location is the only route that's ever assumed — the one spec-fixed constant. IDiscoveryClient itself is deliberately simple — fetch this one url once, cache forever, no TTL of its own — because IClientFactory is what actually owns the cache: one IDiscoveryClient per distinct discovery url, shared by every client created for that url (CreateTokenClient, CreateUserInfoClient, ... all resolve through the same cached instance), kept until discoveryCacheDuration elapses (default 24h, set once via AddPacemIdentityModelClient(discoveryCacheDuration: ...)) and then regenerated on next use. Calling IDiscoveryClient.Refresh() forces that one instance to re-fetch on its next call and tells the factory to drop it early, so a caller who forces a refresh doesn't leave a stale entry behind for everyone else sharing that url.

Notes

• Targets net10.0 only; the request DTOs carry Microsoft.AspNetCore.Mvc-style binding attributes ([FromQuery]/[FromForm]) since Pacem.Id binds incoming requests to these same types server-side — they're inert metadata for outbound client use.
• This library is C#-only by design: it's meant to be referenced directly by .NET relying parties and by Pacem.Id itself, not to describe a wire format for other languages.

References

• OAuth 2.0
• OpenID Connect Core
• OpenID Connect Discovery
• Token Introspection
• Token Revocation
• PKCE