About
- Core technologies
- Requirements
Getting started
Health checks
What's New
Migration guides
Changelog

Getting Started with IdentitySuite

1. Create a new empty project

Create a new Blazor Server .NET10 project

copy

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

2. Install the IdentitySuite NuGet Package

Run the following command in your project directory:

copy

dotnet add package IdentitySuite

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

Database Engine Notice

In version 2, the package for using MySQL as a database engine is currently not available. This is due to the fact that the Pomelo.EntityFrameworkCore.MySql dependency has not yet been updated to support .NET 10.

You can follow the progress of this update on the official GitHub issue: Pomelo MySQL .NET 10 support issue .

Important MySQL Requirements

Connection String: Must include:

copy


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

Without AllowUserVariables=true, Pomelo's caching system will fail

4. 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

5. 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 services
- OpenIddict service
- Authentication
- Entity Framework Core contexts
- 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
- Security headers

Complete Solution

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

Execution Order

Services registration (Add)
Database preparation (Setup)
Middleware activation (Use)

6. Build and Run the Application

Execute these commands in your project directory:

Build the project:

copy

dotnet build

Run the application:

copy

dotnet run

First Run Notice:

The initial startup will take longer as the system:
- Creates/updates the database (if configured)
- Generates encryption keys
- 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.

Complete Example Repository

For a fully configured solution including:

Best practice setup with logging (Serilog)
Environment-specific configurations
Sample authentication flows
Advanced scenarios

View Demo Project on GitHub