Builds safe diagnostic metadata dictionaries for ASP.NET Core auth adapter setup failures.
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.
IReadOnlyDictionary<string, string> MissingService(Type serviceType, string diagnosticCode, string? policyName = null)
Builds metadata for a missing ASP.NET Core service dependency.
serviceType
diagnosticCode
policyName
A safe metadata dictionary for an auth setup-failure result.
IReadOnlyDictionary<string, string> Policy(string diagnosticCode, string policyName)
Builds metadata for a policy lookup or policy-related setup failure.
diagnosticCode
policyName
A safe metadata dictionary for an auth setup-failure result.
Configures how ASP.NET Core request principals are mapped into AppSurface auth contracts.
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.
AppSurfaceAspNetCoreAuthOptions MapSubjectClaim(string claimType)
Gives a claim type first priority when resolving the stable AppSurface subject identifier.
claimType
The current options instance so calls can be chained from registration lambdas.
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.
IReadOnlyList<string> SubjectClaimTypes { get; }
Source
Gets the ordered claim types used to resolve the stable AppSurface subject identifier.
Only authenticated ASP.NET Core identities are inspected. Claims on unauthenticated identities are ignored even when they use one of these claim types.
Describes an AppSurface endpoint policy requirement attached by AppSurfaceEndpointConventionBuilderExtensions.RequireSurfacePolicy{TBuilder}
.
This metadata is diagnostic only. ASP.NET Core authorization policies remain host-owned and are evaluated by IAppSurfaceAspNetCorePolicyEvaluator
when the endpoint filter runs.
string PolicyName { get; }
Source
Gets the ASP.NET Core authorization policy name evaluated for the endpoint.
Defines safe diagnostic metadata keys emitted by the ASP.NET Core auth adapter.
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.
Captures the result of mapping the current ASP.NET Core request principal into an AppSurface auth context.
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.
AppSurfaceAuthContext Context { get; }
Source
Gets the mapped AppSurface auth context.
AppSurfaceAuthResult? Failure { get; }
Source
Gets the setup failure when the context could not be mapped safely.
bool Succeeded { get; }
Source
Gets a value indicating whether the current request principal mapped successfully.
Provides the request-scoped AppSurface auth context mapped from the current ASP.NET Core HttpContext
.
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.
AppSurfaceAspNetCoreAuthContextSnapshot GetCurrentContext()
Gets the current request auth context snapshot, memoizing the result for the accessor scope.
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.
A missing HttpContext
is reported as AppSurfaceAuthReason.MissingServices
so consumers can distinguish host setup/order issues from authorization denials.
Evaluates host-owned ASP.NET Core authorization policies and maps the outcome to AppSurface auth results.
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.
Task<AppSurfaceAuthResult> AuthorizeAsync(string policyName, object? resource = null, CancellationToken cancellationToken = default)
Evaluates a named ASP.NET Core authorization policy for the current HTTP request.
policyName
resource
HttpContext
is used. cancellationToken
A passive AppSurface auth result for the policy decision.
ArgumentException
policyName
is null, empty, or whitespace.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.
Maps an ASP.NET Core ClaimsPrincipal
into an AppSurface auth context snapshot.
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.
AppSurfaceAspNetCoreAuthContextSnapshot Map(ClaimsPrincipal? principal)
Converts an ASP.NET Core principal into a neutral AppSurface auth-context snapshot.
principal
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.
string? ResolveSubject(IReadOnlyList<ClaimsIdentity> identities)
Resolves the first non-blank stable subject value using configured claim-type precedence.
identities
The first matching subject value, or null
when none is present.
Registers the ASP.NET Core adapter for AppSurface auth contracts.
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.
void ConfigureServices(StartupContext context, IServiceCollection services)
Registers ASP.NET Core AppSurface auth adapter services.
context
services
void RegisterDependentModules(ModuleDependencyBuilder builder)
Registers the neutral AppSurface auth module dependency.
builder
Endpoint filter that maps a host-owned ASP.NET Core policy into AppSurface auth results.
Registers the ASP.NET Core AppSurface auth adapter.
IServiceCollection AddAppSurfaceAspNetCoreAuth(this IServiceCollection services, Action<AppSurfaceAspNetCoreAuthOptions>? configure = null)
Adds AppSurface auth mapping services for an ASP.NET Core host.
services
configure
The same service collection for chaining.
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.
Adds AppSurface auth policy helpers to ASP.NET Core endpoint builders.
TBuilder RequireSurfacePolicy<TBuilder>(this TBuilder builder, string policyName)
Requires an AppSurface-shaped ASP.NET Core policy result for a Minimal API endpoint or route group.
TBuilder
builder
policyName
The same endpoint builder for chaining.
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.
Provides scoped access to the current ASP.NET Core request mapped into AppSurface auth contracts.
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.
AppSurfaceAspNetCoreAuthContextSnapshot GetCurrentContext()
Gets the current request's AppSurface auth context mapping snapshot.
A mapping snapshot. Anonymous callers resolve successfully; setup failures are exposed through AppSurfaceAspNetCoreAuthContextSnapshot.Failure
.
Adds AppSurface naming helpers for host-owned ASP.NET Core authorization policies.
AuthorizationOptions AddAppSurfacePolicy(this AuthorizationOptions options, string policyName, Action<AuthorizationPolicyBuilder> configurePolicy)
Registers a host-owned ASP.NET Core authorization policy that AppSurface endpoint helpers can evaluate.
options
policyName
configurePolicy
The same authorization options for chaining.
This method delegates to ASP.NET Core AuthorizationOptions.AddPolicy(string, Action{AuthorizationPolicyBuilder})
. AppSurface does not define a parallel policy DSL or own permission truth.
Maps AppSurface auth failures to API-safe ProblemDetails responses.
IResult ToResult(AppSurfaceAuthResult result, string policyName)
Converts a non-allowed AppSurface auth result into a ProblemDetails result.
result
policyName
An ASP.NET Core result that writes ProblemDetails JSON.
Evaluates host-owned ASP.NET Core authorization policies and returns neutral AppSurface auth results.
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.
Task<AppSurfaceAuthResult> AuthorizeAsync(string policyName, object? resource = null, CancellationToken cancellationToken = default)
Evaluates a named ASP.NET Core authorization policy and maps the outcome to an AppSurface result.
policyName
resource
HttpContext
is used, matching common ASP.NET Core request-policy behavior. cancellationToken
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.
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.
AppSurfaceAuthResult MissingServices(Type missingService, string diagnosticCode, string policyName, string message)
Creates a missing-services setup failure with safe ASP.NET Core auth adapter diagnostics.
missingService
diagnosticCode
policyName
message
A neutral setup-failure auth result.
ServiceResolution<TService> ResolveRequiredService<TService>(IServiceProvider requestServices, string diagnosticCode, string policyName, string message)
Resolves a required request service and converts known missing-framework-service failures into setup failures.
TService
requestServices
diagnosticCode
policyName
message
A service resolution containing either the resolved service or a missing-services failure.
bool IsMissingServiceResolutionFailure(InvalidOperationException exception)
Determines whether an InvalidOperationException
represents missing DI setup.
exception
true
when the exception is a known missing-service resolution failure.
bool IsMissingAuthenticationSetupFailure(InvalidOperationException exception)
Determines whether an authentication exception represents missing host authentication setup.
exception
true
when the exception indicates missing authentication services or handlers.
Represents either a resolved request service or the setup failure produced when resolution failed.
TService
TService Service { get; }
Source
Gets the resolved service when resolution succeeded.
AppSurfaceAuthResult? Failure { get; }
Source
Gets the setup failure when resolution failed.