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

AspNetCore

Namespaces

Type

IAppSurfaceAspNetCoreAuthContextAccessor

Source

Provides scoped access to the current ASP.NET Core request mapped into AppSurface auth contracts.

Remarks

Resolve and use this service after ASP.NET Core authentication middleware has populated the current HttpContext.User . The mapping is lazy and memoized for the scoped service instance.

Method

GetCurrentContext

AppSurfaceAspNetCoreAuthContextSnapshot GetCurrentContext()
Source

Gets the current request's AppSurface auth context mapping snapshot.

Returns

A mapping snapshot. Anonymous callers resolve successfully; setup failures are exposed through AppSurfaceAspNetCoreAuthContextSnapshot.Failure .

Type

AppSurfaceAspNetCoreAuthDiagnostics

Source

Builds safe diagnostic metadata dictionaries for ASP.NET Core auth adapter setup failures.

Remarks

Diagnostics identify missing services, policy names, and stable adapter diagnostic codes. They must not include raw claims, tokens, email addresses, display names, or other request-user secrets.

Method

MissingService

IReadOnlyDictionary<string, string> MissingService(Type serviceType, string diagnosticCode, string? policyName = null)
Source

Builds metadata for a missing ASP.NET Core service dependency.

Parameters

  • serviceType
    The service type that was required but unavailable.
  • diagnosticCode
    A stable adapter diagnostic code describing the missing dependency.
  • policyName
    Optional policy name associated with the setup failure.

Returns

A safe metadata dictionary for an auth setup-failure result.

Method

Policy

IReadOnlyDictionary<string, string> Policy(string diagnosticCode, string policyName)
Source

Builds metadata for a policy lookup or policy-related setup failure.

Parameters

  • diagnosticCode
    A stable adapter diagnostic code describing the policy failure.
  • policyName
    The requested ASP.NET Core authorization policy name.

Returns

A safe metadata dictionary for an auth setup-failure result.

Type

AppSurfacePolicyEndpointFilter

Source

Endpoint filter that maps a host-owned ASP.NET Core policy into AppSurface auth results.

Type

AppSurfacePolicyProblemDetailsMapper

Source

Maps AppSurface auth failures to API-safe ProblemDetails responses.

Method

ToResult

IResult ToResult(AppSurfaceAuthResult result, string policyName)
Source

Converts a non-allowed AppSurface auth result into a ProblemDetails result.

Parameters

  • result
    The auth failure to render.
  • policyName
    The policy name being evaluated for the endpoint.

Returns

An ASP.NET Core result that writes ProblemDetails JSON.

Type

AppSurfaceEndpointConventionBuilderExtensions

Source

Adds AppSurface auth policy helpers to ASP.NET Core endpoint builders.

Method

RequireSurfacePolicy

TBuilder RequireSurfacePolicy<TBuilder>(this TBuilder builder, string policyName)
Source

Requires an AppSurface-shaped ASP.NET Core policy result for a Minimal API endpoint or route group.

Type parameters

  • TBuilder
    Endpoint convention builder type being configured.

Parameters

  • builder
    Endpoint builder that receives the policy filter and metadata.
  • policyName
    The non-blank host-owned ASP.NET Core authorization policy name to evaluate.

Returns

The same endpoint builder for chaining.

Remarks

The helper evaluates the named host policy through IAppSurfaceAspNetCorePolicyEvaluator and maps failures to API-safe ProblemDetails responses. It does not call ASP.NET Core challenge or forbid handlers, does not redirect, and does not replace native RequireAuthorization(...) for browser flows. The endpoint is marked as anonymous for ASP.NET Core authorization middleware so host fallback policies do not run before the AppSurface endpoint filter.

Type

AppSurfaceAspNetCoreAuthContextMapper

Source

Maps an ASP.NET Core ClaimsPrincipal into an AppSurface auth context snapshot.

Remarks

Only authenticated identities are considered. Anonymous principals map to an anonymous success snapshot, while an authenticated principal without a configured stable subject claim maps to a missing-subject setup failure. This keeps AppSurface from silently treating a misconfigured authenticated request as either anonymous or allowed.

Method

Map

AppSurfaceAspNetCoreAuthContextSnapshot Map(ClaimsPrincipal? principal)
Source

Converts an ASP.NET Core principal into a neutral AppSurface auth-context snapshot.

Parameters

  • principal
    The principal populated by ASP.NET Core authentication middleware.

Returns

An anonymous snapshot for null or unauthenticated principals, an authenticated snapshot when a configured subject claim is present, or a missing-subject failure snapshot for authenticated principals without a subject.

Method

ResolveSubject

string? ResolveSubject(IReadOnlyList<ClaimsIdentity> identities)
Source

Resolves the first non-blank stable subject value using configured claim-type precedence.

Parameters

  • identities
    Authenticated identities whose claims are safe to inspect.

Returns

The first matching subject value, or null when none is present.

Type

AppSurfaceAspNetCorePolicyEvaluator

Source

Evaluates host-owned ASP.NET Core authorization policies and returns neutral AppSurface auth results.

Remarks

This evaluator does not register or own schemes, policies, middleware, challenges, forbids, redirects, cookies, OIDC, or Identity. It resolves the host policy services from the current request, delegates authentication and authorization to ASP.NET Core, and maps the resulting principal through AppSurfaceAspNetCoreAuthContextMapper . Missing request services, missing policies, missing authentication setup, and authenticated principals without a subject are reported as setup failures with safe diagnostics; host handler exceptions still propagate.

Method

AuthorizeAsync

Task<AppSurfaceAuthResult> AuthorizeAsync(string policyName, object? resource = null, CancellationToken cancellationToken = default)
Source

Evaluates a named ASP.NET Core authorization policy and maps the outcome to an AppSurface result.

Parameters

  • policyName
    The non-blank host policy name to evaluate.
  • resource
    Optional resource passed to ASP.NET Core authorization handlers. When omitted, the current HttpContext is used, matching common ASP.NET Core request-policy behavior.
  • cancellationToken
    Cancellation observed before and during policy lookup.

Returns

AppSurfaceAuthOutcome.Allowed for successful authorization, AppSurfaceAuthOutcome.Challenge for unauthenticated policy outcomes, AppSurfaceAuthOutcome.Forbid for authenticated denials, or a setup-failure result for missing host services, missing policies, or missing stable subject claims.

Remarks

Call this after the host has configured normal authentication and authorization services and middleware. ASP.NET Core policy evaluation does not accept a cancellation token, so handler execution is not cancellable through this adapter. Invalid operation exceptions that indicate missing framework authentication setup are converted to missing-services results; other host exceptions propagate.

Method

MissingServices

AppSurfaceAuthResult MissingServices(Type missingService, string diagnosticCode, string policyName, string message)
Source

Creates a missing-services setup failure with safe ASP.NET Core auth adapter diagnostics.

Parameters

  • missingService
    The service type that was expected from host setup.
  • diagnosticCode
    Stable diagnostic code for the missing setup condition.
  • policyName
    Policy name being evaluated when the setup failure occurred.
  • message
    User-facing failure message that avoids request secrets.

Returns

A neutral setup-failure auth result.

Method

ResolveRequiredService

ServiceResolution<TService> ResolveRequiredService<TService>(IServiceProvider requestServices, string diagnosticCode, string policyName, string message)
Source

Resolves a required request service and converts known missing-framework-service failures into setup failures.

Type parameters

  • TService
    The request service contract required for policy evaluation.

Parameters

  • requestServices
    Current request service provider.
  • diagnosticCode
    Stable diagnostic code to use if the service cannot be resolved.
  • policyName
    Policy name being evaluated.
  • message
    User-facing failure message that avoids request secrets.

Returns

A service resolution containing either the resolved service or a missing-services failure.

Method

IsMissingServiceResolutionFailure

bool IsMissingServiceResolutionFailure(InvalidOperationException exception)
Source

Determines whether an InvalidOperationException represents missing DI setup.

Parameters

  • exception
    The exception thrown while resolving a request service.

Returns

true when the exception is a known missing-service resolution failure.

Method

IsMissingAuthenticationSetupFailure

bool IsMissingAuthenticationSetupFailure(InvalidOperationException exception)
Source

Determines whether an authentication exception represents missing host authentication setup.

Parameters

  • exception
    The exception thrown by ASP.NET Core policy authentication.

Returns

true when the exception indicates missing authentication services or handlers.

Type

ServiceResolution<TService>

Source

Represents either a resolved request service or the setup failure produced when resolution failed.

Type parameters

  • TService
    The request service contract being resolved.
Property

Service

TService Service { get; } Source

Gets the resolved service when resolution succeeded.

Property

Failure

AppSurfaceAuthResult? Failure { get; } Source

Gets the setup failure when resolution failed.

Type

AppSurfaceAspNetCoreAuthServiceCollectionExtensions

Source

Registers the ASP.NET Core AppSurface auth adapter.

Method

AddAppSurfaceAspNetCoreAuth

IServiceCollection AddAppSurfaceAspNetCoreAuth(this IServiceCollection services, Action<AppSurfaceAspNetCoreAuthOptions>? configure = null)
Source

Adds AppSurface auth mapping services for an ASP.NET Core host.

Parameters

  • services
    Service collection that receives adapter registrations.
  • configure
    Optional adapter options callback.

Returns

The same service collection for chaining.

Remarks

The adapter registers IHttpContextAccessor , AppSurface auth options, adapter options, and scoped adapter services. It intentionally does not call AddAuthentication , register authentication schemes, call AddAuthorization , create policies, add middleware, challenge, forbid, redirect, or mutate cookies. Host applications must keep those choices in their ASP.NET Core security setup.

Type

IAppSurfaceAspNetCorePolicyEvaluator

Source

Evaluates host-owned ASP.NET Core authorization policies and maps the outcome to AppSurface auth results.

Remarks

This service does not create policies, register schemes, challenge responses, forbid responses, redirect callers, or mutate cookies. It evaluates policies registered by the host and returns a passive AppSurface result for downstream AppSurface surfaces.

Method

AuthorizeAsync

Task<AppSurfaceAuthResult> AuthorizeAsync(string policyName, object? resource = null, CancellationToken cancellationToken = default)
Source

Evaluates a named ASP.NET Core authorization policy for the current HTTP request.

Parameters

  • policyName
    Non-empty host-owned policy name.
  • resource
    Optional authorization resource passed to ASP.NET Core policy evaluation. When null, the current HttpContext is used.
  • cancellationToken
    Token observed before and during policy lookup.

Returns

A passive AppSurface auth result for the policy decision.

Exceptions

  • ArgumentException
    policyName is null, empty, or whitespace.

Remarks

ASP.NET Core authorization execution itself does not expose a cancellation-token overload. Cancellation is observed before policy lookup, during asynchronous policy lookup, and immediately before policy evaluation. Exceptions from host policy providers or handlers are allowed to propagate so host bugs are not hidden as denials.

Type

AppSurfaceAspNetCoreAuthContextSnapshot

Source

Captures the result of mapping the current ASP.NET Core request principal into an AppSurface auth context.

Remarks

Anonymous callers resolve successfully with AppSurfaceAuthContext.Anonymous . A non-null Failure means the adapter could not safely map the request, for example because there is no current HTTP request or an authenticated principal did not contain a configured subject claim.

Property

Context

AppSurfaceAuthContext Context { get; } Source

Gets the mapped AppSurface auth context.

Property

Failure

AppSurfaceAuthResult? Failure { get; } Source

Gets the setup failure when the context could not be mapped safely.

Property

Succeeded

bool Succeeded { get; } Source

Gets a value indicating whether the current request principal mapped successfully.

Type

AppSurfaceAspNetCoreAuthContextAccessor

Source

Provides the request-scoped AppSurface auth context mapped from the current ASP.NET Core HttpContext .

Remarks

The accessor is intentionally passive: it reads the host-populated HttpContext.User and does not authenticate, challenge, forbid, redirect, or register host schemes. The mapped snapshot is memoized for the lifetime of the accessor scope so repeated module code sees a stable view of the request. Resolve it only from an ASP.NET Core request scope; outside a request it returns a missing-services snapshot instead of throwing.

Method

GetCurrentContext

AppSurfaceAspNetCoreAuthContextSnapshot GetCurrentContext()
Source

Gets the current request auth context snapshot, memoizing the result for the accessor scope.

Returns

A successful anonymous or authenticated snapshot when a request principal can be mapped; otherwise a snapshot carrying a safe missing-services or missing-subject setup failure.

Remarks

A missing HttpContext is reported as AppSurfaceAuthReason.MissingServices so consumers can distinguish host setup/order issues from authorization denials.

Type

AppSurfacePolicyEndpointMetadata

Source

Describes an AppSurface endpoint policy requirement attached by AppSurfaceEndpointConventionBuilderExtensions.RequireSurfacePolicy{TBuilder} .

Remarks

This metadata is diagnostic only. ASP.NET Core authorization policies remain host-owned and are evaluated by IAppSurfaceAspNetCorePolicyEvaluator when the endpoint filter runs.

Property

PolicyName

string PolicyName { get; } Source

Gets the ASP.NET Core authorization policy name evaluated for the endpoint.

Type

AppSurfaceAspNetCoreAuthMetadataKeys

Source

Defines safe diagnostic metadata keys emitted by the ASP.NET Core auth adapter.

Remarks

These keys are for setup diagnostics only. The adapter does not copy raw claims, tokens, emails, display names, or identity-provider payloads into result metadata.

Type

AppSurfaceAspNetCoreAuthModule

Source

Registers the ASP.NET Core adapter for AppSurface auth contracts.

Remarks

This module composes the neutral AppSurfaceAuthModule and registers adapter services only. It does not configure ASP.NET Core authentication schemes, authorization policies, middleware, challenges, forbids, redirects, cookies, identity providers, endpoint filters, RazorWire UI, or Minimal API helpers.

Method

ConfigureServices

void ConfigureServices(StartupContext context, IServiceCollection services)
Source

Registers ASP.NET Core AppSurface auth adapter services.

Parameters

  • context
    Startup context for the current AppSurface composition pass.
  • services
    Service collection that receives adapter registrations.
Method

RegisterDependentModules

void RegisterDependentModules(ModuleDependencyBuilder builder)
Source

Registers the neutral AppSurface auth module dependency.

Parameters

  • builder
    Module dependency builder for the current startup graph.
Type

AppSurfaceAspNetCoreAuthOptions

Source

Configures how ASP.NET Core request principals are mapped into AppSurface auth contracts.

Remarks

These options do not configure authentication schemes, authorization policies, cookies, bearer tokens, identity providers, middleware, challenges, or forbids. ASP.NET Core remains the source of truth for those behaviors. The adapter only decides which already-authenticated claim represents the stable AppSurface subject identifier.

Method

MapSubjectClaim

AppSurfaceAspNetCoreAuthOptions MapSubjectClaim(string claimType)
Source

Gives a claim type first priority when resolving the stable AppSurface subject identifier.

Parameters

  • claimType
    Claim type that carries the host-owned stable subject id.

Returns

The current options instance so calls can be chained from registration lambdas.

Remarks

This method maps the subject identifier only. It does not map display names, emails, roles, permissions, scopes, or authorization truth. Host-owned ASP.NET Core policies remain responsible for permission decisions.

Property

SubjectClaimTypes

IReadOnlyList<string> SubjectClaimTypes { get; } Source

Gets the ordered claim types used to resolve the stable AppSurface subject identifier.

Remarks

Only authenticated ASP.NET Core identities are inspected. Claims on unauthenticated identities are ignored even when they use one of these claim types.

Type

AppSurfaceAuthorizationOptionsExtensions

Source

Adds AppSurface naming helpers for host-owned ASP.NET Core authorization policies.

Method

AddAppSurfacePolicy

AuthorizationOptions AddAppSurfacePolicy(this AuthorizationOptions options, string policyName, Action<AuthorizationPolicyBuilder> configurePolicy)
Source

Registers a host-owned ASP.NET Core authorization policy that AppSurface endpoint helpers can evaluate.

Parameters

  • options
    ASP.NET Core authorization options that receive the policy.
  • policyName
    The non-blank policy name.
  • configurePolicy
    Callback that configures the normal ASP.NET Core authorization policy.

Returns

The same authorization options for chaining.

Remarks

This method delegates to ASP.NET Core AuthorizationOptions.AddPolicy(string, Action{AuthorizationPolicyBuilder}) . AppSurface does not define a parallel policy DSL or own permission truth.