Identity.Base Docs

Quick Start

This follows the real upstream package-based bootstrap path: create a host, install the modules you need, register each service and endpoint family explicitly, own every enabled DbContext migration, and verify health plus OIDC discovery.

Prerequisites

.NET 9 SDK
`dotnet-ef` installed if you will manage migrations from the CLI
PostgreSQL 16 or SQL Server, depending on your chosen provider
Optional MailJet or SendGrid credentials if you want real account emails during testing

0. Create the host project

bash

dotnet new web -n IdentityHost
cd IdentityHost
dotnet tool install --global dotnet-ef

1. Install the packages

bash

dotnet add package Identity.Base
dotnet add package Identity.Base.Admin
dotnet add package Identity.Base.Roles
dotnet add package Identity.Base.Organizations
dotnet add package Identity.Base.ServicePrincipals
dotnet add package Identity.Base.Email.MailJet

2. Configure Program.cs

csharp

using Identity.Base.Admin.Configuration;
using Identity.Base.Admin.Endpoints;
using Identity.Base.Email.MailJet;
using Identity.Base.Extensions;
using Identity.Base.Organizations.Extensions;
using Identity.Base.Roles.Endpoints;
using Identity.Base.ServicePrincipals.Extensions;
using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);
var configureDbContext = new Action<IServiceProvider, DbContextOptionsBuilder>((sp, options) =>
{
    var connectionString = sp.GetRequiredService<IConfiguration>().GetConnectionString("Primary")
        ?? throw new InvalidOperationException("ConnectionStrings:Primary must be set.");
    options.UseNpgsql(connectionString, sql => sql.EnableRetryOnFailure());
});

var identity = builder.Services.AddIdentityBase(builder.Configuration, builder.Environment, configureDbContext: configureDbContext);
identity.UseTablePrefix("Contoso");
identity.UseMailJetEmailSender();
builder.Services.AddIdentityAdmin(builder.Configuration, configureDbContext).UseTablePrefix("Contoso");
builder.Services.AddIdentityBaseOrganizations(configureDbContext).UseTablePrefix("Contoso");
builder.Services.AddIdentityBaseServicePrincipals(builder.Configuration, configureDbContext);

var app = builder.Build();
app.UseApiPipeline();
app.UseOrganizationContextFromHeader();
app.MapControllers();
app.MapApiEndpoints();
app.MapIdentityRolesUserEndpoints();
app.MapIdentityAdminEndpoints();
app.MapIdentityBaseOrganizationEndpoints();
app.MapIdentityBaseServicePrincipalEndpoints();
await app.RunAsync();

3. Add the minimum configuration

json

{
  "ConnectionStrings": {
    "Primary": "Host=localhost;Database=identity;Username=postgres;Password=postgres"
  },
  "IdentitySeed": {
    "Enabled": true,
    "Email": "[email protected]"
  },
  "Cors": {
    "AllowedOrigins": [
      "http://localhost:5173",
      "https://localhost:5173"
    ]
  },
  "OpenIddict": {
    /* clients, scopes, and keys */
  },
  "Identity": {
    "ServicePrincipals": {
      "AccessTokenLifetime": "00:15:00",
      "AllowedScopes": ["identity.api"]
    }
  }
}

4. Generate and apply migrations from the host

bash

dotnet ef migrations add InitialIdentityBase --context Identity.Base.Data.AppDbContext
dotnet ef migrations add InitialRoles --context Identity.Base.Roles.IdentityRolesDbContext
dotnet ef migrations add InitialOrganizations --context Identity.Base.Organizations.Data.OrganizationDbContext
dotnet ef migrations add InitialServicePrincipals --context Identity.Base.ServicePrincipals.Data.ServicePrincipalDbContext

dotnet ef database update --context Identity.Base.Data.AppDbContext
dotnet ef database update --context Identity.Base.Roles.IdentityRolesDbContext
dotnet ef database update --context Identity.Base.Organizations.Data.OrganizationDbContext
dotnet ef database update --context Identity.Base.ServicePrincipals.Data.ServicePrincipalDbContext

5. Run and verify

bash

dotnet run

# OpenID configuration available at:
# https://localhost:5001/.well-known/openid-configuration

# OpenAPI JSON in development:
# https://localhost:5001/openapi/v1.json

Important: Identity Base does not ship provider migrations. Your host owns migrations, provider choice, and table prefixes. Service principals require both their own context and the updated roles context.