Upgrade to 4.0Changelog
Reference

Configuration options

Reference for PasswordAuthOptions and the module options that a password-facade or composed host sets.

AddPasswordAuth<TUser, TContext>(…) takes PasswordAuthOptions. The modules it registers read their own options: SimpleJwtOptions, AuthEndpointsReAuthOptions, and, on a composed host, EmailCodeOptions and the email-confirmation redirect.

PasswordAuthOptions

AddPasswordAuth / MapPasswordAuth. One session. The building-block expansion is on Password auth. Routes are in the composition table.

PropertyDefaultDescription
SessionCookieAuthEndpointsSession.Cookie or Jwt. IdentityBearer fails validation.
Path/authRooted prefix for every mapped route
RequireConfirmedAccounttrueApplied before ConfigureIdentity
Passkeys(off until a domain is set)ServerDomain. A non-empty, non-whitespace value maps passkey sign-in and management
EmailConfirmation(unset)ConfirmEmailRedirectUri and AllowedRedirectOrigins, copied onto AuthEndpointsOptions
JwtnullRequired Action<SimpleJwtOptions> when Session is Jwt
ConfigureIdentitynullOptional Action<IdentityOptions> after RequireConfirmedAccount
RequireEmailSenderInProductiontrueProduction must register a real IEmailSender<TUser>

SimpleJwtOptions.RefreshTokenTransport defaults to Cookie. AddJwtEndpoints copies it onto JwtSessionOptions only when the value is not Cookie. AddPasswordAuth calls AddJwtEndpoints when Session is Jwt. A Configure<JwtSessionOptions> registered after that call replaces the result. An earlier configure stays when the JWT options leave transport at Cookie.

Session, Path, and Passkeys.ServerDomain are fixed by AddPasswordAuth. MapPasswordAuth maps that snapshot. A later Configure<PasswordAuthOptions> that changes them fails validation. EmailConfirmation can still be set later.

Passkeys

PasswordAuthOptions.Passkeys:

PropertyDefaultDescription
ServerDomainnullWebAuthn relying-party domain (e.g. example.com). A non-whitespace value maps passkey sign-in and management under Path. Unset leaves passkeys unmapped. An empty or whitespace value leaves them unmapped and fails validation in Production.

AddPasswordAuth copies ServerDomain onto IdentityPasskeyOptions. A composed host that calls AddPasskeyEndpoints<TUser>() sets IdentityPasskeyOptions.ServerDomain with Configure<IdentityPasskeyOptions>.

Passkey ceremonies require an antiforgery token for a cookie session and for JWT cookie refresh. With Session set to Jwt and body refresh transport, the password facade maps no GET /csrfToken and those ceremonies do not require a token. See Passkeys with JWT body transport.

Email confirmation

PasswordAuthOptions.EmailConfirmation on the password facade. AddPasswordAuth copies both values onto AuthEndpointsOptions.EmailConfirmation, which the confirm-email handler reads. A composed host sets that object with Configure<AuthEndpointsOptions>.

PropertyDefaultDescription
ConfirmEmailRedirectUrinullAfter browser GET confirm-email, redirect here instead of the plain-text / 401 response. Absolute https:// (or http:// in Development), or a rooted path such as /auth/email-confirmed.
AllowedRedirectOriginsemptyOrigins such as https://app.example.com required when the redirect URI is absolute. A rooted path does not need an entry.

URI rules:

  • Protocol-relative (//…) and non-http(s) schemes are rejected.
  • A rooted path is resolved against the request public origin (scheme://host, including port). PathBase is not included.
  • An absolute URI must match an allowlist entry on scheme, host, and optional port (origin only).
  • Absolute URI plus an empty allowlist is refused.
  • Absolute http:// is refused unless the host is Development.

On the password facade, startup validation also checks the value:

  • A protocol-relative URI or a non-http(s) scheme fails startup in every environment.
  • In Production, an absolute http:// URI, an absolute URI with an empty allowlist, and an absolute URI whose origin is not on the allowlist fail startup.

A composed host has no startup check. The confirm-email handler checks the redirect on each request. When the value is refused, confirm-email does not redirect. Success returns 200 with plain text, and failure returns 401.

Every redirect overwrites (does not append) these query parameters:

NameValues
statusconfirmed or failed
flowconfirm when changedEmail is absent; change-email when it is present

The redirect query does not include tokens, user ids, or emails.

Client steps for sign-up with email confirmation: Register users.

JWT

PasswordAuthOptions.Jwt is an Action<SimpleJwtOptions>. It is required when Session is Jwt. A composed host passes the same callback to AddJwtEndpoints<TUser, TContext>(…).

SimpleJwtOptions

Common settings:

PropertyNotes
Issuer / AudienceProduction rejects the library defaults (Jwt / JwtAudience)
AccessTokenLifetimeDefault 15 minutes
SigningOptionsSymmetric (key ≥ 32 UTF-8 bytes), RSA, ECDSA, or X509
TokenValidationParametersOptional override of validation parameters

With a JWT session, call modelBuilder.UseRefreshToken() on your DbContext and migrate.

Email code

The password facade does not map email-code sign-in. A composed host calls AddEmailCodeEndpoints<TUser, TContext>(options => …) with EmailCodeOptions.

EmailCodeOptions defaults and validation are in the Email-code module. AllowSignUp and MagicLink.Enabled default to false. ReAuth defaults to enabled and 5 minutes, and the proof is offered only when the user has no password, authenticator, or passkey. Call modelBuilder.UseEmailCodes() and add a migration before deploying.

To finish verify in a JWT, call AddJwtEndpoints and pass AuthEndpointsSession.Jwt to MapEmailCodeEndpoints.

ReAuth

AuthEndpointsReAuthOptions:

PropertyDefaultDescription
Lifetime5 minutesCookie ExpireTimeSpan, ticket ExpiresUtc, and header reauthToken expiry for the same confirm. Non-persistent (IsPersistent = false). No sliding expiration.

Startup validation rejects <= 0, InfiniteTimeSpan, values under 1 minute, and values over 60 minutes.

The password facade and a composed host configure the same type:

builder.Services.Configure<AuthEndpointsReAuthOptions>(o =>
{
    o.Lifetime = TimeSpan.FromMinutes(2);
});

Example

builder.Services.AddPasswordAuth<AppUser, AppDbContext>(o =>
{
    o.Session = AuthEndpointsSession.Jwt;
    o.Path = "/api/auth";
    o.RequireConfirmedAccount = true;
    o.EmailConfirmation.ConfirmEmailRedirectUri = "/email-confirmed";
    o.ConfigureIdentity = identity =>
    {
        identity.Password.RequiredLength = 10;
    };
    o.Jwt = jwt =>
    {
        jwt.Issuer = "https://example.com";
        jwt.Audience = "https://example.com";
        jwt.SigningOptions.SymmetricKey = builder.Configuration["Jwt:SymmetricKey"];
    };
});
builder.Services.Configure<AuthEndpointsReAuthOptions>(o =>
{
    o.Lifetime = TimeSpan.FromMinutes(2);
});

For stacks that skip the password facade, see Composition rules.