Upgrade to 4.0Changelog
Concepts

Security model

How AuthEndpoints hides which accounts exist, finishes each sign-in in a session, protects account changes, and which trade-offs it leaves to the host.

AuthEndpoints adds protection in layers on top of ASP.NET Core Identity. This page explains what each layer covers, and where the library makes a trade-off that you should know about.

Responses do not reveal which accounts exist

An attacker who can tell whether an email is registered can target that account. AuthEndpoints returns the same answer whether or not an account exists. The behaviour is always on. There is no option to turn it off.

These routes answer an email that has an account and an email that does not with the same status, the same body shape, and the same headers:

RouteSame responseUnknown-account work
POST /registerEmpty 200Notifies the owner when the email already has an account
POST /forgotPasswordEmpty 200Issues a password-reset token only when the account exists and the email is confirmed
POST /resendConfirmationEmailThe signed-in user's resend resultThe body email is ignored
POST /emailCode/send200 with expiresInSeconds and resendAfterSecondsIssues a code only when the account can receive one
POST /passkeys/register/options200 optionsBuilds creation options

Other routes give one answer for every failure:

  • POST /auth/resetPassword returns InvalidToken for an unknown email, an unconfirmed email, and a bad code alike.
  • Login returns Invalid credentials. for a wrong password, a lockout, and an unconfirmed email.
  • POST /auth/emailCode/send returns the same { "expiresInSeconds", "resendAfterSeconds" } body when the address is unknown, the account is locked or ineligible, the cooldown or per-address cap applies, or the sender throws. POST /auth/emailCode/verify returns Invalid or expired code. for a wrong code, a wrong token, an expired or used code, a lockout, and a failed sign-up.

POST /register does not return DuplicateUserName or DuplicateEmail. A valid password for an existing email does not create a second account. 4.0 sends IAccountSecurityEmailSender<TUser>.SendRegistrationAttemptedAsync to that owner. The attempted password is not in the message. AddPasswordSignUpEndpoints, AddAccountManagementEndpoints, and AddJwtEndpoints register LoggingAccountSecurityEmailSender<TUser> when no sender is registered. That default logs the attempt and does not send mail. Register an implementation to deliver it. Startup logs a warning while the logging sender is still the registration.

Invalid email and password-rule failures stay 400. Those bodies match whether or not the email is registered.

The unknown-account branch runs the same class of work as the account branch, so the two requests take a similar amount of time. Queue confirmation, reset, and registration-attempt mail and return from the sender. A sender that waits on SMTP makes a known address slower than an unknown one.

POST /resendConfirmationEmail still resends for the signed-in user. An anonymous caller cannot use it to ask whether an address is registered.

Clients keep one check-your-email screen for a new registration and a taken email.

Two cases reveal an account. The final passkey register step still reveals a taken email once a valid attestation has been made. POST /passkeys/register/options returns the same options for a known email and an unknown email. POST /passkeys/register checks the email only after attestation succeeds. A taken email then returns 400 with detail Unable to complete registration. A new email continues and creates the user. The same detail is also used for a failed attestation.

The second case is deliberate. Identifier-first passkey sign-in (requestOptions with an email) can reveal through allowCredentials that an account has passkeys. Omit the email to use discoverable credentials and avoid that.

The session matches the client

A cookie is the smaller attack surface for a browser on the same site as the API. JavaScript cannot read an HttpOnly cookie, so a script bug cannot copy the session out. The cost is CSRF. The browser sends the cookie on every request, including a request that another site starts. AuthEndpoints checks an antiforgery token on the routes that change state.

JWT fits a browser that must send a bearer token to a second API. The access token stays in memory. The refresh token stays in an HttpOnly SameSite=Strict cookie, stored as a hash, and rotated on each use. Reuse of an old refresh token revokes the family. The host adds a migration and sets the signing key, the issuer, and the audience.

A native app has no browser cookie jar and no cross-site request that attaches a cookie on its own. Identity bearer returns the access token and the refresh token in the body. Logout on that stack does not revoke those tokens. They stay valid until they expire. JWT with RefreshTokenTransport.Body is the other native choice. Logout then revokes the refresh family.

Passkeys and GitHub or Google finish into one of those sessions. They do not replace the session. Both skip two-factor authentication. The decision table is on Choose your sign-in setup.

Sign-in completers write the session

A sign-in method checks the proof. The completer writes the session after that check succeeds. Failures never call it.

AuthEndpointsSession selects a built-in completer:

SessionNameRegistered byResult
CookieSignInCompleters.CookieAddAuthEndpointsIdentity, AddPasswordEndpoints, or AddEmailCodeEndpointsApplication cookie. Passkey register returns { credentialId }.
IdentityBearerSignInCompleters.IdentityBearersameIdentity bearer body, or an application cookie when useCookies or useSessionCookies is set. Passkey register returns the token body and does not add credentialId.
JwtSignInCompleters.JwtAddJwtEndpointsaccessToken and tokenType. Refresh cookie AuthEndpoints.Jwt.RefreshToken, or refreshToken in the body when transport is Body. Passkey register does not add credentialId.
identity.MapPasswordEndpoints<AppUser>(AuthEndpointsSession.Jwt);
identity.MapEmailCodeEndpoints<AppUser>(AuthEndpointsSession.IdentityBearer);
account.MapPasskeySignInEndpoints<AppUser>(AuthEndpointsSession.Jwt);
external.MapExternalAuthEndpoints<AppUser>(AuthEndpointsSession.Cookie);

MapPasskeySignInEndpoints<TUser>(string?) is still the confirm-email endpoint name. MapPasskeySignInEndpoints<AppUser>("MySession") does not select a completer. When that string matches a registered completer name, map time logs a warning on the AuthEndpoints category and still uses the default completer. Pass the session enum, or pass the completer name and the confirm-email name: MapPasskeySignInEndpoints<AppUser>(SignInCompleters.Jwt, confirmEmailEndpointName: null).

PasskeySignInKind and PasswordLoginMode stay. With no session and no completer argument, email-code verify and passkey register and login keep the Identity bearer completer. Parameterless password login uses the cookie completer. An explicit PasswordLoginMode stays on PasswordSignInAsync. MapCookieAuthEndpoints, MapBearerAuthEndpoints, MapIdentityManagementApi, and MapPasskeyEndpoints keep that choice.

SignInCompletionOptions.Default applies when MapPasswordEndpoints(), MapPasswordSignInEndpoints(), MapEmailCodeEndpoints, or MapPasskeySignInEndpoints is called with no session and no completer name. When Default is unset, those password maps use the Cookie completer. An explicit PasswordLoginMode beats Default and keeps that handler (Cookie, IdentityBearer, or None).

Custom completer

builder.Services.AddSignInCompleter<AppUser, MySignInCompleter>("MySession");
builder.Services.Configure<SignInCompletionOptions>(options => options.Default = "MySession");

Or pass "MySession" to the sign-in map. A name passed to the map wins over an explicitly registered per-method completer. That registration wins over SignInCompletionOptions.Default when the map passes no name. Calling AddSignInCompleter again for the same user and name replaces that registration. The name is checked for the user type being mapped. A completer registered for another user fails at map time. The built-in Cookie, IdentityBearer, and Jwt names apply to every user type.

SignInCompletionContext.UsedTwoFactor is true when password sign-in presented a valid authenticator or recovery code in this request. Cookie and Identity bearer completers add an amr claim of mfa when it is set, and pwd otherwise. A remembered two-factor client stays pwd.

External callbacks use SignInMethod.External. There is no two-factor step. MapExternalAuthEndpoints<TUser>() and MapExternalAuthProvider with no session use the Cookie completer unless SignInCompletionOptions.Default names one. An explicit AddCompleter<T>() still wins over that default. A session or completer argument wins over AddCompleter. AuthEndpointsSession.Jwt writes the refresh cookie and redirects. The access token is not in the URL. That session with RefreshTokenTransport.Body throws at map time and does not create a refresh token. AddCompleter<JwtExternalLoginCompleter<TUser>>() with body transport fails startup validation.

The per-method completer interfaces are obsolete and removed in 5.0. An explicitly registered one still runs when the map passes no session and no completer. See Upgrade to 4.0.

Password login

MapPasswordEndpoints<TUser>() and MapPasswordSignInEndpoints<TUser>() call CheckPasswordSignInAsync, then the user manager's authenticator and recovery-code checks, then the completer. They do not call PasswordSignInAsync, TwoFactorAuthenticatorSignInAsync, or TwoFactorRecoveryCodeSignInAsync. With no SignInCompletionOptions.Default, the completer is Cookie.

A wrong recovery code counts toward lockout. TwoFactorRecoveryCodeSignInAsync does not. An unknown user name runs a password-hash verify with the host's IPasswordHasher<TUser>, so that request takes about as long as a wrong password.

A custom SignInManager<TUser> that overrides PasswordSignInAsync, TwoFactorAuthenticatorSignInAsync, or TwoFactorRecoveryCodeSignInAsync is not called by these maps. Override CheckPasswordSignInAsync or CanSignInAsync, or put sign-in side effects in a completer.

An explicit PasswordLoginMode uses the PasswordSignInAsync handlers and beats SignInCompletionOptions.Default. MapCookieAuthEndpoints and MapBearerAuthEndpoints do too.

A browser sends cookies on every request, including requests that another site starts. AuthEndpoints adds an antiforgery filter to every route that changes state for a signed-in cookie user, and to every anonymous passkey ceremony. The filter skips the check only when the request carries a non-empty Authorization: Bearer header, a scheme in AuthEndpointsAntiforgeryOptions.BearerSchemes (default: Identity bearer and JWT) authenticates that header, and the application cookie does not authenticate. RequireAntiforgery(allowBearer: false) keeps the check for every caller on a route. A token that a host reads from a cookie still needs a CSRF token when the Authorization header is absent. Login, register, forgot password, reset password, and both email-code routes have no check. They do not act on an existing session. See Antiforgery (CSRF) rules.

Rate limits and lockout slow guessing

Login routes share a token bucket per IP. Email-code verify uses that same bucket. Email-code send has its own fixed window per IP, plus a per-address cooldown and send cap that still return 200. Registration and password-reset routes share a fixed window per IP. Passkey options and passkey registration have tighter limits. Identity lockout is on for every password check (lockoutOnFailure: true), including the password proof in step-up. A wrong email code or wrong email-code second factor counts toward lockout when CountFailuresTowardLockout is true (the default) and a user exists. See Rate-limit policies.

Identity bearer POST /auth/refresh has no rate limit. A refresh token is a long random value, so guessing is not practical, but the route does accept unlimited attempts.

Step-up guards the changes that matter most

A stolen session should not be enough to take over an account. Changing the email, the password, the 2FA settings, or the passkeys requires a fresh ReAuth proof that expires after 5 minutes by default. Unlinking an external login requires one too. That proof sits on top of a sign-in and has to be for the same user. It does not sign anyone in by itself. The ReAuth cookie is SameSite=Strict and does not slide. See Require step-up before sensitive actions.

Two-factor is a password add-on

Password sign-in asks for a second factor when the user turned 2FA on. Email-code verify does too when RequireTwoFactor is true (the default): a missing TOTP or recovery code returns RequiresTwoFactor and does not consume the row. A recovery code is redeemed only after the row is consumed. If redeem fails, the consume is cleared and the attempt remains. Passkey sign-in and GitHub or Google sign-in do not ask for a 2FA code, even when the user turned 2FA on. The passkey completers and the OAuth completers sign the user in directly.

For passkeys, this is a reasonable default. A passkey is phishing-resistant and is usually unlocked with a device biometric or PIN, so it already combines two factors. For OAuth, the reasoning is weaker. The account is as strong as the user's GitHub or Google account, which may or may not use 2FA. If your threat model requires 2FA on every path, register a custom ISignInCompleter<TUser> with AddSignInCompleter that checks it, and pass its name to the passkey and external maps.

A related trade-off: a persistent cookie login with a valid authenticator code sets Identity's remember-client cookie. Later password logins from that browser skip 2FA until the user sends forgetMachine or logs out. Session logins and recovery-code logins never set it.

Email confirmation gates sign-in

RequireConfirmedAccount is true by default. Until a user confirms the email, password, passkey, and JWT sign-in all fail. This blocks an attacker from claiming an address they do not own.

Email-code verify can confirm an existing unconfirmed account. The default UnconfirmedAccounts value, ConfirmAndResetCredentials, removes a password, each external login, and each passkey, and updates the security stamp, before it confirms the email. If one of those removals fails, the email stays unconfirmed and verify returns 401. Reject returns 401 without confirming and without removing credentials. A user created with AllowSignUp is confirmed at creation and has no password.

The cost is that resend needs a session. POST /auth/resendConfirmationEmail requires a signed-in user, and an unconfirmed user cannot sign in. A user who loses the first email cannot get another one through AuthEndpoints today.

GitHub and Google accounts skip the confirmation email. EmailConfirmed comes from the provider's verified flag, and RequireVerifiedEmail refuses unverified emails by default.

Startup checks catch unsafe Production settings

In Production, startup fails when the host has no real email sender, no passkey domain, or the default JWT issuer or audience. Outside Development, email-code startup fails when no real IEmailCodeSender<TUser> is registered and RequireSenderOutsideDevelopment is true. A magic-link LinkUri must be an absolute https URI with no # in Production, and its origin must be in AllowedOrigins. In every environment, startup fails for a missing or short symmetric JWT key and for an empty GitHub or Google client id or secret. See Prepare for production.

How it is verified

Every push to main, and every pull request to main or release/**, runs the test projects when it changes library code, tests, the solution file, or the test workflow. A pull request that only changes the docs skips those runs.

Count the tests with:

dotnet test AuthEndpoints.sln

GitHub CodeQL code scanning (default setup) analyzes pull requests and pushes to main.

The OpenSSF Scorecard workflow runs on pushes to main, every week, and when branch protection changes. It uploads its results to code scanning.

A published package includes build provenance. Verify the file you downloaded:

gh attestation verify <file>.nupkg -R madeyoga/AuthEndpoints

To report a vulnerability, follow SECURITY.md. Use GitHub private vulnerability reporting. Do not open a public issue.

What the host owns

AuthEndpoints does not configure HTTPS, CORS, or the security of the client. Serve the API over HTTPS. Allow credentials in CORS only for the exact origins you trust. Keep Identity bearer tokens in secure device storage.