Identity.Base Docs
Identity.Base.Roles
`Identity.Base.Roles` supplies the RBAC substrate for the rest of Identity Base. It owns the permission catalog, role definitions, user-role assignments, and the claim formatting pipeline that downstream APIs and admin surfaces rely on.
Install and seed RBAC
csharp
var rolesBuilder = builder.Services.AddIdentityRoles(
builder.Configuration,
(sp, options) =>
{
var connectionString = sp.GetRequiredService<IConfiguration>().GetConnectionString("Primary")!;
options.UseNpgsql(connectionString);
});
rolesBuilder.UseTablePrefix("Contoso");
var app = builder.Build();
app.MapIdentityRolesUserEndpoints();
await app.Services.SeedIdentityRolesAsync();Configuration sections
- `Permissions` defines the canonical permission catalog and descriptions.
- `Roles` defines role names, role descriptions, permission membership, and default assignments.
- Seed process is idempotent: it adds missing permissions and roles, updates descriptions, and keeps the catalog synchronized.
What gets stored
- `Identity_Roles` for role definitions.
- `Identity_Permissions` for permission definitions.
- `Identity_RolePermissions` for the many-to-many role mapping.
- `Identity_UserRoles` for user-role assignments.
- `Identity_ServicePrincipalRoles` for optional service-principal role assignments when that package is enabled.
- `Identity_AuditEntries` for audit records used by the admin layer.
| API or Type | Why it matters |
|---|---|
| SeedIdentityRolesAsync() | Synchronizes the configured permissions and roles into the database. |
| IRoleAssignmentService | Assigns and removes roles from users without reimplementing the relationship logic. |
| IPermissionResolver | Calculates the effective permission set that becomes the token claim. |
| IPermissionClaimFormatter | Controls how effective permissions are serialized into claims. |
| GET /users/me/permissions | Low-friction way to inspect what the current user actually received in claims. |
Design implications
- Permissions are the durable contract. Endpoints and clients should depend on permissions, not on specific role names.
- Roles can stay host-specific. You own the seeded role names and which permissions they collect.
- Organizations can add dynamic permissions. `IAdditionalPermissionSource` lets org membership contribute extra values at token-issuance time.
- Service principals reuse global roles. Machine tokens receive the same role-derived permission contract without user or organization membership.
- Migrations still belong to the host. The package no longer ships provider-specific migrations.