Identity.Base.Organizations 0.6.1

Identity Base Organizations

For the canonical documentation (installation, endpoints, extension points) see docs/packages/identity-base-organizations/index.md. The README provides a quick-start snapshot.

Identity.Base.Organizations layers organization management on top of the core Identity Base and RBAC packages. It provides EF Core entities, services, hosted infrastructure, and minimal API endpoints so any host can manage organizations, memberships, and organization-scoped roles without custom scaffolding.

Features

• Organization aggregate (Organization, OrganizationMetadata) with per-tenant slug/display name uniqueness.
• Membership service with primary-organization tracking, role assignments, and helper queries for listing memberships.
• Organization-specific role catalog and claim formatter that augments Identity Base permission claims with organization context.
• Hosted migration/seed services that keep the organizations schema current and bootstrap default roles (OrgOwner, OrgManager, OrgMember).
• Minimal API modules for CRUD, membership management, role management, and user-facing endpoints.
• Builder hooks (ConfigureOrganizationModel, AfterOrganizationSeed, AddOrganizationClaimFormatter, AddOrganizationScopeResolver) mirroring Identity Base extensibility points.

Installation

1. Add the package

dotnet add package Identity.Base.Organizations

2. Register services

Add the organizations services after AddIdentityBase (and optionally AddIdentityRoles) in Program.cs:

using Identity.Base.Extensions;
using Identity.Base.Organizations.Data;
using Identity.Base.Organizations.Extensions;
using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddIdentityBase(builder.Configuration, builder.Environment);
var rolesBuilder = builder.Services.AddIdentityRoles(builder.Configuration);
rolesBuilder.AddDbContext<IdentityRolesDbContext>((provider, options) =>
{
    var connectionString = builder.Configuration.GetConnectionString("Primary")!;
    options.UseNpgsql(connectionString);
});

var organizationsBuilder = builder.Services.AddIdentityBaseOrganizations(options =>
{
    var connectionString = builder.Configuration.GetConnectionString("Primary")!;
    options.UseNpgsql(connectionString);
});

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

If you omit the options callback, the package attempts to use the IdentityOrganizations connection string from configuration.

3. Apply migrations

Identity.Base.Organizations ships with an initial migration for OrganizationDbContext:

dotnet ef database update \
  --project Identity.Base.Organizations/Identity.Base.Organizations.csproj \
  --context Identity.Base.Organizations.Data.OrganizationDbContext

The hosted OrganizationMigrationHostedService also applies pending migrations on startup when the provider is relational.

4. Seed default roles

OrganizationRoleSeeder creates the default system roles. Register additional callbacks if you need to extend the seed pipeline:

organizationsBuilder.AfterOrganizationSeed(async (sp, ct) =>
{
    // e.g. provision billing metadata, assign baseline memberships, etc.
});

5. Customize the model

Use ConfigureOrganizationModel to add indexes or shadow properties:

organizationsBuilder.ConfigureOrganizationModel(modelBuilder =>
{
    modelBuilder.Entity<Organization>().HasIndex(org => org.CreatedAtUtc);
});

API surface

Default organization roles (Owner/Manager/Member) currently receive only the user-scoped (user.organizations.*) permissions. Create a separate role with admin.organizations.* permissions if you need a platform-wide organization administrator.

Active organization context

Tokens issued by Identity Base now include an org:memberships claim listing all organization IDs for the signed-in user. Add the middleware in your pipeline:

app.UseOrganizationContextFromHeader();

Then send the X-Organization-Id header on each request. The middleware validates the caller still belongs to that organization (admins with admin.organizations.* bypass the membership check) and loads the organization metadata into IOrganizationContextAccessor; it automatically ignores the header on the admin /organizations APIs so those remain truly global. If a membership changes (for example, the user loses access to an organization), refresh their tokens so the org:memberships claim stays up to date.

Authorization is enforced through the Identity Base RBAC package. The default IOrganizationScopeResolver verifies the caller is a member of the target organization; override it (or IPermissionClaimFormatter) via the builder extensions to compose tenant-specific or elevated administrator rules.

Options

• OrganizationOptions
  • SlugMaxLength, DisplayNameMaxLength
  • MetadataMaxBytes, MetadataMaxKeyLength, MetadataMaxValueLength
• OrganizationRoleOptions
  • NameMaxLength, DescriptionMaxLength
  • Default role names (OwnerRoleName, ManagerRoleName, MemberRoleName)

Bind or override using the standard options pattern:

builder.Services.Configure<OrganizationOptions>(builder.Configuration.GetSection("Organizations"));

Extensibility

organizationsBuilder
    .ConfigureOrganizationModel(modelBuilder => { /* custom EF configuration */ })
    .AfterOrganizationSeed(async (sp, ct) => { /* custom seeding */ })
    .AddOrganizationClaimFormatter<CustomFormatter>()
    .AddOrganizationScopeResolver<CustomScopeResolver>();

Testing

Run the solution tests to execute the organizations unit suite alongside the existing Identity Base coverage:

dotnet test Identity.sln

License

MIT, consistent with the rest of the Identity Base OSS packages.