AppSurface Search
Section API Reference
API Reference Language: C# Component: Auth Audience: developer

Oidc

Type

AppSurfaceOidcReturnUrlOptions

Source

Configures 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.

Method

AllowLocalOnly

AppSurfaceOidcReturnUrlOptions AllowLocalOnly()
Source

Requires prompt targets to be local app-relative paths.

Returns

The current options instance for chaining.

Method

Normalize

string? Normalize(string? targetPath, string parameterName)
Source

Normalizes an optional passive prompt target path according to the configured return-url policy.

Parameters

  • targetPath
    Optional prompt target path supplied by the host.
  • parameterName
    Parameter name used when reporting validation failures.

Returns

null when targetPath is null, empty, or whitespace; otherwise the original target path after validation.

Exceptions

  • ArgumentException
    Thrown when local-only validation is enabled and targetPath is not a safe app-relative path.
Method

IsSafeAppRelativePath

bool IsSafeAppRelativePath(string targetPath)
Source

Determines whether a target path is safe for local app-relative prompt metadata.

Parameters

  • targetPath
    Target 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.

Type

AppSurfaceOidcEventComposer

Source

Composes 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.

Method

Compose

void Compose(OpenIdConnectOptions options, AppSurfaceOidcAuthOptions appSurfaceOptions)
Source

Rebuilds the OIDC event set with AppSurface diagnostic wrappers.

Parameters

  • options
    The ASP.NET Core OpenID Connect handler options to update.
  • appSurfaceOptions
    AppSurface 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 .

Type

AppSurfaceOidcAuthOptions

Source

Configures 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.

Method

ConfigureCookie

AppSurfaceOidcAuthOptions ConfigureCookie(Action<CookieAuthenticationOptions> configure)
Source

Adds host-owned cookie handler configuration.

Parameters

  • configure
    Callback that receives the ASP.NET Core cookie handler options.

Returns

The current options instance for chaining.

Method

ConfigureOpenIdConnect

AppSurfaceOidcAuthOptions ConfigureOpenIdConnect(Action<OpenIdConnectOptions> configure)
Source

Adds host-owned OpenID Connect handler configuration.

Parameters

  • configure
    Callback 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.

Method

CreateLoginPrompt

AppSurfaceLoginPrompt CreateLoginPrompt(string? targetPath = null, string? displayText = null)
Source

Creates a passive login prompt for host-owned login UI.

Parameters

  • targetPath
    Optional safe app-relative target path.
  • displayText
    Optional display text for the host UI.

Returns

A passive login prompt that does not execute a redirect or challenge.

Method

CreateLogoutPrompt

AppSurfaceLogoutPrompt CreateLogoutPrompt(string? targetPath = null, string? displayText = null)
Source

Creates a passive logout prompt for host-owned logout UI.

Parameters

  • targetPath
    Optional safe app-relative target path.
  • displayText
    Optional display text for the host UI.

Returns

A passive logout prompt that does not execute a redirect or sign-out.

Method

ApplyCookie

void ApplyCookie(CookieAuthenticationOptions options)
Source

Applies registered cookie configurators to the AppSurface cookie handler options.

Parameters

  • options
    The ASP.NET Core cookie handler options registered for CookieScheme .

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.

Method

ApplyOpenIdConnect

void ApplyOpenIdConnect(OpenIdConnectOptions options)
Source

Applies registered OpenID Connect configurators to the AppSurface OIDC handler options.

Parameters

  • options
    The ASP.NET Core OpenID Connect handler options registered for OidcScheme .

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.

Method

Validate

void Validate()
Source

Validates AppSurface OIDC scheme names, subject mapping, and callback paths before registration.

Exceptions

  • ArgumentException
    Thrown when a scheme or subject claim is blank, a callback path is blank or unsafe, or CookieScheme and OidcScheme use the same value.

Remarks

Callback paths must be safe app-relative paths accepted by AppSurfaceOidcReturnUrlOptions.IsSafeAppRelativePath(string) .

Property

CookieScheme

string CookieScheme { get; set; } Source

Gets or sets the cookie authentication scheme name.

Property

OidcScheme

string OidcScheme { get; set; } Source

Gets or sets the OpenID Connect authentication scheme name.

Property

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.

Property

CallbackPath

PathString CallbackPath { get; set; } Source

Gets or sets the callback path assigned to the OpenID Connect handler.

Property

SignedOutCallbackPath

PathString SignedOutCallbackPath { get; set; } Source

Gets or sets the signed-out callback path assigned to the OpenID Connect handler.

Property

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.

Property

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.

Property

ReturnUrls

AppSurfaceOidcReturnUrlOptions ReturnUrls { get; } Source

Gets the return-url policy helper used by passive prompt helpers.

Type

AppSurfaceOidcAuthServiceCollectionExtensions

Source

Registers AppSurface-safe ASP.NET Core cookie and OpenID Connect authentication conventions.

Method

AddAppSurfaceOidcAuth

IServiceCollection AddAppSurfaceOidcAuth(this IServiceCollection services, Action<AppSurfaceOidcAuthOptions>? configure = null)
Source

Adds named cookie and OpenID Connect authentication schemes with AppSurface-safe defaults.

Parameters

  • services
    Service collection that receives the registrations.
  • configure
    Optional 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.

Type

AppSurfaceOidcAuthDiagnosticCodes

Source

Stable diagnostic codes emitted by the AppSurface OIDC convenience package.

Type

AppSurfaceOidcOpenIdConnectOptionsValidator

Source

Validates 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 .

Method

Validate

ValidateOptionsResult Validate(string? name, OpenIdConnectOptions options)
Source

Validates required OIDC handler fields for the matching AppSurface scheme.

Parameters

  • name
    The scheme name currently being validated.
  • options
    The 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.

Method

ThrowIfInvalid

void ThrowIfInvalid(string name, OpenIdConnectOptions options, AppSurfaceOidcAuthOptions appSurfaceOptions)
Source

Fails fast with OptionsValidationException when the AppSurface OIDC handler is invalid.

Parameters

  • name
    The scheme name to validate.
  • options
    The ASP.NET Core OpenID Connect handler options.
  • appSurfaceOptions
    AppSurface 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) .

Type

AppSurfaceOidcAuthMetadataKeys

Source

Defines 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.