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

Auth

Namespaces

Type

AppSurfaceAuthMetadataKeys

Source

Defines reserved metadata keys used by AppSurface auth contracts.

Remarks

Metadata is context for diagnostics, display, and adapter hand-off. It is not an authorization source of truth unless a host-owned adapter validates the value against the host security system. The appsurface. prefix is reserved for AppSurface-owned keys so future typed properties can migrate existing metadata without key collisions.

Type

AppSurfaceAuthAuditEvent

Source

Describes a passive AppSurface auth audit event.

Remarks

This value does not write logs, traces, metrics, or persistent audit records. Host applications own audit transport, retention, redaction, and access control. Metadata should remain non-sensitive and diagnostic.

Property

Name

string Name { get; } Source

Gets the stable event name.

Property

Timestamp

DateTimeOffset Timestamp { get; } Source

Gets the timestamp supplied by the host.

Property

Outcome

AppSurfaceAuthOutcome Outcome { get; } Source

Gets the high-level auth outcome associated with the event.

Property

Reason

AppSurfaceAuthReason Reason { get; } Source

Gets the concrete auth reason associated with the event.

Property

UserId

string? UserId { get; } Source

Gets the optional user identifier associated with the event.

Property

SessionId

string? SessionId { get; } Source

Gets the optional session identifier associated with the event.

Property

Metadata

IReadOnlyDictionary<string, string> Metadata { get; } Source

Gets copied metadata that can help adapters or diagnostics preserve host-specific context.

Type

AppSurfaceUser

Source

Represents the surface-neutral identity information AppSurface modules can share about a user.

Remarks

AppSurfaceUser is not a claims principal, identity-provider user, or authorization policy result. Host adapters should map their security system into this passive value only after authenticating the subject. Metadata is copied with ordinal keys and should be treated as context, not as authority for authorization decisions.

Property

Id

string Id { get; } Source

Gets the stable host-owned user identifier.

Property

DisplayName

string? DisplayName { get; } Source

Gets the optional display name for UI or diagnostics.

Property

Email

string? Email { get; } Source

Gets the optional email address for UI or diagnostics.

Property

Metadata

IReadOnlyDictionary<string, string> Metadata { get; } Source

Gets copied metadata that can help adapters or diagnostics preserve host-specific context.

Type

AppSurfaceLoginPrompt

Source

Describes a possible host-owned login prompt without executing sign-in or redirects.

Remarks

The prompt is passive. It never writes cookies, challenges a caller, redirects a response, or invokes an identity provider. Host UI or host adapters decide whether and how to act on it.

Property

TargetPath

string? TargetPath { get; } Source

Gets the optional app-relative target for host-owned login UI.

Property

DisplayText

string? DisplayText { get; } Source

Gets optional display text for host-owned login UI.

Property

Metadata

IReadOnlyDictionary<string, string> Metadata { get; } Source

Gets copied metadata that can help adapters or diagnostics preserve host-specific context.

Type

AppSurfaceLogoutPrompt

Source

Describes a possible host-owned logout prompt without executing sign-out or redirects.

Remarks

The prompt is passive. It never clears cookies, signs out a caller, redirects a response, or invokes an identity provider. Host UI or host adapters decide whether and how to act on it.

Property

TargetPath

string? TargetPath { get; } Source

Gets the optional app-relative target for host-owned logout UI.

Property

DisplayText

string? DisplayText { get; } Source

Gets optional display text for host-owned logout UI.

Property

Metadata

IReadOnlyDictionary<string, string> Metadata { get; } Source

Gets copied metadata that can help adapters or diagnostics preserve host-specific context.

Type

AppSurfaceAuthOptions

Source

Options root for the surface-neutral AppSurface auth composition boundary.

Remarks

This boundary-preview type is intentionally empty. It exists so future AppSurface auth contracts can add settings through a stable options root after those contracts are proven. It does not configure authentication schemes, authorization policies, user or session access, tenant behavior, identity providers, cookies, bearer tokens, challenges, forbids, middleware, endpoint filters, or UI. Host applications must keep those choices in their host-specific security configuration until a later AppSurface package explicitly owns them.

Type

AppSurfaceAuthContext

Source

Captures the passive user and session context available to AppSurface auth-aware modules.

Remarks

A context with no User is a valid anonymous context. The context does not evaluate policies, read the current request, or wrap ASP.NET Core ClaimsPrincipal; host-specific adapters own those mappings.

Property

Anonymous

AppSurfaceAuthContext Anonymous { get; } Source

Gets an anonymous auth context with no user, no session, and no metadata.

Property

User

AppSurfaceUser? User { get; } Source

Gets the optional authenticated user description.

Property

Session

AppSurfaceSession? Session { get; } Source

Gets the optional session description.

Property

Metadata

IReadOnlyDictionary<string, string> Metadata { get; } Source

Gets copied metadata that can help adapters or diagnostics preserve host-specific context.

Property

IsAuthenticated

bool IsAuthenticated { get; } Source

Gets a value indicating whether the context contains a user description.

Type

AppSurfaceAuthModule

Source

Registers the surface-neutral AppSurface auth composition boundary.

Remarks

AppSurfaceAuthModule is a boundary-preview module. It gives AppSurface packages a stable place to compose future auth contracts without taking a dependency on ASP.NET Core authentication, authorization policies, identity providers, middleware, endpoint filters, cookies, bearer tokens, or UI. Registering this module does not sign users in, inspect requests, challenge callers, forbid callers, or enforce authorization; host applications must continue to configure those behaviors in their host-specific security stack.

Method

ConfigureServices

void ConfigureServices(StartupContext context, IServiceCollection services) Source

Registers the AppSurface auth boundary options type.

Parameters

  • contextStartup context for the current AppSurface composition pass.
  • servicesService collection that receives the boundary-preview options registration.

Remarks

This method registers AppSurfaceAuthOptions with the Microsoft Options pattern so later AppSurface auth contracts have a documented options home. It intentionally adds no runtime auth behavior and performs no request, principal, policy, middleware, or identity-provider configuration.

Method

RegisterDependentModules

void RegisterDependentModules(ModuleDependencyBuilder builder) Source

Registers modules required by the AppSurface auth boundary.

Parameters

  • builderThe module dependency builder for the current startup graph.

Remarks

The boundary preview has no dependent modules. Future host-specific auth integrations should declare their own dependencies instead of relying on this module to pull in ASP.NET Core or UI packages.

Type

AppSurfaceSession

Source

Represents surface-neutral session information associated with an AppSurface auth context.

Remarks

Session timestamps use DateTimeOffset so host adapters can preserve their original offset. AppSurface does not convert, refresh, revoke, store, or validate the backing host session.

Property

Id

string Id { get; } Source

Gets the stable host-owned session identifier.

Property

StartedAt

DateTimeOffset? StartedAt { get; } Source

Gets the optional timestamp when the host session began.

Property

ExpiresAt

DateTimeOffset? ExpiresAt { get; } Source

Gets the optional timestamp when the host session expires.

Property

Metadata

IReadOnlyDictionary<string, string> Metadata { get; } Source

Gets copied metadata that can help adapters or diagnostics preserve host-specific context.

Type

AppSurfaceAuthResult

Source

Represents a passive AppSurface auth decision.

Remarks

AppSurfaceAuthResult describes an auth decision; it does not challenge, forbid, redirect, evaluate policies, sign users in, or sign users out. Host-specific packages map these outcomes to platform behavior.

Method

Allowed

AppSurfaceAuthResult Allowed(AppSurfaceAuthContext? context = null, string? message = null, IReadOnlyDictionary<string, string>? metadata = null) Source

Creates a result that allows the requested operation.

Parameters

  • contextOptional auth context that was evaluated.
  • messageOptional display-safe message supplied by the host adapter.
  • metadataOptional display or diagnostic metadata copied with ordinal keys.

Returns

An allowed auth result.

Method

Challenge

AppSurfaceAuthResult Challenge(AppSurfaceAuthContext? context = null, string? message = null, IReadOnlyDictionary<string, string>? metadata = null) Source

Creates a result indicating that the caller should authenticate before retrying.

Parameters

  • contextOptional auth context that was evaluated.
  • messageOptional display-safe message supplied by the host adapter.
  • metadataOptional display or diagnostic metadata copied with ordinal keys.

Returns

A challenge auth result.

Method

Unauthenticated

AppSurfaceAuthResult Unauthenticated(AppSurfaceAuthContext? context = null, string? message = null, IReadOnlyDictionary<string, string>? metadata = null) Source

Creates a result indicating that the caller is not authenticated.

Parameters

  • contextOptional auth context that was evaluated.
  • messageOptional display-safe message supplied by the host adapter.
  • metadataOptional display or diagnostic metadata copied with ordinal keys.

Returns

A challenge auth result.

Method

Forbid

AppSurfaceAuthResult Forbid(AppSurfaceAuthContext? context = null, string? message = null, IReadOnlyDictionary<string, string>? metadata = null) Source

Creates a result indicating that the authenticated caller is forbidden.

Parameters

  • contextOptional auth context that was evaluated.
  • messageOptional display-safe message supplied by the host adapter.
  • metadataOptional display or diagnostic metadata copied with ordinal keys.

Returns

A forbidden auth result.

Method

Forbidden

AppSurfaceAuthResult Forbidden(AppSurfaceAuthContext? context = null, string? message = null, IReadOnlyDictionary<string, string>? metadata = null) Source

Creates a result indicating that the authenticated caller is forbidden.

Parameters

  • contextOptional auth context that was evaluated.
  • messageOptional display-safe message supplied by the host adapter.
  • metadataOptional display or diagnostic metadata copied with ordinal keys.

Returns

A forbidden auth result.

Method

MissingPolicy

AppSurfaceAuthResult MissingPolicy(AppSurfaceAuthContext? context = null, string? message = null, IReadOnlyDictionary<string, string>? metadata = null) Source

Creates a setup-failure result for a missing host-owned policy.

Parameters

  • contextOptional auth context that was evaluated.
  • messageOptional display-safe message supplied by the host adapter.
  • metadataOptional display or diagnostic metadata copied with ordinal keys.

Returns

A setup-failure auth result.

Method

MissingServices

AppSurfaceAuthResult MissingServices(AppSurfaceAuthContext? context = null, string? message = null, IReadOnlyDictionary<string, string>? metadata = null) Source

Creates a setup-failure result for missing host-owned auth services.

Parameters

  • contextOptional auth context that was evaluated.
  • messageOptional display-safe message supplied by the host adapter.
  • metadataOptional display or diagnostic metadata copied with ordinal keys.

Returns

A setup-failure auth result.

Method

MissingSubject

AppSurfaceAuthResult MissingSubject(AppSurfaceAuthContext? context = null, string? message = null, IReadOnlyDictionary<string, string>? metadata = null) Source

Creates a setup-failure result for an authenticated caller that could not be mapped to a stable subject.

Parameters

  • contextOptional auth context that was evaluated.
  • messageOptional display-safe message supplied by the host adapter.
  • metadataOptional display or diagnostic metadata copied with ordinal keys.

Returns

A setup-failure auth result.

Method

UnsafeReturnUrl

AppSurfaceAuthResult UnsafeReturnUrl(AppSurfaceAuthContext? context = null, string? message = null, IReadOnlyDictionary<string, string>? metadata = null) Source

Creates a result for an unsafe return or navigation target.

Parameters

  • contextOptional auth context that was evaluated.
  • messageOptional display-safe message supplied by the host adapter.
  • metadataOptional display or diagnostic metadata copied with ordinal keys.

Returns

An unsafe-navigation auth result.

Method

StaleOrUnknownSession

AppSurfaceAuthResult StaleOrUnknownSession(AppSurfaceAuthContext? context = null, string? message = null, IReadOnlyDictionary<string, string>? metadata = null) Source

Creates a result for stale, expired, missing, or unresolved session state.

Parameters

  • contextOptional auth context that was evaluated.
  • messageOptional display-safe message supplied by the host adapter.
  • metadataOptional display or diagnostic metadata copied with ordinal keys.

Returns

A stale-or-unknown-session auth result.

Property

Outcome

AppSurfaceAuthOutcome Outcome { get; } Source

Gets the high-level auth outcome.

Property

Reason

AppSurfaceAuthReason Reason { get; } Source

Gets the concrete reason associated with Outcome.

Property

Context

AppSurfaceAuthContext? Context { get; } Source

Gets the optional auth context that was evaluated.

Property

Message

string? Message { get; } Source

Gets an optional display-safe message supplied by the host adapter.

Property

Metadata

IReadOnlyDictionary<string, string> Metadata { get; } Source

Gets copied metadata that can help adapters or diagnostics preserve host-specific context.

Property

IsAllowed

bool IsAllowed { get; } Source

Gets a value indicating whether the outcome allows the requested operation.

Property

RequiresAuthentication

bool RequiresAuthentication { get; } Source

Gets a value indicating whether the caller should authenticate before retrying.

Property

IsConfigurationFailure

bool IsConfigurationFailure { get; } Source

Gets a value indicating whether the outcome represents host setup or configuration failure.

Enum

AppSurfaceAuthOutcome

Source

Defines the high-level auth outcome AppSurface modules can understand without owning host authentication.

Enum

AppSurfaceAuthReason

Source

Defines the concrete reason associated with an AppSurface auth outcome.