ForgeTrust.AppSurface.Auth.AspNetCore.Oidc

ForgeTrust.AppSurface.Auth.AspNetCore.Oidc registers named ASP.NET Core cookie and OpenID Connect schemes with AppSurface-safe defaults.

Use this package when an ASP.NET Core web app already has an identity provider selected and wants a shorter, safer cookie + OIDC setup for AppSurface modules. The package composes ForgeTrust.AppSurface.Auth.AspNetCore so request principals and host-owned policy decisions still flow through the existing AppSurface auth adapter.

Release Guidance

AppSurface ships as a coordinated package family. Before installing this package from a prerelease feed, check the package chooser and release hub for current release risk, migration guidance, and readiness.

Use the AppSurface Auth adoption ladder when deciding whether OIDC convenience registration is the right rung or whether raw ASP.NET Core/provider setup, DevAuth, or Auth.Testing is safer.

Quickstart: Register Named Cookie And OIDC Schemes

Install the package:

dotnet add package ForgeTrust.AppSurface.Auth.AspNetCore.Oidc

Register AppSurface OIDC auth:

using ForgeTrust.AppSurface.Auth.AspNetCore.Oidc;

builder.Services.AddAppSurfaceOidcAuth(options =>
{
    options.ConfigureOpenIdConnect(oidc =>
    {
        oidc.Authority = builder.Configuration["Authentication:Oidc:Authority"];
        oidc.ClientId = builder.Configuration["Authentication:Oidc:ClientId"];
        oidc.ClientSecret = builder.Configuration["Authentication:Oidc:ClientSecret"];
    });
});
builder.Services.AddAuthorization();

Run the host auth middleware in the normal ASP.NET Core order:

app.UseAuthentication();
app.UseAuthorization();

The default schemes are:

The package does not set global default schemes. If the host wants ASP.NET Core defaults, configure them explicitly with the normal AddAuthentication(options => ...) API before or after adding this package.

What The Package Includes

• AddAppSurfaceOidcAuth(...)
• AppSurfaceOidcAuthOptions
• named cookie and OIDC scheme registration
• OIDC authorization code flow default
• OIDC sign-in scheme wired to the AppSurface cookie scheme
• SaveTokens = false by default
• sub subject mapping through ForgeTrust.AppSurface.Auth.AspNetCore
• safe local-only passive login/logout prompt helpers
• stable OIDC diagnostic codes
• host event chaining for OIDC diagnostics

What The Package Does Not Include

• user stores, app-user provisioning, or ASP.NET Identity replacement
• identity-provider hosting or OAuth/OIDC server behavior
• provider SDKs such as Microsoft.Identity.Web, Auth0, Okta, or Keycloak packages
• EF Core, persistence, tenant authority, or permission systems
• middleware insertion
• challenge, redirect, sign-in, or sign-out execution
• silent default scheme takeover
• token storage by default
• Aspire, Keycloak management, or Dev Auth test harness behavior

Defaults And Overrides

Use ConfigureOpenIdConnect(...) for provider settings:

builder.Services.AddAppSurfaceOidcAuth(options =>
{
    options.ConfigureOpenIdConnect(oidc =>
    {
        oidc.Authority = "https://login.example";
        oidc.ClientId = "appsurface-web";
        oidc.ClientSecret = builder.Configuration["Authentication:Oidc:ClientSecret"];
        oidc.Scope.Add("profile");
    });
});

Client secrets are applied to ASP.NET Core OpenIdConnectOptions; AppSurface diagnostics never copy them into metadata.

Login And Logout Prompts

CreateLoginPrompt(...) and CreateLogoutPrompt(...) create passive AppSurface prompt objects only:

var prompt = oidcOptions.CreateLoginPrompt("/dashboard", "Sign in");

Prompt targets must be local app-relative paths such as /dashboard. External, protocol-relative, backslash-containing, or control-character paths are rejected. The helpers do not call ChallengeAsync, SignInAsync, SignOutAsync, or Redirect.

Diagnostics

Setup diagnostics use stable codes and safe metadata:

Diagnostics must not include raw tokens, raw claims, email addresses, display names, client secrets, ID-token payloads, or provider response bodies.

Middleware ordering symptoms are documented, not perfectly runtime-detected. If authentication never appears to run, verify UseAuthentication() is before UseAuthorization() and before endpoints that need HttpContext.User.

Provider Guidance

Use this package when you want recognizable ASP.NET Core cookie + OIDC handlers with AppSurface naming, subject mapping, return-url guardrails, and safe diagnostics.

Use raw ASP.NET Core OIDC when the host already has a detailed provider setup and only needs complete handler control.

Use Microsoft.Identity.Web, Auth0, Okta, Keycloak, or another provider SDK when the app needs provider-specific token acquisition, management APIs, tenant helpers, or SDK-specific conventions.

Durable external-subject-to-app-user mapping belongs to the AppSurface app-user mapping contract path, not this package.

Local Proof

For a no-secret demonstration of the registration surface, see the ASP.NET Core OIDC example.

Pitfalls

• Register real provider values before resolving the named OIDC options.
• Configure callback and signout callback URLs in the identity provider when using the defaults.
• Do not enable SaveTokens unless the host accepts larger cookies and stored token material.
• Do not treat the external OIDC subject as an AppSurface app-user record.
• Do not expect this package to insert middleware or execute login/logout redirects.