External OAuth packages
GitHub and Google sign-in is compose-only. The password facade does not map it. The endpoint types live in AuthEndpoints.dll, namespace AuthEndpoints.External.OAuth. AuthEndpoints.OAuth.GitHub and AuthEndpoints.OAuth.Google 4.0.0 only register handlers. They depend on AuthEndpoints [4.0.0, 5.0.0).
AuthEndpoints.External.OAuth 4.0.0 is a forwarding shim. Remove it, or upgrade a package below 4.0.0. A package below 4.0.0 fails the build with AE4000. The shim warns AE4001.
Pass AuthEndpointsSession to MapExternalAuthEndpoints or MapExternalAuthProvider. The default session is the cookie completer. There is no two-factor step. Jwt with RefreshTokenTransport.Body throws at map time. See Sign-in completers.
Install
dotnet add package AuthEndpoints
dotnet add package AuthEndpoints.OAuth.GitHub
dotnet add package AuthEndpoints.OAuth.Google
Requires ASP.NET Core Identity already configured, typically via AddAuthEndpointsIdentity or AddPasswordAuth. External sign-in does not call the Identity management HTTP API. Map account management yourself when you need it.
Hosts must call UseRateLimiter() (included in UseAuthEndpoints). AddExternalAuthEndpoints registers the login rate-limit policy.
DI
using AuthEndpoints.External.OAuth;
using AuthEndpoints.OAuth.GitHub;
using AuthEndpoints.OAuth.Google;
builder.Services.AddExternalAuthEndpoints<AppUser>(o =>
{
o.RequireVerifiedEmail = true; // default
o.AutoLinkByEmail = false; // default; opt in requires verified provider email and confirmed local email
o.DefaultReturnUrl = "/"; // rooted local path
o.ErrorPath = "/auth/external/error";
// o.AllowedReturnUrlOrigins.Add("https://app.example.com"); // optional absolute allowlist
})
.AddGitHub(o =>
{
o.ClientId = builder.Configuration["Authentication:GitHub:ClientId"]!;
o.ClientSecret = builder.Configuration["Authentication:GitHub:ClientSecret"]!;
})
.AddGoogle(o =>
{
o.ClientId = builder.Configuration["Authentication:Google:ClientId"]!;
o.ClientSecret = builder.Configuration["Authentication:Google:ClientSecret"]!;
});
ClientId/Secret are validated on startup. Missing values fail fast.
AddExternalAuthEndpoints<TUser>() returns an ExternalAuthBuilder. These methods extend it:
AddGitHub(fromAuthEndpoints.OAuth.GitHub) andAddGoogle(fromAuthEndpoints.OAuth.Google) register the OAuth handlers (SignInScheme = Identity.External) and provider metadata.AddCompleter<T>is obsolete. PassAuthEndpointsSessionor a completer name to the map.AddProviderandAddProvider<T>register a custom provider. See Custom providers.
JWT completion
Requires JWT services registered (AddJwtEndpoints):
builder.Services.AddJwtEndpoints<AppUser, AppDbContext>(jwt =>
{
jwt.Issuer = "https://example.com";
jwt.Audience = "https://example.com";
jwt.SigningOptions.SymmetricKey = key;
});
builder.Services.AddExternalAuthEndpoints<AppUser>()
.AddGitHub(...);
app.MapGroup("/auth/external").MapExternalAuthEndpoints<AppUser>(AuthEndpointsSession.Jwt);
After OAuth, the completer writes a refresh cookie and the browser redirects to returnUrl. The access token is not in that URL. The client calls POST /auth/refresh with the CSRF token and the refresh cookie. This session requires RefreshTokenTransport.Cookie. Body transport throws at map time, and the callback does not create a refresh token.
Map
var external = app.MapGroup("/auth/external").WithTags("External");
external.MapExternalAuthProvider<AppUser>("GitHub");
external.MapExternalAuthProvider<AppUser>("Google");
external.MapExternalAccountEndpoints<AppUser>(); // link / unlink while signed in
Or map every registered sign-in provider:
app.MapGroup("/auth/external").MapExternalAuthEndpoints<AppUser>();
Routes
Relative to the group prefix (example /auth/external):
| Method | Path | Auth | Notes |
|---|---|---|---|
GET | /providers | List registered providers as { "scheme", "displayName" }; [] when none is registered | |
GET | /login/github | Challenge; rate-limited; returnUrl | |
GET | /login/github/callback | Provision + completer; errors redirect to ErrorPath | |
GET | /login/google | Challenge; rate-limited | |
GET | /login/google/callback | Provision + completer | |
GET | /logins | yes | List linked external logins |
DELETE | /logins/{loginProvider}/{providerKey} | yes | Unlink; antiforgery + ReAuth; refuses the last sign-in method |
GET | /link/{scheme} | yes | Start link challenge |
GET | /link/{scheme}/callback | yes | Complete link |
IdP callback paths
| Provider | Middleware path |
|---|---|
| GitHub | /signin-github |
/signin-google |
Security behavior
- Account creation: a verified provider email creates an account when no local user has that email. There is no option to stop that.
RequireVerifiedEmaildefaults totrueand refuses an unverified email. It does not stop creation for a verified email. - Verified email (default): Google reads
email_verifiedfrom the userinfo payload after the host configures the handler, so a host stamp cannot stick. GitHub callsGET https://api.github.com/user/emailswith the access token and keeps the verified primary address, or any verified address when the primary is unverified. An unverified profile email is dropped. The access token is not saved on the ticket (SaveTokensis false). - Auto-link by email (default off): when
AutoLinkByEmailis true, the provider email must be verified and the local account'sEmailConfirmedmust be true, even ifRequireVerifiedEmailis false. Otherwise the callback denies withauto_link_disabled,email_unverified, oremail_unconfirmed. - EmailConfirmed on new users matches whether the provider email was verified.
- Link: the challenge stores the signed-in user id as the external-login XSRF token (
ConfigureExternalAuthenticationProperties). The callback accepts the external login only when that token matches. Explicit link also requires a verified email whenRequireVerifiedEmailis true. The callback scheme must match the route. - Unlink: requires an AuthEndpoints sign-in scheme, the core antiforgery filter, and
.RequireReauth().GET /loginsand the link routes use the same schemes (RequireAuthEndpointsUser), so a custom default scheme does not authorize them. The step-up proof has to be for that same user. It is not merged intoHttpContext.User, so the antiforgery token still matches the application user. A signed-in user without a matching proof gets403. Removal is refused when it would delete the last sign-in method. A password, each passkey, each other external login, and email code can remain. Email code counts only when email-code sign-in is mapped and the email is confirmed. A missing login returns 404. The problem title islast_signin_method. Passkeys are counted when the Identity store schema is version 3 (AddAuthEndpointsIdentitysets this, andAddPasswordAuthcalls it). - External cookie is signed out after success and on login/link failure, including remote authentication failure.
returnUrl: rooted local paths are accepted before any absolute-URI parse, so/and/dashboardstay local on Linux.~/, protocol-relative//, backslash, control characters, and encoded CR/LF/NUL/tab are rejected. Absolute URLs must matchAllowedReturnUrlOriginsby scheme, host, and port (same rule as email-confirmation redirects). Illegal values fall back toDefaultReturnUrl.- Errors / cancel: browser redirects to
ErrorPath?error=&error_description=; clients that preferapplication/jsonovertext/htmlget Problem details instead. - Cookie completion calls
SignInAsyncdirectly. It does not issue a two-factor challenge, so OAuth sign-in skips 2FA for users who turned it on. Identity UI usesExternalLoginSignInAsyncinstead, which returnsRequiresTwoFactorfor those users.JwtExternalLoginCompleteralso skips 2FA. Hosts that need 2FA after OAuth should register a completer that checks it.
Options
| Property | Default | Notes |
|---|---|---|
SignInScheme | null | Cookie completer scheme override |
IsPersistent | true | Application cookie persistence |
DefaultReturnUrl | / | Rooted local path |
RequireVerifiedEmail | true | Block unverified provider emails on create and explicit link |
AutoLinkByEmail | false | Opt-in link of an existing confirmed user by verified provider email |
AllowedReturnUrlOrigins | empty | Absolute http(s) origins allowlist |
ErrorPath | /auth/external/error | Relative path for error redirects |
Custom providers
- Register an OAuth handler with
SignInScheme = IdentityConstants.ExternalScheme. - Implement
IExternalAuthProvider(scheme + login/callback paths + endpoint name). builder.AddProvider<MyProvider>()thenMapExternalAuthProvider<TUser>("MyScheme")orMapExternalAuthEndpoints.
Built-in GitHub and Google providers set email and email_verified themselves. A custom provider must put a real verified email on the principal when RequireVerifiedEmail is true. A host event that stamps email_verified before the provider seal does not count.
Configuration
The library reads no configuration keys. OAuth ClientId and ClientSecret come from the configure delegate that you pass to AddGitHub or AddGoogle. They are not ExternalAuthOptions properties. The DI sample above reads them from host configuration:
| Configuration key | Environment variable |
|---|---|
Authentication:GitHub:ClientId / Authentication:GitHub:ClientSecret | Authentication__GitHub__ClientId / Authentication__GitHub__ClientSecret |
Authentication:Google:ClientId / Authentication:Google:ClientSecret | Authentication__Google__ClientId / Authentication__Google__ClientSecret |
Use any key names you like. Change the configure delegate to match.
Gotchas
- Pipeline: authentication +
UseRateLimiter()(viaUseAuthEndpoints). - Host an error page at
ErrorPath(or change the option). - Install
AuthEndpoints.OAuth.GitHuborAuthEndpoints.OAuth.Google(or both). The core package alone does not register those handlers. - OAuth sign-in skips two-factor with both built-in completers. See Security behavior.