Skip to main content

Identity

Identity is the authentication and account-management application of the system. It issues OpenID Connect tokens, handles browser sign-in flows, manages user credentials and two-factor authentication, and provides integration points for trusted backend services.

It is intentionally separated from App Main because authentication has a clear technical boundary. Keeping it isolated makes the authentication surface easier to reason about, allows it to be deployed independently, and prevents product-domain logic from being mixed with security concerns.

API​

The Identity API is an ASP.NET Core application built on ASP.NET Core Identity and OpenIddict. OpenIddict provides the OpenID Connect server surface used by the main web application and backend service clients.

The application supports:

  • Authorization Code Flow with PKCE for the main frontend.
  • Refresh Token Flow for browser session continuity.
  • Client Credentials Flow for service-to-service authentication.
  • Access tokens, identity tokens, refresh tokens, and application cookies.

Access tokens grant access to protected APIs and carry claims such as user identity, roles, scopes, and organization context. Identity tokens represent the authenticated user in the OpenID Connect flow. Refresh tokens and application cookies keep browser sessions usable without forcing the user to re-authenticate on every interaction.

Authorization Code Flow with PKCE is used for the browser client because it is the standard secure flow for public clients. PKCE protects the authorization-code exchange from interception and lets the frontend authenticate without storing a client secret.

Responsibilities​

Identity owns the technical authentication lifecycle and identity-specific state. This includes:

  • sign-in, sign-out, password change, password reset, and email confirmation;
  • user activation/deactivation and lock/unlock flows;
  • two-factor authentication, two-factor settings, and two-factor method setup;
  • token issuing and validation;
  • Google external login and external registration flows;
  • user and organization synchronization from App Main events;
  • email and SMS delivery for identity workflows.

The service stores identity users, password hashes, roles, organization references, email confirmation state, lockout state, external login references, two-factor settings, and OpenIddict token/application data.

Integration API​

Identity exposes public account endpoints for browser authentication flows and private endpoints for trusted backend integrations. Private access is protected with application-specific scopes issued through OpenIddict client credentials.

Synchronous integration is handled through REST endpoints. Asynchronous synchronization is handled through messaging. This lets Identity operate as a standalone service while still participating in the wider application ecosystem.

Event Integration​

Identity is integrated with the rest of the system through MassTransit messaging. It consumes application events for users and organizations and updates identity state accordingly. It also publishes identity workflow events, such as requests to send invite, confirmation, and password notification emails.

This keeps Identity independently deployable while still synchronizing authentication state with App Main.

Project Structure​

The src/app-identity folder contains three projects:

  • StarterKit.App.Identity - the ASP.NET Core Identity application, OpenIddict configuration, endpoints, data access, messaging consumers, email/SMS services, and token services.
  • StarterKit.App.Identity.Migrations - EF Core migrations for Identity and OpenIddict storage.
  • StarterKit.App.Identity.UI - the Preact account UI hosted by the Identity application.

The backend application keeps a compact project structure because Identity has a focused technical responsibility and is primarily infrastructure-oriented. We avoid splitting it into additional layers without a clear need, which keeps the service easier to understand and maintain. It is the authentication boundary and identity integration point for the rest of the system.

Client​

The client-side application is built with Preact and TypeScript. It provides the account-facing UI for login, MFA, password recovery, email confirmation, unlock flows, redirects, errors, and language switching.

Preact is used because the Identity UI is intentionally small and focused. It provides the component model needed for account screens while keeping the client lightweight. TypeScript keeps request models, form values, and route-driven flows explicit and maintainable.

The UI is hosted by the Identity application and focuses only on authentication and account recovery workflows, while the main product UI lives in App Main.