Configuration options
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.
| Property | Default | Description |
|---|---|---|
Session | Cookie | AuthEndpointsSession.Cookie or Jwt. IdentityBearer fails validation. |
Path | /auth | Rooted prefix for every mapped route |
RequireConfirmedAccount | true | Applied 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 |
Jwt | null | Required Action<SimpleJwtOptions> when Session is Jwt |
ConfigureIdentity | null | Optional Action<IdentityOptions> after RequireConfirmedAccount |
RequireEmailSenderInProduction | true | Production 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:
| Property | Default | Description |
|---|---|---|
ServerDomain | null | WebAuthn 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>.
| Property | Default | Description |
|---|---|---|
ConfirmEmailRedirectUri | null | After 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. |
AllowedRedirectOrigins | empty | Origins 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).PathBaseis 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:
| Name | Values |
|---|---|
status | confirmed or failed |
flow | confirm 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:
| Property | Notes |
|---|---|
Issuer / Audience | Production rejects the library defaults (Jwt / JwtAudience) |
AccessTokenLifetime | Default 15 minutes |
SigningOptions | Symmetric (key ≥ 32 UTF-8 bytes), RSA, ECDSA, or X509 |
TokenValidationParameters | Optional 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:
| Property | Default | Description |
|---|---|---|
Lifetime | 5 minutes | Cookie 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.