string CssClassPrefix { get; set; }
Source
Gets or sets the CSS class prefix used for every marker element.
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.
AppSurfaceDevAuthMarkerOptions
SourceControls how the AppSurface DevAuth marker renders inside a local development host page.
Remarks
The marker is an explicit opt-in snippet for Development pages. 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.
CssClassPrefix
AdditionalCssClass
string? AdditionalCssClass { get; set; }
Source
Gets or sets an extra CSS class appended to the marker root element.
IncludeDefaultStyles
bool IncludeDefaultStyles { get; set; }
Source
Gets or sets a value indicating whether the marker includes package-provided default styles.
Remarks
Set this to false when the host wants to skin the marker entirely with its own CSS.
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.
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. External URLs, protocol-relative URLs, and backslash-prefixed URLs are ignored by the DevAuth endpoints.
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.
AppSurfaceDevAuthStartupValidator
SourcePerforms DevAuth startup validation after the host service provider has been built.
Remarks
Registration validates the caller-supplied Development 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 non-Development hosts 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 Development 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
AppSurfaceDevAuthExceptionThrown withASDEV001outside Development, with option diagnostics when materialized options are invalid, 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.
AppSurfaceDevAuthMarker
SourceRenders an explicit AppSurface DevAuth state marker for host pages.
Remarks
Use this helper from a Development-only page or layout when 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.
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.
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.
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.
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 and set no-store headers on every response.
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.
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.
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.
AppSurfaceDevAuthOptions
SourceOptions for AppSurface development-only authentication.
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.
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.
AppSurfaceDevAuthServiceCollectionExtensions
SourceRegisters AppSurface development-only authentication for ASP.NET Core hosts.
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 Development-only startup.configureCallback that configures seeded local personas and DevAuth options once during registration.
Returns
The same service collection for chaining.
Exceptions
AppSurfaceDevAuthExceptionThrown when DevAuth is enabled outside Development or the supplied options are invalid.
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.
CreateNonDevelopmentException
AppSurfaceDevAuthException CreateNonDevelopmentException(string environmentName)
Source
Creates the stable AppSurfaceDevAuthDiagnostics.NonDevelopmentEnvironment exception.
Parameters
environmentNameHost environment name used only in the safe diagnostic message. Blank values are rendered as(unknown).
Returns
An exception that tells consumers to run DevAuth only in Development 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.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.
AppSurfaceDevAuthDiagnostics
SourceStable AppSurface DevAuth diagnostic codes and safe metadata keys.
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
IReadOnlyDictionary<string, AppSurfaceDevAuthPersona> Personas { get; }
Source
Gets the configured local-development personas.
AppSurfaceDevAuthDefaults
SourceDefines default names and paths for AppSurface development authentication.