Authendpoints

AuthEndpoints 3.x (library users)

Ready-made Identity auth API endpoints for first-party web and mobile clients. This skill is for apps that consume the NuGet package, not for changing the AuthEndpoints source repo.

Canonical docs: https://authendpoints.harten.id — follow those pages; do not invent APIs.

Requires .NET 10, ASP.NET Core Identity, and EF Core. The host DbContext is typically IdentityDbContext<TUser> (or with roles). TUser may use any Identity key type (string, Guid, long, …). Passwordless passkey account register needs a string or Guid key. The minted user id defaults to Guid.NewGuid() (UUID v4); register IPasskeyUserIdFactory to choose a different id.

Install

dotnet add package AuthEndpoints

GitHub/Google OAuth is compose-only (independent preview versioning, not inside MapAuthEndpoints). Install the provider package you use. It depends on AuthEndpoints.External.OAuth. The core OAuth nupkg does not reference GitHub or Google handlers.

dotnet add package AuthEndpoints.OAuth.GitHub --prerelease
dotnet add package AuthEndpoints.OAuth.Google --prerelease

AutoLinkByEmail defaults to false. Opt in only when a verified provider email should attach to a local account whose email is already confirmed. Host a page at ErrorPath. Unlink requires the application cookie, an antiforgery token, and a ReAuth principal, and it refuses the last sign-in method.

Docs: https://authendpoints.harten.id/modules/external-oauth

Prefer the facade

One Add / Use / Map triad. Cookie is the default sign-in. Native/mobile uses AuthEndpointsSignIn.IdentityBearer. Compose modules yourself only for JWT-only hosts, custom prefixes, or a mix the facade does not cover.

Cookie web

Default: Identity management + cookie sign-in at IdentityPath (/identity) and passkeys at PasskeyPath (/account). JWT is opt-in.

builder.Services.AddDbContext<AppDbContext>(/* your provider */);

builder.Services.AddAuthEndpoints<AppUser, AppDbContext>(o =>
{
    o.Passkeys.ServerDomain = "example.com"; // required in Production when passkeys are enabled
});

// Required in Production (Identity's no-op sender is rejected).
builder.Services.AddTransient<IEmailSender<AppUser>, MyEmailSender>();

var app = builder.Build();

app.UseAuthEndpoints();          // authentication, authorization, rate limiting, antiforgery
app.MapAuthEndpoints<AppUser>(); // /identity (management + cookie) + /account (passkeys)
app.Run();

Identity bearer (native / mobile)

Same methods and pipeline. Maps Identity Login (JSON access and refresh tokens) instead of LoginCookie.

builder.Services.AddAuthEndpoints<AppUser, AppDbContext>(AuthEndpointsSignIn.IdentityBearer, o =>
{
    o.Passkeys.ServerDomain = "example.com";
});

builder.Services.AddTransient<IEmailSender<AppUser>, MyEmailSender>();

var app = builder.Build();

app.UseAuthEndpoints();
app.MapAuthEndpoints<AppUser>(); // /identity (management + bearer login/refresh) + /account (passkeys)
app.Run();

AddAuthEndpoints returns IdentityBuilder for optional chaining. It registers Identity API endpoints, EF stores, IdentitySchemaVersions.Version3 (required for passkey credential storage), antiforgery, cookie or bearer auth helpers, ReAuth, and rate limits.

UseAuthEndpoints must run after exception-handling middleware. Enable HTTPS in Production separately. Safe to call once; a second call is a no-op.

Quick start: https://authendpoints.harten.id/getting-started/quick-start

Roles

Use the three-type overload so AddRoles runs before AddEntityFrameworkStores:

builder.Services.AddAuthEndpoints<AppUser, AppRole, AppDbContext>(o =>
{
    o.Passkeys.ServerDomain = "example.com";
});

DbContext should be IdentityDbContext<AppUser, AppRole, TKey> (or equivalent). Do not chain bare .AddRoles<TRole>() after the two-type overload.

Choose cookie vs bearer vs JWT

Mixed web + native: map separate sign-in groups (or hosts) per client type. Do not map cookie and bearer login on the same path without separate groups.

Recipes: https://authendpoints.harten.id/composables/recipes

Paths below use IdentityPath (default /identity). Hosts that change o.IdentityPath must use that prefix instead.

Login query flags

Which handler is mapped decides which query flags work. Cookie facade / MapCookieAuthEndpoints maps LoginCookie. Bearer facade / MapBearerAuthEndpoints maps Identity Login. useCookies on the cookie-facade login URL does nothing.

Cookie facade → LoginCookie

Always the application cookie. Only useSessionCookies is read. useCookies is ignored.

Body is Identity LoginRequest (email, password, optional twoFactorCode / twoFactorRecoveryCode). POST {IdentityPath}/login (default /identity/login) does not need CSRF. Lockout on failure. Rate-limited.

Bearer facade → Identity Login

Cookie iff useCookies==true || useSessionCookies==true. Persistent iff useCookies==true && useSessionCookies!=true. Neither flag → Identity bearer tokens (accessToken, refreshToken).

Default passkey completer (IdentityPasskeySignInCompleter) uses these Identity Login rules, not LoginCookie — even when password login uses the cookie facade.

CSRF on cookie mutations

Cookie sessions and the JWT refresh cookie need antiforgery on unsafe methods (POST / PUT / PATCH / DELETE). Login does not.

1. GET {IdentityPath}/csrfToken (default /identity/csrfToken; JWT: {Jwt.Path}/csrfToken, default /auth/csrfToken) → JSON csrfToken.
2. Send the token in the antiforgery header.
3. Send cookies (credentials: "include" / Axios withCredentials).

The library calls AddAntiforgery() with no header override. ASP.NET Core's default header name is RequestVerificationToken. Hosts may set AntiforgeryOptions.HeaderName to X-CSRF-TOKEN (common for SPAs). Clients must use the header the host configured.

CSRF is skipped when the request is authenticated via Identity bearer or JWT Bearer and not via the application/external cookie. Cookie sessions still require CSRF even if a bearer token is also present.