Requirements
Misconfigured composition is the most common integration issue. Follow these rules when you skip the facade (or when you extend it).
1. DI must match maps
| You map… | You must register… |
|---|---|
MapIdentityManagementApi | Identity API endpoints + EF stores + token providers (as with AddIdentityApiEndpoints / facade) |
MapCookieAuthEndpoints | AddCookieAuthEndpoints() (+ antiforgery) |
MapBearerAuthEndpoints | AddBearerAuthEndpoints() |
MapJwtAuthEndpoints | AddJwtEndpoints<TUser, TContext>(…) and UseRefreshToken() on the DbContext |
MapPasskeyEndpoints | AddPasskeyEndpoints() |
| CSRF-protected routes | AddAntiforgery() |
Cookie and bearer helpers also register ReAuth schemes and rate-limit policies used by login/account flows.
2. Pipeline order
app.UseAuthentication();
app.UseAuthorization();
app.UseRateLimiter();
app.UseAntiforgery();
The facade equivalent is a single call:
app.UseAuthEndpoints();
Without rate limiting and antiforgery middleware, endpoint policies and CSRF filters will not behave correctly.
3. Map management once
In production hosts, map MapIdentityManagementApi once.
If you intentionally map management on two groups (for example cookie + bearer test hosts), pass a unique confirmEmailEndpointName for the second map so email confirmation link generation stays unambiguous.
4. Antiforgery rules
- Cookie and other CSRF-sensitive endpoints use
RequireAntiforgery()(endpoint filter). - Bearer JWT / Identity bearer: the filter skips CSRF when the request is authenticated via bearer schemes and not the application/external cookie.
- Clients:
GET …/csrfToken→ sendRequestVerificationTokenon unsafe methods. - Optional host middleware:
AntiforgeryEnforcementMiddleware(the Demo sample uses it; filter-only is enough for mapped endpoints).
5. Rate-limit policies
Policies are registered by cookie/bearer/JWT/passkey DI helpers:
| Policy constant | Typical use |
|---|---|
AuthEndpoints.Login | Login / token create / refresh (token bucket: 10 tokens, +2 / 10s per IP) |
AuthEndpoints.AccountAbuse | Account abuse–sensitive actions (10 / minute per IP) |
AuthEndpoints.ConfirmIdentity | ReAuth confirm (20 / minute per IP) |
AuthEndpoints.Passkey.ObtainOptions | Passkey options (5 / minute per IP) |
AuthEndpoints.Passkey.Register | Passkey register (3 / minute per IP) |
Ensure UseRateLimiter() runs in the pipeline.
6. ReAuth for sensitive mutations
Manage 2FA/info mutations and passkey add/rename/delete/creationOptions require step-up ReAuth (plus antiforgery where applicable).
Hosts can protect their own endpoints with .RequireReauth() after registering ReAuth schemes. See ReAuth.