Getting Started
Configuration
Reference for AuthEndpointsOptions and nested passkey, JWT, and email confirmation settings.
Configure the facade via AddAuthEndpoints<TUser, TContext>(…) or, with roles, AddAuthEndpoints<TUser, TRole, TContext>(…).
AuthEndpointsOptions
| Property | Default | Description |
|---|---|---|
IdentityPath | /identity | Route prefix for Identity management plus the configured sign-in stack |
SignIn | Cookie | AuthEndpointsSignIn.Cookie or IdentityBearer. Pass IdentityBearer as the first argument to AddAuthEndpoints, or set o.SignIn. |
PasskeyPath | /account | Route prefix for passkey endpoints |
RequireConfirmedAccount | true | Identity requires a confirmed account before sign-in |
Passkeys | (enabled) | Nested passkey options |
EmailConfirmation | (unset) | Nested email confirmation |
Jwt | (disabled) | Nested JWT options |
ConfigureIdentity | null | Optional Action<IdentityOptions> applied after secure defaults |
ConfigurePasskeys | null | Optional Action<IdentityPasskeyOptions> after ServerDomain is applied |
RequireEmailSenderInProduction | true | Production must register a real IEmailSender<TUser> (not Identity's no-op) |
Passkeys
AuthEndpointsPasskeyOptions:
| Property | Default | Description |
|---|---|---|
Enabled | true | When false, passkey DI and mapping are skipped |
ServerDomain | null | WebAuthn relying-party domain (e.g. example.com). Required in Production when enabled |
Email confirmation
AuthEndpointsEmailConfirmationOptions:
| 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 at request time. Production also fails options validation.
- Absolute
http://is refused unless the host is Development. Production fails options validation forhttp://.
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.
SPA signup that stays logged out until confirm: Register a confirmed account.
JWT
AuthEndpointsJwtOptions:
| Property | Default | Description |
|---|---|---|
Enabled | false | When true, registers and maps JWT endpoints |
Path | /auth | Route prefix for JWT endpoints |
Configure | null | Optional Action<SimpleJwtOptions> for issuer, audience, signing, lifetimes |
SimpleJwtOptions (via Jwt.Configure)
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 |
When JWT is enabled, call modelBuilder.UseRefreshToken() on your DbContext and migrate.
Example
builder.Services.AddAuthEndpoints<AppUser, AppDbContext>(o =>
{
o.IdentityPath = "/auth/cookie";
o.PasskeyPath = "/auth/passkey";
o.RequireConfirmedAccount = true;
o.Passkeys.ServerDomain = "example.com";
o.ConfigureIdentity = identity =>
{
identity.Password.RequiredLength = 10;
};
o.Jwt.Enabled = true;
o.Jwt.Path = "/auth/jwt";
o.Jwt.Configure = jwt =>
{
jwt.Issuer = "https://example.com";
jwt.Audience = "https://example.com";
jwt.SigningOptions.SymmetricKey = builder.Configuration["Jwt:SymmetricKey"];
};
});
For advanced stacks that skip the facade, see Composable endpoint requirements.