Composition 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<TUser>() (registers default Identity completer) |
| 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
- Routes that change state for a cookie user use
RequireAntiforgery(), an endpoint filter. - The filter skips the check when a bearer scheme authenticated the request and no application or external cookie is present.
- Clients send the
RequestVerificationTokenheader. Get the token fromGET …/csrfToken. AntiforgeryEnforcementMiddlewareis optional. The filter is enough for mapped endpoints.
The full route list and the failure shape are in Antiforgery (CSRF) rules.
5. Rate-limit policies
AddCookieAuthEndpoints, AddBearerAuthEndpoints, AddJwtEndpoints, and AddPasskeyEndpoints register the AuthEndpoints.Login, AuthEndpoints.AccountAbuse, and AuthEndpoints.ConfirmIdentity policies. AddPasskeyEndpoints also registers the two passkey policies. AddExternalAuthEndpoints registers AuthEndpoints.Login. Identity bearer POST /refresh has no rate limit.
Call UseRateLimiter() in the pipeline. Limits and routes per policy are in Rate-limit policies.
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.