string CookieScheme { get; set; }
Source
Gets or sets the cookie authentication scheme name.
Oidc
AppSurfaceOidcAuthOptions
SourceConfigures AppSurface conventions for ASP.NET Core cookie and OpenID Connect authentication registration.
Remarks
These options name schemes, configure safe AppSurface defaults, and provide callbacks for host-owned ASP.NET Core handler options. They do not insert middleware, execute challenges, execute redirects, store users, provision app users, replace ASP.NET Identity, or configure provider-specific SDKs.
ConfigureCookie
AppSurfaceOidcAuthOptions ConfigureCookie(Action<CookieAuthenticationOptions> configure)
Source
Adds host-owned cookie handler configuration.
Parameters
configureCallback that receives the ASP.NET Core cookie handler options.
Returns
The current options instance for chaining.
ConfigureOpenIdConnect
AppSurfaceOidcAuthOptions ConfigureOpenIdConnect(Action<OpenIdConnectOptions> configure)
Source
Adds host-owned OpenID Connect handler configuration.
Parameters
configureCallback that receives the ASP.NET Core OpenID Connect handler options.
Returns
The current options instance for chaining.
Remarks
Provider values such as authority, client id, and client secret should be applied here. AppSurface diagnostics never copy those values into metadata.
CreateLoginPrompt
AppSurfaceLoginPrompt CreateLoginPrompt(string? targetPath = null, string? displayText = null)
Source
Creates a passive login prompt for host-owned login UI.
Parameters
targetPathOptional safe app-relative target path.displayTextOptional display text for the host UI.
Returns
A passive login prompt that does not execute a redirect or challenge.
CreateLogoutPrompt
AppSurfaceLogoutPrompt CreateLogoutPrompt(string? targetPath = null, string? displayText = null)
Source
Creates a passive logout prompt for host-owned logout UI.
Parameters
targetPathOptional safe app-relative target path.displayTextOptional display text for the host UI.
Returns
A passive logout prompt that does not execute a redirect or sign-out.
ApplyCookie
void ApplyCookie(CookieAuthenticationOptions options)
Source
Applies registered cookie configurators to the AppSurface cookie handler options.
Parameters
optionsThe ASP.NET Core cookie handler options registered forCookieScheme.
Remarks
Configurators run in the order they were added through ConfigureCookie(Action{CookieAuthenticationOptions}). Host values assigned by later configurators can therefore replace values assigned by earlier configurators.
ApplyOpenIdConnect
void ApplyOpenIdConnect(OpenIdConnectOptions options)
Source
Applies registered OpenID Connect configurators to the AppSurface OIDC handler options.
Parameters
optionsThe ASP.NET Core OpenID Connect handler options registered forOidcScheme.
Remarks
Configurators run in the order they were added through ConfigureOpenIdConnect(Action{OpenIdConnectOptions}) after package defaults are assigned, so host configuration can intentionally override default handler values.
Validate
void Validate()
Source
Validates AppSurface OIDC scheme names, subject mapping, and callback paths before registration.
Exceptions
ArgumentExceptionThrown when a scheme or subject claim is blank, a callback path is blank or unsafe, orCookieSchemeandOidcSchemeuse the same value.
Remarks
Callback paths must be safe app-relative paths accepted by AppSurfaceOidcReturnUrlOptions.IsSafeAppRelativePath(string).
CookieScheme
OidcScheme
string OidcScheme { get; set; }
Source
Gets or sets the OpenID Connect authentication scheme name.
SubjectClaim
string SubjectClaim { get; set; }
Source
Gets or sets the stable subject claim that should be mapped into AppSurface auth context.
Remarks
The OIDC package defaults this to sub, then delegates to AppSurfaceAspNetCoreAuthOptions.MapSubjectClaim(string). This keeps subject mapping in the existing ASP.NET Core adapter instead of adding a parallel mapper.
CallbackPath
PathString CallbackPath { get; set; }
Source
Gets or sets the callback path assigned to the OpenID Connect handler.
SignedOutCallbackPath
PathString SignedOutCallbackPath { get; set; }
Source
Gets or sets the signed-out callback path assigned to the OpenID Connect handler.
SaveTokens
bool SaveTokens { get; set; }
Source
Gets or sets a value indicating whether tokens should be saved into the authentication ticket.
Remarks
The default is false. Enabling token storage can increase cookie size and persist sensitive token material in host-owned authentication state.
RequireClientSecret
bool RequireClientSecret { get; set; }
Source
Gets or sets a value indicating whether the OpenID Connect handler must have a client secret configured.
Remarks
The default is true for confidential ASP.NET Core web applications. Hosts using a provider flow that does not require a client secret can disable this validation explicitly.
ReturnUrls
AppSurfaceOidcReturnUrlOptions ReturnUrls { get; }
Source
Gets the return-url policy helper used by passive prompt helpers.
AppSurfaceOidcEventComposer
SourceComposes OpenID Connect event handlers so AppSurface can attach safe diagnostics without replacing host behavior.
Remarks
The composer installs a new OpenIdConnectEvents instance on the handler options. Existing handlers are copied or invoked first, then AppSurface adds diagnostics for missing subject claims, remote failures, and optional token persistence.
Compose
void Compose(OpenIdConnectOptions options, AppSurfaceOidcAuthOptions appSurfaceOptions)
Source
Rebuilds the OIDC event set with AppSurface diagnostic wrappers.
Parameters
optionsThe ASP.NET Core OpenID Connect handler options to update.appSurfaceOptionsAppSurface OIDC options that provide subject-claim and token settings.
Remarks
This method overwrites OpenIdConnectOptions.Events. Existing event delegates are preserved by copying pass-through handlers and by invoking host handlers first for OnTokenValidated, OnRemoteFailure, and, when AppSurfaceOidcAuthOptions.SaveTokens is enabled, OnTicketReceived.
AppSurfaceOidcOpenIdConnectOptionsValidator
SourceValidates OpenID Connect handler options for the AppSurface-owned OIDC scheme.
Remarks
Validation is scoped to AppSurfaceOidcAuthOptions.OidcScheme so other host-owned OIDC schemes remain untouched. The client-secret requirement follows AppSurfaceOidcAuthOptions.RequireClientSecret.
Validate
ValidateOptionsResult Validate(string? name, OpenIdConnectOptions options)
Source
Validates required OIDC handler fields for the matching AppSurface scheme.
Parameters
nameThe scheme name currently being validated.optionsThe ASP.NET Core OpenID Connect handler options.
Returns
ValidateOptionsResult.Skip for non-AppSurface schemes, success when authority, client id, and any required client secret are present, or a failure result with stable AppSurface diagnostic messages.
ThrowIfInvalid
void ThrowIfInvalid(string name, OpenIdConnectOptions options, AppSurfaceOidcAuthOptions appSurfaceOptions)
Source
Fails fast with OptionsValidationException when the AppSurface OIDC handler is invalid.
Parameters
nameThe scheme name to validate.optionsThe ASP.NET Core OpenID Connect handler options.appSurfaceOptionsAppSurface OIDC registration options that define the validation policy.
Remarks
This helper is intended for post-configuration paths that need the same validation semantics as Validate(string?, OpenIdConnectOptions).
AppSurfaceOidcAuthDiagnosticCodes
SourceStable diagnostic codes emitted by the AppSurface OIDC convenience package.
AppSurfaceOidcAuthServiceCollectionExtensions
SourceRegisters AppSurface-safe ASP.NET Core cookie and OpenID Connect authentication conventions.
AddAppSurfaceOidcAuth
IServiceCollection AddAppSurfaceOidcAuth(this IServiceCollection services, Action<AppSurfaceOidcAuthOptions>? configure = null)
Source
Adds named cookie and OpenID Connect authentication schemes with AppSurface-safe defaults.
Parameters
servicesService collection that receives the registrations.configureOptional AppSurface OIDC convention configuration.
Returns
The same service collection for chaining.
Remarks
The method registers named schemes only. It does not set global default schemes, insert middleware, execute challenges, execute redirects, execute sign-in or sign-out, provision users, or configure provider-specific SDKs. Hosts must still call UseAuthentication() and UseAuthorization() in the ASP.NET Core pipeline.
AppSurfaceOidcAuthMetadataKeys
SourceDefines safe diagnostic metadata keys emitted by the AppSurface OIDC convenience package.
Remarks
These keys identify setup and handler-state diagnostics only. They must not carry raw tokens, raw claims, emails, display names, client secrets, ID-token payloads, or provider response bodies.
AppSurfaceOidcReturnUrlOptions
SourceConfigures return-url validation for AppSurface OIDC passive prompt helpers.
Remarks
The initial package only allows local app-relative return targets. It does not URL-decode, redirect, challenge, or call an identity provider.
AllowLocalOnly
AppSurfaceOidcReturnUrlOptions AllowLocalOnly()
Source
Requires prompt targets to be local app-relative paths.
Returns
The current options instance for chaining.
Normalize
string? Normalize(string? targetPath, string parameterName)
Source
Normalizes an optional passive prompt target path according to the configured return-url policy.
Parameters
targetPathOptional prompt target path supplied by the host.parameterNameParameter name used when reporting validation failures.
Returns
null when targetPath is null, empty, or whitespace; otherwise the original target path after validation.
Exceptions
ArgumentExceptionThrown when local-only validation is enabled andtargetPathis not a safe app-relative path.
IsSafeAppRelativePath
bool IsSafeAppRelativePath(string targetPath)
Source
Determines whether a target path is safe for local app-relative prompt metadata.
Parameters
targetPathTarget path to validate.
Returns
true when the path starts with a single forward slash, contains no backslashes, and contains no control characters; otherwise false.
Remarks
Protocol-relative paths such as //example.com, backslash-prefixed paths, and paths containing backslashes are rejected because browsers and proxies can interpret them as cross-origin redirects.