Getting Started with IdentitySuite

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

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

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 Credentials:

Username Password
admin@IdentitySuite.local P@ssw0rd1234!

Security Note: Change these credentials 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