IReadOnlyDictionary<string, AppSurfaceDevAuthPersona> Personas { get; }
Source
Gets the configured local-development personas.
DevAuth
AppSurfaceDevAuthHandler
SourceAuthenticates the configured DevAuth scheme from the local persona cookie.
Remarks
The handler reads only the protected persona id cookie, resolves that id against seeded personas, and returns AuthenticateResult.NoResult() for blank, tampered, stale, or unknown state. It does not issue challenges, sign users in, or validate production identity tokens.
HandleAuthenticateAsync
Task<AuthenticateResult> HandleAuthenticateAsync()
Source
Attempts to authenticate the selected local persona.
Returns
Success with a claims principal for a known protected persona id, or no result when no trustworthy persona is selected.
ProtectPersonaId
string ProtectPersonaId(string personaId)
Source
Protects a persona id with the same data-protection purpose as the endpoint cookie writer.
Parameters
personaIdConfigured persona id to protect for tests.
Returns
A protected cookie payload containing only the persona id.
AppSurfaceDevAuthPersonaCollection
SourceCollection of seeded local-development personas for AppSurface DevAuth.
Add
AppSurfaceDevAuthPersonaCollection Add(string id, Action<AppSurfaceDevAuthUserBuilder> configure)
Source
Adds a local-development persona.
Parameters
idURL-safe local persona id.configureCallback that configures the persona.
Returns
The same collection for chaining.
Personas
AppSurfaceDevAuthEndpointRouteBuilderExtensions
SourceMaps AppSurface DevAuth local-only control and status endpoints.
MapAppSurfaceDevAuth
IEndpointRouteBuilder MapAppSurfaceDevAuth(this IEndpointRouteBuilder endpoints)
Source
Maps the AppSurface DevAuth control page, status JSON, select persona, and clear persona endpoints.
Parameters
endpointsEndpoint route builder that receives the local-only endpoints.
Returns
The same endpoint route builder for chaining.
Remarks
Map this after building the app and before relying on the persona lab in a local proof host. The method validates the same materialized options used by the authentication handler, reserves the configured path prefix, and rejects existing endpoints whose route templates are equivalent to DevAuth control routes even when parameter names differ. Control endpoints stay loopback-only by default, honor AppSurfaceDevAuthOptions.AllowedEnvironmentNames, and set no-store headers on every response. The control-page GET accepts an optional returnUrl query value. A safe rooted local value is propagated to every select and clear form action, and successful mutations return through a local redirect. Missing or rejected values are omitted, so mutations render the control page normally.
BuildStatus
AppSurfaceDevAuthStatus BuildStatus(HttpContext httpContext, IHostEnvironment environment, AppSurfaceDevAuthOptions options, IDataProtectionProvider dataProtectionProvider)
Source
Builds safe DevAuth status from the selected persona cookie for endpoint and marker rendering.
DisplayPersonaName
string DisplayPersonaName(AppSurfaceDevAuthPersona persona)
Source
Returns a safe display name for a configured persona.
DisplayStatusPersonaName
string DisplayStatusPersonaName(AppSurfaceDevAuthStatus status)
Source
Returns a safe display name for the current status.
DisplayStatusSubject
string DisplayStatusSubject(AppSurfaceDevAuthStatus status)
Source
Returns a safe subject value for the current status.
BuildMutationUrl
string BuildMutationUrl(string pathPrefix, string action, string? returnUrl)
Source
Builds a DevAuth mutation action URL and optionally appends a URI-escaped return URL.
Parameters
pathPrefixValidated DevAuth path prefix without a trailing slash.actionMutation action path relative topathPrefix.returnUrlOptional return URL that the caller has already validated or normalized. This method does not determine whether the target is local or safe.
Returns
The bare mutation action when returnUrl is null; otherwise the mutation action with one URI-escaped returnUrl query value.
NormalizeLocalReturnUrl
string NormalizeLocalReturnUrl(string? value)
Source
Normalizes a local marker return URL and falls back to the site root for unsafe values.
AppSurfaceDevAuthEndpointMetadata
SourceMarker metadata applied to endpoints mapped by AppSurface DevAuth.
AppSurfaceDevAuthDiagnostics
SourceStable AppSurface DevAuth diagnostic codes and safe metadata keys.
AppSurfaceDevAuthStartupValidator
SourcePerforms DevAuth startup validation after the host service provider has been built.
Remarks
Registration validates the caller-supplied environment early, but this hosted service re-checks the real environment resolved from dependency injection and inspects the final authentication defaults and schemes. It rejects environments outside the DevAuth activation allow-list and real authentication scheme conflicts unless the consumer explicitly enabled the local-proof override. This service is internal infrastructure for AppSurfaceDevAuthServiceCollectionExtensions.
StartAsync
Task StartAsync(CancellationToken cancellationToken)
Source
Validates that DevAuth is running in an allowed environment and is not silently coexisting with real authentication.
Parameters
cancellationTokenStartup cancellation token; validation performs only in-memory inspection.
Returns
A completed task when the final host configuration is safe for local DevAuth.
Exceptions
ArgumentExceptionThrown when materialized DevAuth options contain blank required values or an invalidAppSurfaceDevAuthOptions.AllowedEnvironmentNamesallow-list.AppSurfaceDevAuthExceptionThrown withASDEV001outside configured proof environments or withASDEV002when real schemes/defaults are present without the explicit override.
StopAsync
Task StopAsync(CancellationToken cancellationToken)
Source
Stops the validator.
Parameters
cancellationTokenStop cancellation token.
Returns
A completed task because the validator does not own background work.
AppSurfaceDevAuthPersona
SourceRepresents a seeded local-development persona that can be selected by AppSurface DevAuth.
Id
string Id { get; }
Source
Gets the stable local persona id used by the DevAuth selection cookie.
DisplayName
string DisplayName { get; }
Source
Gets the display name shown on the local-only DevAuth control page.
SubjectClaimType
string SubjectClaimType { get; }
Source
Gets the claim type used to expose the stable local subject.
Subject
string Subject { get; }
Source
Gets the stable local subject value for this persona.
Claims
IReadOnlyList<Claim> Claims { get; }
Source
Gets safe local-development claims issued for this persona.
AppSurfaceDevAuthMarker
SourceRenders an explicit AppSurface DevAuth state marker for host pages.
Remarks
Use this helper from pages or layouts where the selected fake persona should stay visible while navigating the app. The returned HTML contains only safe persona display values and POST-only controls that target the mapped DevAuth endpoints. DevAuth does not automatically inject this marker into host output, and this helper returns an empty string when the current environment is not in AppSurfaceDevAuthOptions.AllowedEnvironmentNames. With default styles, the marker is a fixed bottom-right overlay above 640 CSS pixels and participates in normal document flow at widths up to and including 640 CSS pixels. The host owns the viewport metadata, render location, outer spacing, and any containing layout; render the marker after persistent application chrome and before main content so the narrow-screen marker reserves space instead of covering that content.
Render
string Render(HttpContext httpContext, IHostEnvironment environment, IOptions<AppSurfaceDevAuthOptions> options, IDataProtectionProvider dataProtectionProvider, Action<AppSurfaceDevAuthMarkerOptions>? configure = null)
Source
Renders a local DevAuth marker using the current request state.
Parameters
httpContextCurrent HTTP context, used to read the protected persona cookie and build return URLs.environmentHost environment used for marker status.optionsConfigured DevAuth options.dataProtectionProviderData protection provider used to read the selected persona cookie.configureOptional marker rendering customization.
Returns
HTML that can be embedded in a host page, or an empty string when the current environment is not allowed. With default styles, the returned marker is fixed above 640 CSS pixels and in flow at 640 CSS pixels or below.
AppSurfaceDevAuthException
SourceException thrown when AppSurface DevAuth detects unsafe or invalid development-auth configuration.
DiagnosticCode
string DiagnosticCode { get; }
Source
Gets the stable AppSurface DevAuth diagnostic code.
AppSurfaceDevAuthOptions
SourceOptions for AppSurface Development-by-default authentication with explicit local/proof environment opt-in.
Users
AppSurfaceDevAuthPersonaCollection Users { get; }
Source
Gets the seeded local-development personas.
SchemeName
string SchemeName { get; set; }
Source
Gets or sets the authentication scheme registered for DevAuth.
PathPrefix
string PathPrefix { get; set; }
Source
Gets or sets the local-only path prefix for the control page and status endpoints.
CookieName
string CookieName { get; set; }
Source
Gets or sets the cookie name that stores the selected local persona id.
UseAsDefaultSchemeForLocalProof
bool UseAsDefaultSchemeForLocalProof { get; set; }
Source
Gets or sets a value indicating whether DevAuth may become the default scheme for local proof apps.
Remarks
Leave this disabled for package consumers that already have real authentication. Enable it only in throwaway local proof hosts where DevAuth is intentionally the whole authentication stack.
AllowDevAuthOverrideForLocalProof
bool AllowDevAuthOverrideForLocalProof { get; set; }
Source
Gets or sets a value indicating whether DevAuth may coexist with other registered authentication schemes.
Remarks
This is a loud local-only override for demos that intentionally compose real and fake schemes. It must not be used to hide production authentication conflicts.
RequireLoopbackControlRequests
bool RequireLoopbackControlRequests { get; set; }
Source
Gets or sets a value indicating whether control endpoints reject non-loopback requests.
AllowedEnvironmentNames
ISet<string> AllowedEnvironmentNames { get; }
Source
Gets environment names where DevAuth is allowed to activate.
Remarks
The set defaults to Environments.Development and compares names case-insensitively. DevAuth trims names when checking the active host environment. Add only local or proof environments that should expose fake personas; this allow-list is activation policy for fake auth, not a production safety boundary.
DisplayClaimTypes
ISet<string> DisplayClaimTypes { get; }
Source
Gets claim types that may appear in the local-only control page claims preview.
Remarks
The authentication handler still issues every seeded persona claim. This allowlist affects only the HTML preview. Sensitive claim names such as tokens, secrets, passwords, keys, and emails are never rendered even when added here.
AppSurfaceDevAuthUserBuilder
SourceBuilds a seeded local-development persona for AppSurface DevAuth.
DisplayName
AppSurfaceDevAuthUserBuilder DisplayName(string displayName)
Source
Sets the display name shown on the DevAuth control page.
Parameters
displayNameNon-blank display name.
Returns
The same builder for chaining.
Subject
AppSurfaceDevAuthUserBuilder Subject(string subject, string claimType = AppSurfaceDevAuthDefaults.SubjectClaimType)
Source
Sets the stable subject claim for the local persona.
Parameters
subjectNon-blank subject value.claimTypeNon-blank subject claim type. Defaults tosub.
Returns
The same builder for chaining.
Claim
AppSurfaceDevAuthUserBuilder Claim(string type, string value)
Source
Adds a safe local-development claim to the persona.
Parameters
typeNon-blank claim type.valueNon-blank claim value.
Returns
The same builder for chaining.
Remarks
Claims added here are local test inputs. They are not durable identity, tenant authority, or permission truth. Keep secrets, tokens, passwords, raw emails, and production identity payloads out of DevAuth personas.
Build
AppSurfaceDevAuthPersona Build()
Source
Builds the immutable persona that will be stored in AppSurfaceDevAuthOptions.Users.
Returns
A persona with a default display name of the persona id when no display name was supplied.
Remarks
The configured subject claim is prepended when Subject(string, string) was called. Any previously added claim with the same subject claim type is replaced so the persona has one stable subject value. Registration validation rejects personas that were built without an explicit subject.
NormalizePersonaId
string NormalizePersonaId(string id)
Source
Validates and returns a route-safe local persona id.
Parameters
idCandidate persona id, such asadmin,viewer, orqa.local_1.
Returns
The original id when it is safe for route values and local cookie payloads.
Exceptions
AppSurfaceDevAuthExceptionThrown withASDEV006when the id is blank, a URI dot segment, contains unsupported characters, or includes a sensitive-looking token segment such assecret,token,key, oremail.
Remarks
Use this before accepting route-supplied persona ids. The validation is intentionally strict because persona ids are visible in the local selection URL and are the only payload stored in the protected persona cookie.
Id
string Id { get; }
Source
Gets the local persona id.
AppSurfaceDevAuthEnvironmentPolicy
SourceCentralizes DevAuth environment activation checks.
IsEnvironmentAllowed
bool IsEnvironmentAllowed(IHostEnvironment environment, AppSurfaceDevAuthOptions options)
Source
Determines whether DevAuth may activate in the current host environment.
Parameters
environmentHost environment to check.optionsMaterialized DevAuth options containing allowed environment names.
Returns
true when the environment name is in the DevAuth activation allow-list.
ValidateAllowedEnvironmentNames
void ValidateAllowedEnvironmentNames(AppSurfaceDevAuthOptions options)
Source
Validates the configured DevAuth activation allow-list.
Parameters
optionsMaterialized DevAuth options to validate.
Exceptions
ArgumentExceptionThrown when the allow-list is empty or contains blank names.
FormatAllowedEnvironmentNames
string FormatAllowedEnvironmentNames(AppSurfaceDevAuthOptions options)
Source
Formats configured allowed environment names for safe diagnostics.
Parameters
optionsMaterialized DevAuth options to inspect.
Returns
A comma-separated, display-safe list of configured environment names.
AppSurfaceDevAuthStaticExportMarkers
SourceDefines DevAuth marker tokens that static exporters must treat as private development-auth evidence.
Remarks
DevAuth renders these tokens only on local development surfaces. Static export auditors consume the same constants so marker renames are compiler-checked across the renderer and artifact-audit boundary.
AppSurfaceDevAuthMarkerOptions
SourceControls how the AppSurface DevAuth marker renders inside a local or proof host page.
Remarks
The marker is an explicit opt-in snippet for pages where fake auth state should be visible. It never injects itself into host HTML. Consumers can disable the default inline styles and provide their own classes when the marker needs to match a local design system. The default styles use a fixed desktop overlay above 640 CSS pixels and normal document flow at widths up to and including 640 CSS pixels. The host remains responsible for viewport metadata, render location, outer spacing, containing layout, and any CSS overrides.
CssClassPrefix
string CssClassPrefix { get; set; }
Source
Gets or sets the CSS class prefix used for every marker element.
Remarks
The prefix replaces every package-emitted marker selector, including descendant selectors in the default inline styles. Changing it does not disable the package's responsive behavior. Use the new prefix for host overrides, or set IncludeDefaultStyles to false when the host will provide the complete skin.
AdditionalCssClass
string? AdditionalCssClass { get; set; }
Source
Gets or sets an extra CSS class appended to the marker root element.
Remarks
Use this host-owned class for outer spacing or a deliberate placement override. Package styles are emitted with the configured CssClassPrefix, so placement overrides may need higher specificity or later source order. The host owns overlap prevention whenever it overrides the package placement rules.
IncludeDefaultStyles
bool IncludeDefaultStyles { get; set; }
Source
Gets or sets a value indicating whether the marker includes package-provided default styles.
Remarks
When enabled, the package renders a fixed bottom-right overlay above 640 CSS pixels and an in-flow marker at widths up to and including 640 CSS pixels. Set this to false when the host wants to own all marker styling and responsive placement. The host must supply its own styles in that case.
ShowPersonaControls
bool ShowPersonaControls { get; set; }
Source
Gets or sets a value indicating whether persona select and clear controls are rendered in the marker.
Remarks
When enabled, controls use POST-only DevAuth endpoints and include a safe local return URL so the browser returns to the host page after changing personas.
StartExpanded
bool StartExpanded { get; set; }
Source
Gets or sets a value indicating whether the marker starts expanded.
Remarks
The default is collapsed so the DevAuth state remains visible with a smaller desktop footprint. Set this to true when a proof page should show the persona controls immediately. At narrow widths the default-styled expanded marker remains in normal flow and pushes following content instead of overlaying it.
ReturnUrl
string? ReturnUrl { get; set; }
Source
Gets or sets the local URL to return to after a marker persona mutation.
Remarks
Leave this unset to return to the current request path and query. The marker normalizes blank, non-rooted, external, protocol-relative, backslash-containing, and control-character values to the site root before constructing its mutation actions.
AppSurfaceDevAuthDefaults
SourceDefines default names and paths for AppSurface development authentication.
AppSurfaceDevAuthServiceCollectionExtensions
SourceRegisters AppSurface Development-by-default authentication for ASP.NET Core hosts with explicit local/proof environment opt-in.
AddAppSurfaceDevAuth
IServiceCollection AddAppSurfaceDevAuth(this IServiceCollection services, IHostEnvironment environment, Action<AppSurfaceDevAuthOptions> configure)
Source
Adds the AppSurface DevAuth named authentication scheme and startup safety validation.
Parameters
servicesService collection that receives DevAuth registrations.environmentHost environment used to enforce the DevAuth activation allow-list.configureCallback that configures seeded local personas and DevAuth options once during registration.
Returns
The same service collection for chaining.
Exceptions
ArgumentExceptionThrown when required option values are blank orAppSurfaceDevAuthOptions.AllowedEnvironmentNamesis empty or contains blank names.AppSurfaceDevAuthExceptionThrown when DevAuth is enabled in an environment that is not allowed or another DevAuth safety diagnostic fails.
Remarks
DevAuth is fake local authentication. It registers a normal ASP.NET Core authentication handler, but it must not be used as a production identity provider, user store, OIDC replacement, or durable app-user mapping layer. DevAuth activates only when the trimmed host environment name matches AppSurfaceDevAuthOptions.AllowedEnvironmentNames case-insensitively. The default allow-list contains Development; add proof environments only for intentional local/proof hosts.
CreateNonDevelopmentException
AppSurfaceDevAuthException CreateNonDevelopmentException(string environmentName, AppSurfaceDevAuthOptions options)
Source
Creates the stable AppSurfaceDevAuthDiagnostics.NonDevelopmentEnvironment exception.
Parameters
environmentNameHost environment name used only in the safe diagnostic message. Blank values are rendered as(unknown).optionsMaterialized DevAuth options used to format the allowed environment names.
Returns
An exception that tells consumers to run DevAuth only in an allowed proof environment or remove it.
ValidateOptions
void ValidateOptions(AppSurfaceDevAuthOptions options)
Source
Validates the materialized DevAuth options before endpoint mapping and startup safety checks run.
Parameters
optionsOptions instance populated once by the consumer registration callback.
Exceptions
ArgumentExceptionThrown whenAppSurfaceDevAuthOptions.SchemeName,AppSurfaceDevAuthOptions.PathPrefix, orAppSurfaceDevAuthOptions.CookieNameis blank, or whenAppSurfaceDevAuthOptions.AllowedEnvironmentNamesis empty or contains blank names.AppSurfaceDevAuthExceptionThrown withASDEV003when no personas are configured,ASDEV004when a persona lacks its configured subject claim, orASDEV005when the path prefix is not an absolute path without a trailing slash.
IsMissingSubjectClaim
bool IsMissingSubjectClaim(AppSurfaceDevAuthPersona persona)
Source
Determines whether a seeded persona is missing the non-blank subject claim required by Auth.AspNetCore mapping.
Parameters
personaPersona to inspect after it has been built from the local seed callback.
Returns
true when the persona lacks its configured subject claim.
AppSurfaceDevAuthSensitiveValue
SourceDetects sensitive-looking local persona ids and preview values without rejecting innocent words such as monkey or mailbox.
Remarks
DevAuth diagnostics and control pages must not render obvious secrets, tokens, passwords, keys, credentials, or email-shaped values. This helper treats separators, PascalCase, and camelCase as token boundaries so names such as apiKey, passwordHash, access_token, and secret-token are hidden.
ContainsSensitiveToken
bool ContainsSensitiveToken(string value)
Source
Determines whether a value looks too sensitive to expose in DevAuth diagnostics or route-visible persona ids.
Parameters
valueCandidate local value, claim type, claim value, display name, subject, or persona id.
Returns
true when the value contains an email marker or sensitive word boundary.