Getting Started with IdentitySuite

From an empty project to a running instance in four steps

1. Project Setup

1.1 Create a new empty project

Create a new Blazor Server .NET10 project

copy
dotnet new blazor -o IdentitySuite --empty --interactivity Server --all-interactive

1.2 Install the IdentitySuite NuGet Package

Run the following command in your project directory:

copy
dotnet add package IdentitySuite

1.3 Choose and Install a Database Provider Package

IdentitySuite supports multiple database backends. Install one of the following providers:

SQL Server (Recommended for Windows/Enterprise)

copy
dotnet add package IdentitySuite.EntityFrameworkCore.SqlServer

PostgreSQL (Cross-platform, Open Source)

copy
dotnet add package IdentitySuite.EntityFrameworkCore.PostgreSql

MySQL (Compatible with MySQL/MariaDB)

copy
dotnet add package IdentitySuite.EntityFrameworkCore.MySql

Install only one provider package. If more than one ends up referenced (for example after switching providers without removing the old package), IdentitySuite picks between them automatically and logs a warning listing every candidate found. To force a specific one, set Database:ProviderAssemblyName in identitySuiteSettings.[Environment].json to the assembly name, e.g. "IdentitySuite.EntityFrameworkCore.SqlServer". This setting is JSON-only; there is no UI toggle for it.

MySQL Provider Notice

Starting from version 2.4.0, IdentitySuite replaces the Pomelo.EntityFrameworkCore.MySql provider with the Microting.EntityFrameworkCore.MySql. This change was necessary because Pomelo has not yet released a version compatible with .NET 10.

The Microting provider is a community-maintained fork of Pomelo that enables .NET 10 support. Although our internal testing indicates that it works correctly with IdentitySuite, this should be considered a temporary and experimental solution until the official Pomelo package is updated.

We will continue monitoring the progress of the official Pomelo release and may revert to it once full .NET 10 compatibility is available.

You can track the status of the official update here: Pomelo MySQL .NET 10 support issue .

Important MySQL Requirements

The MySQL connection string must include AllowUserVariables=true, otherwise Pomelo's caching system will fail:

copy

"ConnectionStrings": {
    "MySqlConnection": "Server=localhost;Database=IdentitySuiteDb;Uid=root;Pwd=your_password;AllowUserVariables=true"
}

2. Configuration

2.1 Build the Application

Build the application to automatically create the default IdentitySuite folder and copy all generated configuration files into it.

copy
dotnet build

2.2 Configure the server

After installation, edit the configuration file found in the IdentitySuite directory located in the root of your project:

IdentitySuiteSettings.{environment}.json

Where {environment} matches your current environment (Development, Production, etc.).

Important:

  • Set the ConnectionStrings section according to your database provider
  • Ensure the configuration matches the NuGet package you installed (SQL Server, PostgreSQL, or MySQL)
  • Set "Initialize": true to enable automatic database initialization and migrations

Initializing outside Development

Initialize: true drops and recreates the database. Outside the Development environment, IdentitySuite refuses to start with this flag enabled unless you also set the environment variable IDENTITYSUITE_CONFIRM_DB_INITIALIZE=true on the process running the application. This is a deliberate safeguard against an Initialize: true left over in a config file being applied to a production database by accident. It only needs to be set for the first run — the application resets the flag to false in the settings file once initialization succeeds, so leaving the environment variable set afterwards has no further effect.

3. Configure Program.cs

Update your Program.cs file with the following code:

copy

using IdentitySuite;

var builder = WebApplication.CreateBuilder(args);

// 1. Registers all required services (authentication, authorization, etc.)
builder.AddIdentitySuiteServices();

var app = builder.Build();

// 2. Creates/updates the database based on configuration
await app.SetupIdentitySuiteDbAsync();

// 3. Enables all runtime services (authentication, routing, etc.)
app.UseIdentitySuiteServices();

await app.RunAsync();

Method Breakdown

AddIdentitySuiteServices()

Registers all necessary services including Blazor, OpenIddict, Authentication, Entity Framework Core contexts and Identity core services.

SetupIdentitySuiteDbAsync()

Handles database operations based on IdentitySuiteSettings.json: applies pending migrations, creates initial tables. Requires "Initialize": true.

UseIdentitySuiteServices()

Configures the complete middleware pipeline: Authentication, Authorization, Routing, Session management and Security headers.

Complete Solution

IdentitySuite handles all standard Blazor Server setup — no additional services or middleware needed in Program.cs.

Execution Order

  1. Services registration (Add)
  2. Database preparation (Setup)
  3. Middleware activation (Use)

4. Run the Application

Execute this command in your project directory:

copy
dotnet run

First Run Notice:

The initial startup will take longer as the system creates/updates the database (if configured), generates encryption keys and seeds initial data. Subsequent runs will be significantly faster.

Default Admin Account:

On first run, IdentitySuite creates the administrator account admin@IdentitySuite.local with a random password generated for that installation. It is not a fixed, published value.

Where to find it: the generated password is printed once in the application's startup log, at Warning level, right after the account is created — look for a line mentioning Generated initial password for seed user. It will not be shown again after that run, so record it immediately.

Security Note: Change this password immediately after first login.

Resources

Complete Guide

A comprehensive, step-by-step guide that takes you from zero to a production-ready OpenID Connect authentication server in under an hour. You'll learn how to deploy a secure OIDC server, configure SQL Server, PostgreSQL, or MySQL, master certificate management and token security, understand OAuth 2.0 and OpenID Connect architecture, register and configure SPA client applications, and implement Authorization Code + PKCE flows.

Read the Complete Guide

Complete Example Repository

A fully configured example solution that follows industry best practices, including best-practice setup with Serilog logging, environment-specific configuration files, sample authentication flows, advanced scenarios ready to explore, and a real-world foundation to accelerate your IdentitySuite integration.

View Demo Project on GitHub