Reference

AddTraxOidcAuth

Package Trax.Api.Auth.OidcNamespace Trax.Api.Auth.OidcSource OidcAuthServiceCollectionExtensions.cs, OidcBuilder.cs, DefaultOidcPrincipalResolver.cs, OidcTokenInput.cs

NO WARRANTY. Trax auth is plumbing, not a security product. You are solely responsible for securing systems that use it. See API Security.

Extension methods on IServiceCollection, declared on OidcAuthServiceCollectionExtensions, that register the Trax OpenID Connect authorization-code scheme (OidcDefaults.SchemeName) and its session cookie (OidcDefaults.CookieSchemeName). A challenge against the OIDC scheme redirects the browser to the identity provider; on the callback the handler validates the id-token, an ITraxPrincipalResolver<OidcTokenInput> maps it to a TraxPrincipal, and the user is signed into the cookie scheme. For API clients that send tokens, the scheme is AddTraxJwtAuth.

Signatures

public static AuthenticationBuilder AddTraxOidcAuth(
    this IServiceCollection services,
    string authority,
    string clientId);
 
public static AuthenticationBuilder AddTraxOidcAuth<TResolver>(
    this IServiceCollection services,
    string authority,
    string clientId)
    where TResolver : class, ITraxPrincipalResolver<OidcTokenInput>;
 
public static AuthenticationBuilder AddTraxOidcAuth(
    this IServiceCollection services,
    Action<OidcBuilder> configure);
 
public static AuthenticationBuilder AddTraxOidcAuth<TResolver>(
    this IServiceCollection services,
    Action<OidcBuilder> configure)
    where TResolver : class, ITraxPrincipalResolver<OidcTokenInput>;
public sealed class OidcBuilder
{
    public OidcBuilder UseAuthority(string authority, string clientId);
    public OidcBuilder WithClientSecret(string clientSecret);
    public OidcBuilder AddScope(string scope);
    public OidcBuilder WithCallbackPath(string callbackPath);
    public OidcBuilder WithSignedOutCallbackPath(string path);
    public OidcBuilder AllowHttpMetadata();
    public OidcBuilder DoNotSaveTokens();
    public OidcBuilder CustomizeOidcOptions(Action<OpenIdConnectOptions> configure);
    public OidcBuilder CustomizeCookieOptions(Action<CookieAuthenticationOptions> configure);
}
 
public sealed record OidcTokenInput(ClaimsPrincipal Principal, string? IdToken, string? AccessToken);
 
public sealed class DefaultOidcPrincipalResolver : ITraxPrincipalResolver<OidcTokenInput>
{
    public ValueTask<TraxPrincipal?> ResolveAsync(OidcTokenInput input, CancellationToken ct);
}

Parameters

ParameterTypeDescription
authoritystringThe OIDC issuer URL. AddTraxOidcAuth(authority, clientId) is AddTraxOidcAuth(oidc => oidc.UseAuthority(authority, clientId)).
clientIdstringThe client id registered with the provider.
configureAction<OidcBuilder>Configures the scheme. UseAuthority is required.
TResolvertype argumentThe resolver, registered scoped. Without it the scheme registers a singleton DefaultOidcPrincipalResolver.

Members

OidcBuilder, passed to configure:

MemberDescription
UseAuthority(authority, clientId)The issuer URL and client id.
WithClientSecret(secret)The secret of a confidential client. Without it the client is public.
AddScope(scope)Requests another scope. openid and profile are requested by default; a scope already present is not added twice.
WithCallbackPath(path)Replaces /signin-oidc.
WithSignedOutCallbackPath(path)Replaces /signout-callback-oidc.
AllowHttpMetadata()Permits non-HTTPS authority metadata.
DoNotSaveTokens()Stops the handler saving the id and access tokens in the session.
CustomizeOidcOptions(configure)Edits OpenIdConnectOptions after Trax has set them and wired OnTokenValidated to the resolver. A second call replaces the first. Replacing Events wholesale removes the resolver hook.
CustomizeCookieOptions(configure)Edits the session cookie's CookieAuthenticationOptions after Trax has set them. A second call replaces the first.

OidcTokenInput, passed to the resolver: Principal (the validated id-token's claims), and IdToken and AccessToken as the raw strings the provider sent, or null.

Returns

The AuthenticationBuilder from services.AddAuthentication().

Behavior

The scheme uses the authorization-code flow (response_type=code) with PKCE, saves the tokens in the session unless DoNotSaveTokens() is called, requires HTTPS metadata unless AllowHttpMetadata() is called, and validates the id-token's issuer, audience, lifetime and signature. AddTraxOidcAuth throws InvalidOperationException when UseAuthority was not called or the callback path is not a valid absolute path.

RequestResult
No session cookieAuthenticateResult.NoResult(). On a protected endpoint the cookie scheme answers 401, not a redirect.
Callback id-token invalid (signature, nonce, audience, lifetime)The handler fails the callback; the user is not signed in.
Callback valid, resolver returns nullFail("OIDC id-token did not map to a known Trax principal.")
Callback valid, resolver throwsFails with the exception.
Callback valid, resolver returns a principalThe user is signed into the cookie scheme; later requests authenticate against the cookie.

The cookie is trax.oidc: HTTP-only, SameSite=Lax, always Secure, with an 8-hour sliding expiration. A redirect to a login page is answered with 401 and a redirect to an access-denied page with 403, because the host is an API. CustomizeCookieOptions replaces those events for a host with its own login page.

DefaultOidcPrincipalResolver

Returns null, failing the sign-in, when the id-token has no subject.

ClaimLands on
sub, then ClaimTypes.NameIdentifierTraxPrincipal.Id
The first non-empty of name, ClaimTypes.Name, preferred_username, email, ClaimTypes.Email, then the idTraxPrincipal.DisplayName
role, roles, groups, ClaimTypes.RoleTraxPrincipal.Roles, without blanks or duplicates
Every other claimTraxPrincipal.Claims, the first value of each type
TraxPrincipal.PrincipalType is oidc.

Policies

OidcDefaults.PolicyName authenticates against the cookie scheme and is satisfied only by a caller the OIDC session signed in. The cookie scheme joins TraxAuthClaimTypes.TraxAuthPolicy. On the Trax GraphQL endpoint, the builder's RequireAuthorization(...) is the gate the startup checks for the operations namespace and [TraxAllowAnonymous] see; a convention on the route is an extra layer those checks do not count. See Authorization.

Subscriptions

The session cookie authenticates the WebSocket upgrade like any other request. The schema accepts an upgrade only from origins the host serves: the endpoint's own host, or the origins AllowSocketOrigins(...) allows, which default to the origins the CORS default policy names. A policy built with AllowAnyOrigin() names none. The socket closes when the sign-in it opened with expires, or at the connection's maximum lifetime. See Subscriptions.

Registered services

ServiceLifetime
Authentication services, the TraxOidc OpenID Connect scheme and the TraxOidc.Cookie cookie scheme
ITraxPrincipalResolver<OidcTokenInput>: DefaultOidcPrincipalResolver or TResolverSingleton or scoped
OidcPolicy, and the cookie scheme in TraxAuthPolicy
TraxPrincipal and TraxCaller, through AddTraxPrincipalAccessor()Scoped
The NO WARRANTY startup log, registered onceHosted service

Examples

A public client:

services.AddTraxOidcAuth("https://login.example.com", "my-client-id");

A confidential client with another scope, gated GraphQL, and a sign-in route:

services.AddTraxOidcAuth(oidc => oidc
    .UseAuthority("https://login.example.com", "my-client-id")
    .WithClientSecret(builder.Configuration["Oidc:ClientSecret"]!)
    .AddScope("email"));
 
services.AddTraxGraphQL(graphql => graphql.RequireAuthorization(OidcDefaults.PolicyName));
 
app.MapGet("/login", () =>
    Results.Challenge(new AuthenticationProperties { RedirectUri = "/" }, [OidcDefaults.SchemeName]));

A resolver for Entra's oid and groups claims:

services.AddTraxOidcAuth<EntraOidcResolver>(oidc =>
    oidc.UseAuthority("https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0", "my-client-id"));
 
public sealed class EntraOidcResolver : ITraxPrincipalResolver<OidcTokenInput>
{
    public ValueTask<TraxPrincipal?> ResolveAsync(OidcTokenInput input, CancellationToken ct)
    {
        var oid = input.Principal.FindFirst("oid")?.Value;
        if (oid is null)
            return ValueTask.FromResult<TraxPrincipal?>(null);
 
        var groups = input.Principal.FindAll("groups").Select(c => c.Value).ToArray();
        var name = input.Principal.FindFirst("name")?.Value ?? oid;
        return ValueTask.FromResult<TraxPrincipal?>(
            new TraxPrincipal(oid, name, groups, PrincipalType: OidcDefaults.PrincipalType));
    }
}

See also