Identity.Base Docs

Identity.Base Core Package

`Identity.Base` is the host package that turns an ASP.NET Core application into an OAuth2/OIDC identity authority. Everything else in the ecosystem layers on top of it, so this is the package to understand first if you are building a real production host.

What the core package owns

OpenIddict hosting for authorization code + PKCE, refresh tokens, discovery, token issuance, and logout.
Identity workflows for registration, login, confirmation, password reset, MFA enrollment, MFA challenge, recovery codes, and profile management.
Operational defaults such as `UseApiPipeline`, JSON health checks, seed callbacks, and safe host extension points.

Minimal host wiring

csharp

var builder = WebApplication.CreateBuilder(args);

var identity = builder.Services.AddIdentityBase(
    builder.Configuration,
    builder.Environment,
    configureDbContext: (sp, options) =>
    {
        var connectionString = sp.GetRequiredService<IConfiguration>().GetConnectionString("Primary")
            ?? throw new InvalidOperationException("ConnectionStrings:Primary must be set.");

        options.UseNpgsql(connectionString);
    });

identity.UseTablePrefix("Contoso"); // optional

var app = builder.Build();
app.UseApiPipeline(appBuilder => appBuilder.UseSerilogRequestLogging());
app.MapApiEndpoints();
await app.RunAsync();

Surface	Routes	Notes
Authentication	/auth/register, /auth/login, /auth/logout, /auth/profile-schema	Registration, password login, cookie logout, profile-schema discovery.
MFA	/auth/mfa/enroll, /verify, /challenge, /disable, /recovery-codes	Authenticator apps by default, with optional email and SMS channels.
Email workflows	/auth/confirm-email, /resend-confirmation, /forgot-password, /reset-password	Requires a real templated email sender if you want production delivery.
OpenIddict	/connect/authorize, /connect/token, /connect/logout, /connect/userinfo	Your SPA and downstream APIs rely on these endpoints.
User profile	/users/me, /users/me/profile, /users/me/change-password	Can be called with cookie auth or bearer auth depending on your app shape.
Health	/healthz	Returns structured JSON with the readiness checks that the host registered.

Configuration checklist

`ConnectionStrings:Primary` is required. Hosts own migrations and apply them before startup.
`OpenIddict:Applications` must explicitly list permissions, grants, scopes, redirect URIs, and PKCE requirements.
`Registration` defines confirmation/reset URL templates and any registration metadata fields.
`Cors:AllowedOrigins` must include every browser origin that will call `/auth/*` or `/connect/*`.
`OpenIddict:ServerKeys` should move to persisted signing and encryption keys outside local development.

Host responsibilities that stay outside the package

Choose and configure the EF Core provider.
Generate and apply migrations from the consuming host project.
Register external auth providers and map their route keys.
Choose the email sender implementation and manage secrets.
Run any provisioning logic after seed completion through the builder callbacks.

Extension points worth knowing

Email delivery: replace `ITemplatedEmailSender` with MailJet, SendGrid, or your own sender.
Audit and sanitization: override `IAuditLogger` and `ILogSanitizer` to fit your logging stack.
Lifecycle hooks: use `AfterRoleSeeding`, `AfterIdentitySeed`, and user lifecycle listeners to attach domain provisioning.
EF model customization: `ConfigureAppDbContextModel` and `UseTablePrefix(...)` let the package fit an existing schema strategy.