Prepare for production

Work through this checklist before you deploy. Startup validation catches some items. The rest are your responsibility.

Check the core settings

• Serve the API over HTTPS.
• Register a real IEmailSender<TUser>. When RequireEmailSenderInProduction is true (the default), startup fails in Production while Identity's no-op sender is registered.
• On the password facade, set Passkeys.ServerDomain only when you want passkeys. Leave it unset to keep them off. A whitespace value fails startup in Production.
• On the 3.x facade, passkeys are on until Passkeys.Enabled is false. Production then requires Passkeys.ServerDomain.
• Leave RequireConfirmedAccount at true unless you have another way to verify email ownership.

Check the email-code settings

Skip this section if email-code sign-in is off.

• Call modelBuilder.UseEmailCodes() and apply the migration. MapEmailCodeEndpoints throws without that entity. The table is AuthEndpoints.AuthEndpointsEmailCodes.
• Register a real IEmailCodeSender<TUser>. IEmailSender<TUser> does not send the code. Outside Development, startup fails while DevelopmentEmailCodeSender<TUser> or no sender is registered, unless RequireSenderOutsideDevelopment is false.
• Queue the message and return. Send awaits SendSignInCodeAsync. Code and LinkUrl are raw. Encode them in an HTML template, and do not log them.
• If the magic link is on, set LinkUri to an absolute https URI with no #, and list that origin in MagicLink.AllowedOrigins.
• Leave AllowSignUp off unless an unknown address should become a confirmed user with no password.

Check the JWT settings

Skip this section if JWT is off.

• Call modelBuilder.UseRefreshToken() on your DbContext and apply the migration.
• Set an issuer and an audience. Startup fails in Production with the library defaults (Jwt and JwtAudience).
• Use a symmetric key of at least 256 bits (32 UTF-8 bytes), or an asymmetric key.
• If you upgrade from plaintext refresh-token storage, recreate the AuthEndpointsRefreshTokens table. AuthEndpoints now stores hashed tokens with reuse detection.

Check the external OAuth settings

Skip this section if you do not use GitHub or Google.

• Map the OAuth routes yourself. MapAuthEndpoints does not map them.
• Host a page at ErrorPath (default /auth/external/error).
• Leave AutoLinkByEmail off unless a verified provider email should attach to an existing confirmed account.
• Keep RequireVerifiedEmail on.

Check the browser setup

• If the client runs on another origin, add a CORS policy with credentials. See Call the API from a browser.
• Decide whether passkey and OAuth sign-in skipping 2FA fits your threat model. See Security model.

What the validators check

• AuthEndpointsOptionsValidator checks IdentityPath, PasskeyPath, and Jwt.Path formats, and the Production passkey domain.
• AuthEndpointsEmailSenderValidator checks the email sender in Production.
• EmailCodeSenderValidator<TUser> checks IEmailCodeSender<TUser> outside Development when email-code sign-in is registered and RequireSenderOutsideDevelopment is true.
• EmailCodeOptionsValidator checks code length, lifetime, attempts, cooldown, send caps, and the magic-link URI.
• JWT options validation rejects the default issuer and audience in Production, and checks the key material against the signing algorithm.
• AddGitHub and AddGoogle reject an empty ClientId or ClientSecret at startup.

Related

• Configuration options
• Email-code module
• JWT module
• Passkeys module
• Security model