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

Auth

Namespaces

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 message supplied by the host adapter for its own display contract.
  • metadataOptional 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 message supplied by the host adapter for its own display contract.
  • metadataOptional 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 message supplied by the host adapter for its own display contract.
  • metadataOptional 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 message supplied by the host adapter for its own display contract.
  • metadataOptional 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 message supplied by the host adapter for its own display contract.
  • metadataOptional 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 message supplied by the host adapter for its own display contract.
  • metadataOptional 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 message supplied by the host adapter for its own display contract.
  • metadataOptional 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 message supplied by the host adapter for its own display contract.
  • metadataOptional 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 message supplied by the host adapter for its own display contract.
  • metadataOptional 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 message supplied by the host adapter for its own display contract.
  • metadataOptional 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 message supplied by the host adapter for that adapter's own display contract.

Property

Metadata

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

Gets copied metadata that can help adapters 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.

Type

AppSurfaceUserIdentityResolutionContext

Source

Carries display-safe context for resolving an external subject to an app-owned user id.

Remarks

The context is an input to an app-owned resolver. It may carry safe correlation, issuer, tenant, or provisioning policy hints, but those hints are not authority unless the application validates them against its own security and persistence rules. Metadata is copied with ordinal keys.

Property

Empty

AppSurfaceUserIdentityResolutionContext Empty { get; } Source

Gets an empty resolution context.

Property

CorrelationId

string? CorrelationId { get; } Source

Gets the optional display-safe correlation id.

Property

Metadata

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

Gets copied metadata that can help an app resolver preserve display-safe context.

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

ExternalSubject

Source

Describes an authenticated external subject before it has been resolved to an app-owned user id.

Remarks

The uniqueness key is the ordinal tuple of Issuer, Subject, and optional PartitionKey. Use PartitionKey only for host-validated realm, tenant, client, or environment context that is part of the subject namespace. AppSurface does not treat the partition as tenant authority or authorization truth. The raw values are intentionally omitted from ToString.

Property

Issuer

string Issuer { get; } Source

Gets the stable issuer or identity-provider namespace.

Property

Subject

string Subject { get; } Source

Gets the stable subject id inside the issuer namespace.

Property

PartitionKey

string? PartitionKey { get; } Source

Gets the optional host-validated partition that participates in the uniqueness key.

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

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

AppSurfaceUserIdentityResult

Source

Represents the result of resolving an external subject to a durable app-owned user id.

Remarks

This result family is intentionally separate from AppSurfaceAuthResult. Authentication, policy, and navigation outcomes remain host-auth decisions; identity resolution describes the app-owned mapping step that can happen after the host has authenticated a subject. Messages and metadata should be display-safe and avoid raw subjects, emails, tokens, and provider payloads by default.

Method

Resolved

AppSurfaceUserIdentityResult Resolved(AppUserId appUserId, ExternalSubject subject, string? message = null, IReadOnlyDictionary<string, string>? metadata = null) Source

Creates a successful identity resolution result.

Parameters

  • appUserIdThe durable app-owned user id.
  • subjectThe external subject tuple that resolved to the app user.
  • messageOptional display-safe message supplied by the app resolver.
  • metadataOptional display or diagnostic metadata copied with ordinal keys.

Returns

A resolved identity result.

Method

MissingSubject

AppSurfaceUserIdentityResult MissingSubject(string? message = null, IReadOnlyDictionary<string, string>? metadata = null) Source

Creates a failure result for a missing external subject.

Parameters

  • messageOptional display-safe message supplied by the app resolver.
  • metadataOptional display or diagnostic metadata copied with ordinal keys.

Returns

A missing-subject identity result.

Method

MalformedSubject

AppSurfaceUserIdentityResult MalformedSubject(string? message = null, IReadOnlyDictionary<string, string>? metadata = null) Source

Creates a failure result for a malformed external subject.

Parameters

  • messageOptional display-safe message supplied by the app resolver.
  • metadataOptional display or diagnostic metadata copied with ordinal keys.

Returns

A malformed-subject identity result.

Method

DisabledAppUser

AppSurfaceUserIdentityResult DisabledAppUser(ExternalSubject? subject = null, string? message = null, IReadOnlyDictionary<string, string>? metadata = null) Source

Creates a failure result for a disabled app user.

Parameters

  • subjectOptional external subject involved in the failed resolution.
  • messageOptional display-safe message supplied by the app resolver.
  • metadataOptional display or diagnostic metadata copied with ordinal keys.

Returns

A disabled-app-user identity result.

Method

StaleOrUnknownSession

AppSurfaceUserIdentityResult StaleOrUnknownSession(ExternalSubject? subject = null, string? message = null, IReadOnlyDictionary<string, string>? metadata = null) Source

Creates a failure result for a stale or unknown session.

Parameters

  • subjectOptional external subject involved in the failed resolution.
  • messageOptional display-safe message supplied by the app resolver.
  • metadataOptional display or diagnostic metadata copied with ordinal keys.

Returns

A stale-or-unknown-session identity result.

Method

DuplicateMapping

AppSurfaceUserIdentityResult DuplicateMapping(ExternalSubject? subject = null, string? message = null, IReadOnlyDictionary<string, string>? metadata = null) Source

Creates a failure result for duplicate mappings.

Parameters

  • subjectOptional external subject involved in the failed resolution.
  • messageOptional display-safe message supplied by the app resolver.
  • metadataOptional display or diagnostic metadata copied with ordinal keys.

Returns

A duplicate-mapping identity result.

Method

StoreUnavailable

AppSurfaceUserIdentityResult StoreUnavailable(ExternalSubject? subject = null, string? message = null, IReadOnlyDictionary<string, string>? metadata = null) Source

Creates a failure result for an unavailable app-owned identity store.

Parameters

  • subjectOptional external subject involved in the failed resolution.
  • messageOptional display-safe message supplied by the app resolver.
  • metadataOptional display or diagnostic metadata copied with ordinal keys.

Returns

A store-unavailable identity result.

Method

ProvisioningDenied

AppSurfaceUserIdentityResult ProvisioningDenied(ExternalSubject? subject = null, string? message = null, IReadOnlyDictionary<string, string>? metadata = null) Source

Creates a failure result when the app declines provisioning or attachment.

Parameters

  • subjectOptional external subject involved in the failed resolution.
  • messageOptional display-safe message supplied by the app resolver.
  • metadataOptional display or diagnostic metadata copied with ordinal keys.

Returns

A provisioning-denied identity result.

Property

Status

AppSurfaceUserIdentityStatus Status { get; } Source

Gets the identity resolution status.

Property

AppUserId

AppUserId? AppUserId { get; } Source

Gets the resolved app-owned user id when Succeeded is true.

Property

Subject

ExternalSubject? Subject { get; } Source

Gets the external subject tuple involved in resolution when it was available and valid enough to report safely.

Property

Message

string? Message { get; } Source

Gets an optional display-safe message supplied by the app resolver.

Property

Metadata

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

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

Property

Succeeded

bool Succeeded { get; } Source

Gets a value indicating whether the external subject resolved to an app-owned user id.

Enum

AppSurfaceUserIdentityStatus

Source

Defines result states for resolving an external subject to an app-owned user id.

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

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

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

IAppSurfaceUserIdentityResolver

Source

Resolves authenticated external subjects to durable app-owned user ids.

Remarks

Applications implement this interface with their own persistence, provisioning, disabled-user, and duplicate-mapping policies. Implementations should make successful resolution idempotent for the same ExternalSubject tuple, honor cancellation before starting expensive work and while awaiting I/O, and handle concurrent first-time resolution without creating duplicate app users.

Prefer enforcing uniqueness at the mapping store with a unique constraint over the external subject tuple (issuer, subject, and partition key), then make competing inserts converge on the same app user id through optimistic concurrency or a transaction retry. Stores that cannot enforce uniqueness should use an equivalent first-provisioning guard, such as a short distributed lock scoped to the external subject tuple.

Avoid a check-then-insert flow that reads a missing mapping and blindly creates a new app user. Concurrent sign-ins can otherwise provision duplicate app users before either caller observes the other mapping.

Method

ResolveAsync

ValueTask<AppSurfaceUserIdentityResult> ResolveAsync(ExternalSubject subject, AppSurfaceUserIdentityResolutionContext context, CancellationToken cancellationToken = default) Source

Resolves an external subject to a durable app-owned user id.

Parameters

  • subjectThe authenticated external subject to resolve.
  • contextDisplay-safe resolution context supplied by the host integration.
  • cancellationTokenCancellation token for resolver work and awaited I/O.

Returns

An identity resolution result with either an app-owned user id or a typed failure state.

Type

AppUserId

Source

Identifies a durable app-owned user record after an external authenticated subject has been resolved.

Remarks

AppUserId belongs to the consuming application. AppSurface does not allocate ids, prescribe storage, or treat the id as a permission source. The value is intentionally omitted from ToString so accidental logs and diagnostics do not disclose user identifiers by default.

Property

Value

string Value { get; } Source

Gets the stable app-owned user id value.