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. Build the Application

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

Build the project:

copy
dotnet build

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

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

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

7. Run the Application

Execute this commands in your project directory:

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 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 authentication 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
  • Implement Authorization Code + PKCE flows
Read the Complete Guide

Complete Example Repository

A fully configured example solution that follows industry best practices and includes:

  • Best-practice setup with Serilog logging
  • Environment-specific configuration files
  • Sample authentication flows
  • Advanced scenarios ready to explore
  • A real-world foundation to accelerate your IdentitySuite integration
View Demo Project on GitHub