Build a custom auth stack
AuthEndpoints is a set of minimal API modules. The password facade is one composition of those modules. A custom host calls the same Add* and Map* pairs, on the prefixes it chooses.
Use AddPasswordAuth when the app is password sign-up, one session, and account management. Compose the building blocks when the app is email-code only, external-first, passkey-first, or more than one session. An app with no public sign-up is Run an app with no public sign-up.
MapIdentityApi maps one fixed set. The gaps are in AuthEndpoints compared with MapIdentityApi and other options.
The password facade is one fixed composition
The password facade is Password auth: AddPasswordAuth and MapPasswordAuth. It maps password sign-up, one session, recovery, and account management. The expansion on that page is the block list.
When to call the facade, and when to compose instead, is in Choose your sign-in setup.
What you compose
- Register the
Add*for each module you map. AMap*without itsAdd*throwsInvalidOperationException. The message names the method to call. A building-block pair saysCall {Add} before {Map}.MapPasswordAuthsaysAddPasswordAuth<TUser, TContext> was not called before MapPasswordAuth<TUser>.The other names are in Upgrade to 4.0. - Map per-session routes once for each session prefix. Password login, email-code verify, and passkey ceremonies finish in a sign-in completer, so they are per session.
- Map shared routes once. Sign-up, recovery, confirm-email, account management, and passkey management do not start a session.
- Put
UseAuthEndpointsin the pipeline so authentication, authorization, rate limiting, and antiforgery run.
The pairs, the routes, and the maps that contain each pair are in the composition table. That table is the route list.
MapSignInEndpoints maps the per-session routes whose Add* is registered, plus that session's logout and refresh routes. MapSharedAuthEndpoints maps the shared routes whose Add* is registered. Copy-paste hosts are in Copy a host.
Follow the composition rules
Misconfigured composition is the most common integration issue. Follow these rules when you skip the password facade or when you extend it.
Register the Add call for each Map call
| You map… | You must register… |
|---|---|
MapIdentityManagementApi | Identity (AddAuthEndpointsIdentity or AddIdentityApiEndpoints + EF stores + token providers) plus AddPasswordEndpoints and AddAccountManagementEndpoints |
MapPasswordEndpoints | AddPasswordEndpoints() |
MapConfirmEmailEndpoints | AddAccountAbuseRateLimiting() |
MapAccountManagementEndpoints | AddAccountManagementEndpoints() |
MapCookieAuthEndpoints | AddCookieAuthEndpoints() (password, cookie session, and account management) |
MapCookieSessionEndpoints | AddCookieSessionEndpoints() |
MapBearerAuthEndpoints | AddBearerAuthEndpoints() |
MapBearerSessionEndpoints | AddBearerSessionEndpoints() |
MapJwtAuthEndpoints, MapJwtPasswordEndpoints, MapJwtSessionEndpoints | AddJwtEndpoints<TUser, TContext>(…) and UseRefreshToken() on the DbContext. Session maps also need AddAntiforgery(). |
MapPasskeyEndpoints, MapPasskeySignInEndpoints, MapPasskeySignUpEndpoints, MapPasskeyManagementEndpoints | AddPasskeyEndpoints<TUser>(), or the matching AddPasskeySignInEndpoints, AddPasskeySignUpEndpoints, or AddPasskeyManagementEndpoints. MapPasskeySignInEndpoints still maps POST /passkeys/register. Login without that route is in Passkeys. |
| CSRF-protected routes | AddAntiforgery() |
AddPasswordEndpoints, AddCookieSessionEndpoints, and AddAccountManagementEndpoints register authorization and antiforgery. Account management also registers ReAuth schemes. Call each Add* before its map so the policies and schemes exist.
AddIdentityApiEndpoints leaves RequireConfirmedAccount at false. AddAuthEndpointsIdentity sets it to true, then runs your callback. Set SignIn.RequireConfirmedAccount yourself when you call AddIdentityApiEndpoints and unconfirmed sign-in should fail.Order the pipeline
app.UseAuthentication();
app.UseAuthorization();
app.UseRateLimiter();
app.UseAntiforgery();
UseAuthEndpoints is the same pipeline in one call:
app.UseAuthEndpoints();
Without rate limiting and antiforgery middleware, endpoint policies and CSRF filters will not behave correctly.
Map each confirm-email name once
Confirm-email is stored once per endpoint name for the app. MapConfirmEmailEndpoints, MapPasswordEndpoints, MapAccountManagementEndpoints, and MapPasskeySignInEndpoints share that registry. The default name is AuthEndpointsEndpointNames.ConfirmEmail<TUser>() (MapIdentityManagementApi-{TUser}-confirmEmail). A later map with the same name leaves the first GET /confirmEmail route in place.
Pass a different confirmEmailEndpointName when two groups should each expose confirm-email, for example a cookie group and a bearer group. MapPasskeyEndpoints does not map confirm-email. Passwordless register still builds its link from the name you pass, which defaults to AuthEndpointsEndpointNames.ConfirmEmail<TUser>().
Send the antiforgery token
Clients send the RequestVerificationToken header. Get the token from GET …/csrfToken. The routes, the skip rule, and the failure body are in Antiforgery (CSRF) rules.
Register the rate-limit policies
AddCookieAuthEndpoints, AddBearerAuthEndpoints, AddJwtEndpoints, and AddPasskeyEndpoints register the AuthEndpoints.Login, AuthEndpoints.AccountAbuse, and AuthEndpoints.ConfirmIdentity policies. AddPasswordEndpoints registers Login and AccountAbuse. AddAccountManagementEndpoints registers AccountAbuse and ConfirmIdentity. 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.
Require ReAuth for sensitive changes
Manage changes, passkey add, rename, delete, and creation options require step-up. Pair .RequireReauth() with a sign-in authorization. Schemes, the stamp check, and the cookie versus reauthToken split are in ReAuth. The steps are in Require step-up before sensitive actions.
Copy a host
Each code sample below is a complete Program.cs. The groups and the routes are in the composition table.
Email-code only
The account is created and signed in with an emailed code. This prefix does not map password register, login, forgot-password, or reset-password. POST /manage/password is mapped and returns 404, because password sign-in is not mapped.
using AuthEndpoints;
using AuthEndpoints.EmailCode;
using AuthEndpoints.Identity;
using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<AppDbContext>(options =>
options.UseSqlite("Data Source=app.db"));
builder.Services.AddAuthEndpointsIdentity<AppUser, AppDbContext>(options =>
{
options.User.RequireUniqueEmail = true;
});
builder.Services.AddCookieSessionEndpoints();
builder.Services.AddAccountManagementEndpoints();
builder.Services.AddEmailCodeEndpoints<AppUser, AppDbContext>(options =>
{
options.AllowSignUp = true;
});
builder.Services.AddTransient<IEmailCodeSender<AppUser>, QueuedEmailCodeSender>();
builder.Services.AddTransient<IEmailSender<AppUser>, QueuedIdentityEmailSender>();
var app = builder.Build();
app.UseAuthEndpoints();
var auth = app.MapGroup("/auth");
auth.MapEmailCodeEndpoints<AppUser>(AuthEndpointsSession.Cookie);
auth.MapCookieSessionEndpoints<AppUser>();
auth.MapAccountManagementEndpoints<AppUser>();
app.Run();
public class AppUser : IdentityUser { }
public class AppDbContext(DbContextOptions<AppDbContext> options) : IdentityDbContext<AppUser>(options)
{
protected override void OnModelCreating(ModelBuilder builder)
{
base.OnModelCreating(builder);
builder.UseEmailCodes();
}
}
public sealed class QueuedEmailCodeSender : IEmailCodeSender<AppUser>
{
public Task SendSignInCodeAsync(EmailCodeMessage<AppUser> message, CancellationToken cancellationToken = default)
=> Task.CompletedTask;
}
public sealed class QueuedIdentityEmailSender : IEmailSender<AppUser>
{
public Task SendConfirmationLinkAsync(AppUser user, string email, string confirmationLink)
=> Task.CompletedTask;
public Task SendPasswordResetLinkAsync(AppUser user, string email, string resetLink)
=> Task.CompletedTask;
public Task SendPasswordResetCodeAsync(AppUser user, string email, string resetCode)
=> Task.CompletedTask;
}
Call UseEmailCodes() and add the migration before production. Verify with ?useSessionCookies=true or ?useCookies=true when the client should get the application cookie. A verify call with neither flag returns an Identity bearer token.
POST /confirmIdentity/emailCode/send is on this map. That proof is offered only when the user has no password, no authenticator, and no passkey. An external login does not block it. After the user enables 2FA or adds a passkey, emailCode on GET /manage/authMethods becomes false and the send route returns 400 EmailCodeProofUnavailable.
Outside Development, register a real IEmailCodeSender<TUser>. Queue the message and return. IEmailSender<TUser> sends resend and a later email change. Email-code sign-up confirms the new address itself.
External-first
The user signs up with GitHub or Google, then adds a password. There is no password register route. POST /manage/password sets the first password after step-up. Password login and recovery are mapped so that password can be used afterwards. Unlink is allowed once a password exists.
using AuthEndpoints;
using AuthEndpoints.External.OAuth;
using AuthEndpoints.Identity;
using AuthEndpoints.OAuth.GitHub;
using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<AppDbContext>(options =>
options.UseSqlite("Data Source=app.db"));
builder.Services.AddAuthEndpointsIdentity<AppUser, AppDbContext>(options =>
{
options.User.RequireUniqueEmail = true;
});
builder.Services.AddCookieSessionEndpoints();
builder.Services.AddPasswordSignInEndpoints();
builder.Services.AddPasswordRecoveryEndpoints();
builder.Services.AddAccountManagementEndpoints();
builder.Services.AddExternalAuthEndpoints<AppUser>(options =>
{
options.AllowedReturnUrlOrigins.Add("https://app.example.com");
})
.AddGitHub(github =>
{
github.ClientId = "client-id";
github.ClientSecret = "client-secret";
});
builder.Services.AddTransient<IEmailSender<AppUser>, QueuedIdentityEmailSender>();
var app = builder.Build();
app.UseAuthEndpoints();
var auth = app.MapGroup("/auth");
auth.MapExternalAuthEndpoints<AppUser>(AuthEndpointsSession.Cookie);
auth.MapExternalAccountEndpoints<AppUser>();
auth.MapPasswordSignInEndpoints<AppUser>(AuthEndpointsSession.Cookie);
auth.MapPasswordRecoveryEndpoints<AppUser>();
auth.MapCookieSessionEndpoints<AppUser>();
auth.MapAccountManagementEndpoints<AppUser>();
app.Run();
public class AppUser : IdentityUser { }
public class AppDbContext(DbContextOptions<AppDbContext> options) : IdentityDbContext<AppUser>(options) { }
public sealed class QueuedIdentityEmailSender : IEmailSender<AppUser>
{
public Task SendConfirmationLinkAsync(AppUser user, string email, string confirmationLink)
=> Task.CompletedTask;
public Task SendPasswordResetLinkAsync(AppUser user, string email, string resetLink)
=> Task.CompletedTask;
public Task SendPasswordResetCodeAsync(AppUser user, string email, string resetCode)
=> Task.CompletedTask;
}
External sign-in has no two-factor step. Add AuthEndpoints.OAuth.Google and .AddGoogle the same way when you want Google. Host a page at ExternalAuthOptions.ErrorPath (default /auth/external/error).
An external-only user has no password, authenticator, or passkey, so email-code step-up is the way to reach POST /manage/password before those exist. Add AddEmailCodeEndpoints and UseEmailCodes() when that user must turn on 2FA or set a password. The send route appears on MapAccountManagementEndpoints once AddEmailCodeSendEndpoints or AddEmailCodeEndpoints is registered. AddEmailCodeSignInEndpoints alone does not map it.
Passkey-first
Email-code sign-up creates the account. The user then adds a passkey. Later sign-in uses the passkey. Password routes stay unmapped. After the passkey exists, email-code step-up turns off because a passkey is a stronger factor.
using AuthEndpoints;
using AuthEndpoints.EmailCode;
using AuthEndpoints.Identity;
using AuthEndpoints.Passkey;
using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<AppDbContext>(options =>
options.UseSqlite("Data Source=app.db"));
builder.Services.AddAuthEndpointsIdentity<AppUser, AppDbContext>(options =>
{
options.User.RequireUniqueEmail = true;
});
builder.Services.AddCookieSessionEndpoints();
builder.Services.AddAccountManagementEndpoints();
builder.Services.AddEmailCodeEndpoints<AppUser, AppDbContext>(options =>
{
options.AllowSignUp = true;
options.MagicLink.Enabled = true;
options.MagicLink.LinkUri = "https://app.example.com/auth/email-link";
options.MagicLink.AllowedOrigins.Add("https://app.example.com");
});
builder.Services.AddPasskeyEndpoints<AppUser>();
builder.Services.Configure<IdentityPasskeyOptions>(passkeys =>
{
passkeys.ServerDomain = "app.example.com";
});
builder.Services.AddTransient<IEmailCodeSender<AppUser>, QueuedEmailCodeSender>();
builder.Services.AddTransient<IEmailSender<AppUser>, QueuedIdentityEmailSender>();
var app = builder.Build();
app.UseAuthEndpoints();
var auth = app.MapGroup("/auth");
auth.MapEmailCodeEndpoints<AppUser>(AuthEndpointsSession.Cookie);
auth.MapCookieSessionEndpoints<AppUser>();
auth.MapAccountManagementEndpoints<AppUser>();
auth.MapPasskeySignInEndpoints<AppUser>(AuthEndpointsSession.Cookie);
auth.MapPasskeyManagementEndpoints<AppUser>();
app.Run();
public class AppUser : IdentityUser { }
public class AppDbContext(DbContextOptions<AppDbContext> options) : IdentityDbContext<AppUser>(options)
{
protected override void OnModelCreating(ModelBuilder builder)
{
base.OnModelCreating(builder);
builder.UseEmailCodes();
}
}
public sealed class QueuedEmailCodeSender : IEmailCodeSender<AppUser>
{
public Task SendSignInCodeAsync(EmailCodeMessage<AppUser> message, CancellationToken cancellationToken = default)
=> Task.CompletedTask;
}
public sealed class QueuedIdentityEmailSender : IEmailSender<AppUser>
{
public Task SendConfirmationLinkAsync(AppUser user, string email, string confirmationLink)
=> Task.CompletedTask;
public Task SendPasswordResetLinkAsync(AppUser user, string email, string resetLink)
=> Task.CompletedTask;
public Task SendPasswordResetCodeAsync(AppUser user, string email, string resetCode)
=> Task.CompletedTask;
}
Flow: email code or magic link, then POST /auth/confirmIdentity/emailCode/send and POST /auth/confirmIdentity with { "emailCode" }, then POST /auth/passkeys/creationOptions and POST /auth/passkeys. From then on the user signs in with POST /auth/passkeys/login.
MapPasskeySignInEndpoints also maps register/options and register and ensures confirm-email when that name is new. Do not also call MapPasskeyRegisterOptionsEndpoints on /auth.
External sign-in with JWT
The callback redirects, so refresh transport stays Cookie. Body transport throws when this map runs. There is no POST /create. Register IEmailCodeSender<TUser> as well if these users must step up before they have a password, an authenticator, or a passkey.
using AuthEndpoints;
using AuthEndpoints.External.OAuth;
using AuthEndpoints.Identity;
using AuthEndpoints.Jwt;
using AuthEndpoints.OAuth.GitHub;
using AuthEndpoints.OAuth.Google;
using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore;
var builder = WebApplication.CreateBuilder(args);
var key = "0123456789abcdef0123456789abcdef";
builder.Services.AddDbContext<AppDbContext>(options =>
options.UseSqlite("Data Source=app.db"));
builder.Services.AddAuthEndpointsIdentity<AppUser, AppDbContext>();
builder.Services.AddJwtEndpoints<AppUser, AppDbContext>(jwt =>
{
jwt.Issuer = "https://api.example.com";
jwt.Audience = "https://api.example.com";
jwt.SigningOptions.SymmetricKey = key;
});
builder.Services.AddAccountManagementEndpoints();
builder.Services.AddExternalAuthEndpoints<AppUser>(options =>
{
options.AllowedReturnUrlOrigins.Add("https://app.example.com");
})
.AddGitHub(github =>
{
github.ClientId = "github-client-id";
github.ClientSecret = "github-client-secret";
})
.AddGoogle(google =>
{
google.ClientId = "google-client-id";
google.ClientSecret = "google-client-secret";
});
var app = builder.Build();
app.UseAuthEndpoints();
app.MapGroup("/auth").MapJwtSessionEndpoints<AppUser>();
app.MapGroup("/auth/external").MapExternalAuthEndpoints<AppUser>(AuthEndpointsSession.Jwt);
app.MapGroup("/auth/external").MapExternalAccountEndpoints<AppUser>();
app.MapGroup("/auth").MapAccountManagementEndpoints<AppUser>();
app.Run();
public class AppUser : IdentityUser { }
public class AppDbContext(DbContextOptions<AppDbContext> options) : IdentityDbContext<AppUser>(options)
{
protected override void OnModelCreating(ModelBuilder builder)
{
base.OnModelCreating(builder);
builder.UseRefreshToken();
}
}
Password and passkey
That is the password facade. Cookie is the default. The building-block expansion is on Password auth.
using AuthEndpoints;
using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<AppDbContext>(options =>
options.UseSqlite("Data Source=app.db"));
builder.Services.AddPasswordAuth<AppUser, AppDbContext>(options =>
{
options.Passkeys.ServerDomain = "example.com";
});
builder.Services.AddTransient<IEmailSender<AppUser>, QueuedIdentityEmailSender>();
var app = builder.Build();
app.UseAuthEndpoints();
app.MapPasswordAuth<AppUser>();
app.Run();
public class AppUser : IdentityUser { }
public class AppDbContext(DbContextOptions<AppDbContext> options) : IdentityDbContext<AppUser>(options) { }
public sealed class QueuedIdentityEmailSender : IEmailSender<AppUser>
{
public Task SendConfirmationLinkAsync(AppUser user, string email, string confirmationLink)
=> Task.CompletedTask;
public Task SendPasswordResetLinkAsync(AppUser user, string email, string resetLink)
=> Task.CompletedTask;
public Task SendPasswordResetCodeAsync(AppUser user, string email, string resetCode)
=> Task.CompletedTask;
}
Identity bearer and cookie prefixes
The password facade does not map Identity bearer. Compose AddBearerAuthEndpoints and MapBearerAuthEndpoints. Cookie and bearer session maps both expose POST /logout, so they need different prefixes, such as /auth for the cookie session and /bearer for Identity bearer. ?useCookies=true does nothing on cookie POST /login. That query affects Identity bearer login and the default passkey completer.
For a hand-mapped host, call AddAuthEndpointsIdentity rather than bare AddIdentityApiEndpoints, then AddCookieAuthEndpoints or AddBearerAuthEndpoints, and map MapIdentityManagementApi once.