Identity Base

Identity Base is a modular Identity + OpenID Connect platform for .NET 9. It packages ASP.NET Core Identity, provider-agnostic EF Core contexts, OpenIddict server setup, MFA, external provider orchestration for host-registered OAuth/OIDC schemes, optional email delivery providers (Mailjet, SendGrid), and deployment-ready defaults. The recommended architecture is a dedicated Identity Host that runs all identity surfaces, a fleet of JWT-protected microservices, and a React 19 SPA consuming the APIs. Hosts are responsible for configuring the DbContexts, generating migrations for their chosen provider (PostgreSQL, SQL Server, etc.), and applying them before Identity Base runs its seeders.

The project is open source under the MIT License.

---

Features at a Glance

• Identity & OpenIddict orchestration – authorization-code PKCE flow, refresh tokens, configured scopes, client seeding.
• Multi-factor authentication – authenticator apps, SMS, email challenges, and recovery code support.
• External providers – provider-agnostic endpoints with host-registered OAuth/OIDC schemes.
• Email delivery integrations – optional packages for Mailjet (Identity.Base.Email.MailJet) or SendGrid (Identity.Base.Email.SendGrid) to send confirmation, password reset, and MFA challenge emails.
• Extensible DI surface – option validators, templated email sender, MFA challenge senders, audit logging, return URL validation.
• Secure defaults – return URL normalization, request logging with redaction, dedicated health checks.

---

Database Providers & Migrations

Identity Base is provider-agnostic: the packages expose DbContexts but never register a specific provider or ship migrations. Your host application must:

1. Configure each required DbContext (e.g., via the configureDbContext delegate on AddIdentityBase, AddIdentityRoles, AddIdentityOrganizations, AddIdentityAdmin) and choose UseNpgsql, UseSqlServer, etc.
2. Generate migrations from the host project (dotnet ef migrations add ...) and keep them with the host/source control.
3. Apply migrations (for example, on startup before calling SeedIdentityRolesAsync) and then let the Identity Base seeders run.

See Identity.Base.Host and apps/org-sample-api for reference helper extensions, design-time factories, and per-host table prefixes. The Getting Started guide walks through configuring the delegates and running dotnet ef.

---

Repository Overview

Path	Purpose
Identity.Base/	Core class library (Identity, OpenIddict, EF Core contexts, MFA) published to NuGet (no bundled migrations).
Identity.Base.Roles/	Role-based access control primitives (roles, permissions, seeding helpers).
Identity.Base.Admin/	Admin API/RBAC extensions layered on the core package.
Identity.Base.Organizations/	Multi-tenant organization, membership, and role tooling.
Identity.Base.AspNet/	Helpers that let microservices validate Identity Base-issued JWTs.
Identity.Base.Email.MailJet/	Optional Mailjet email sender and configuration add-on.
Identity.Base.Email.SendGrid/	Optional SendGrid email sender and configuration add-on.
Identity.Base.Host/	Opinionated ASP.NET Core host wired for local development and integration tests. Owns its migrations/prefixes and applies them before seeding on startup.
apps/	Sample APIs that demonstrate bearer auth and organization scenarios.
docs/	Architecture, engineering principles, sprint plans, onboarding, full-stack integration guides.
packages/	Client packages (@identity-base/client-core, @identity-base/angular-client, @identity-base/angular-organizations, @identity-base/react-client, @identity-base/react-organizations).

Provider selection in the sample host is config-driven: set Database:Provider to PostgreSql, SqlServer, or InMemory, and optionally point Database:Migrations:{ContextName} (or Database:Migrations:Default) at provider-specific migration assemblies.

Key documents:

• Package Documentation Hub
• Project Plan
• Engineering Principles
• Database Design Guidelines
• HTTP API Reference (Scopes + OpenAPI)
• Identity.Base Public API
• Release Checklist
• React Integration Guide

Task Playbooks

• Overview: docs/playbooks/README.md
• Pilot: docs/playbooks/identity-base-with-roles-and-organizations.md
• Manifest: docs/playbooks/index.yaml

---

NuGet Packages

Package	Description
Identity.Base	Core Identity/OpenIddict services, EF Core contexts (bring-your-own migrations), MFA, external providers, DI extensions.
Identity.Base.Roles	Role and permission management primitives (DbContext, seed helpers, configuration).
Identity.Base.Admin	Admin API extensions layered on Identity Base + roles.
Identity.Base.Organizations	Organizations, memberships, and organization-scoped role tooling.
Identity.Base.AspNet	ASP.NET Core helpers for microservices consuming Identity Base tokens via JWT bearer authentication.
Identity.Base.Email.MailJet	Optional Mailjet integration (email sender, options, health checks).
Identity.Base.Email.SendGrid	Optional SendGrid integration (email sender, options, health checks).

Install via .NET CLI (replace <latest> with the published version):

dotnet add package Identity.Base --version <latest>
# Add-on packages as needed:
dotnet add package Identity.Base.Roles --version <latest>
dotnet add package Identity.Base.Admin --version <latest>
dotnet add package Identity.Base.Organizations --version <latest>
dotnet add package Identity.Base.AspNet --version <latest>
dotnet add package Identity.Base.Email.MailJet --version <latest>
dotnet add package Identity.Base.Email.SendGrid --version <latest>

Manual package builds are available through the GitHub Actions CI workflow (see Release Checklist).

---

Quick Start

1. Identity Host (all identity + admin endpoints)

dotnet restore Identity.sln
dotnet build Identity.sln
dotnet run --project Identity.Base.Host/Identity.Base.Host.csproj

The host wires the full pipeline:

The host applies all bundled migrations on startup (Identity, Roles, Organizations) and seeds the admin account based on configuration. No manual dotnet ef database update is required unless you add custom entities.

If you install an email add-on, call identity.UseMailJetEmailSender(); or identity.UseSendGridEmailSender(); (or the corresponding builder.Services.Add*EmailSender(...)) when configuring services. Follow the Getting Started guide for configuration schema and OpenIddict application registration.

2. Secure .NET microservices

// Program.cs
using Identity.Base.AspNet;

builder.Services.AddIdentityBaseAuthentication("https://identity.yourdomain.com");

var app = builder.Build();
app.UseIdentityBaseRequestLogging();
app.UseIdentityBaseAuthentication();

app.MapGet("/api/protected", () => "Secure content")
   .RequireAuthorization(policy => policy.RequireScope("identity.api"));

See Identity.Base.AspNet/README.md for detailed options, scope helpers, and troubleshooting.

3. React 19 SPA

Install the published React packages and wrap your app with both providers:

npm install @identity-base/react-client @identity-base/react-organizations

import { IdentityProvider } from '@identity-base/react-client';
import { OrganizationsProvider } from '@identity-base/react-organizations';

<IdentityProvider config={identityConfig}>
  <OrganizationsProvider apiBase={identityConfig.apiBase}>
    <App />
  </OrganizationsProvider>
</IdentityProvider>

The hooks exposed by the packages (useLogin, useOrganizations, useOrganizationMembers, etc.) orchestrate the full identity and organization flows. The Full Stack Integration Guide walks through setting up the Identity Host, microservices, and the SPA end-to-end.

4. Angular SPA

Install the Angular package (it uses @identity-base/client-core under the hood):

npm install @identity-base/angular-client

Register providers once (example app.config.ts):

import { provideIdentityClient } from '@identity-base/angular-client';

export const appConfig = {
  providers: [
    ...provideIdentityClient({
      apiBase: 'https://identity.example.com',
      clientId: 'spa-client',
      redirectUri: 'https://app.example.com/auth/callback',
      scope: 'openid profile email identity.api',
      tokenStorage: 'sessionStorage',
      autoRefresh: true,
    }),
  ],
};

To call organization endpoints, also install and register @identity-base/angular-organizations:

npm install @identity-base/angular-organizations

import { provideIdentityOrganizations } from '@identity-base/angular-organizations';

export const appConfig = {
  providers: [
    ...provideIdentityOrganizations({ apiBase: 'https://identity.example.com' }),
  ],
};

---

Running the Stack Locally

Prerequisites

• .NET 9 SDK
• PostgreSQL 16 (local or Docker)
• Optional: Mailjet or SendGrid credentials (or MailHog for local stubbing)
• Node.js 20 / npm 10 if you run the React clients

Configuration snapshot

Configuration snapshot

• Registration – profile fields, confirmation/reset URL templates (embed {token} + {userId}).
• MailJet / SendGrid – API keys, sender info, template IDs (confirmation/reset/MFA). Only required when the corresponding package is enabled.
• Mfa – issuer name, email/SMS toggles, Twilio credentials (if SMS is enabled).
• External providers – register OAuth/OIDC schemes in your host and map route keys using AddExternalAuthProvider(...).
• OpenIddict – client applications, scopes, server key provider (development, file-system, Azure Key Vault).
• Cors – allowed origins for browser clients.

Full option reference lives in docs/guides/getting-started.md. For the full architecture walk-through (Identity Host + microservices + React 19), see docs/guides/full-stack-integration-guide.md.

---

Testing & Tooling

• Run dotnet test Identity.sln (integration + unit suites) before submitting changes.
• The host project uses EF Core InMemory for tests; design-time factory enables CLI tooling.
• CI (GitHub Actions) builds, tests, and packs both packages for every push/PR. Manual releases are triggered via Run workflow with a semantic version.

---

Release & Distribution

1. Update the changelog’s “Unreleased” section.
2. Trigger the GitHub Actions workflow with the desired package-version (and optional publish-to-nuget flag). Artifacts named nuget-packages-<version> are produced.
3. Smoke test the packages locally before pushing to NuGet.
4. Tag the release and publish notes referencing the changelog.

Process details: Release Checklist. The Identity Host and sample APIs own their migrations and attempt to apply them at startup; ensure deployments allow those host-defined migrations to run (or execute them via your existing release automation) before Identity Base seeders kick in.

---

Support

• File issues and feature requests on GitHub.
• For security or conduct-related concerns, email opensource@amarettosoftware.com.
• Configuration guidance for email lives in docs/guides/mailjet-email-sender.md.

---

Contributing

• Review the Contributing Guide and Code of Conduct.
• Follow the Engineering Principles and Database Design Guidelines when proposing changes.
• Pair documentation updates with functional changes.

---

License

Identity Base is licensed under the MIT License.

---

Products Showcase

Product	Website	Company	Built with	Notes
Aurora	AuroraHQ.ai	Amaretto Software Labs	Identity.Base, @identity-base/react-client	Create high-fidelity product prototypes using AI.
Borealis	BorealisHQ.io	Amaretto Software Labs	Identity.Base, @identity-base/react-client	AI Sandboxes and infrastructure on demand.
Dawn	DawnHQ.ai	Amaretto Software Labs	Identity.Base, @identity-base/react-client	Team knowledge agent, get instant answers from your codebase, infrastructure, and connected systems — directly in Slack, Teams or Telegram.
Enclave	EnclaveHQ.io	Amaretto Software Labs	Identity.Base, @identity-base/react-client	Run protected apps in a secure environment via remote browser isolation.
FormFeeder	FormFeeder.io	Amaretto Software Labs	Identity.Base, @identity-base/react-client	Form handling for static websites with privacy and security by default.

---

Sponsors & Contributors

We are grateful to VA Software Solutions and Amaretto Software Labs for supporting the Identity Base project.