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

Migration Guides

Step-by-step instructions for upgrading between IdentitySuite versions

From 1.x to 2.0

IdentitySuite v2.0 introduces a major breaking change: primary keys in tables defined in IdentityUser and IdentityServer schemas have been redefined from int to Guid (GuidV7). This schema redesign requires a fresh installation with a new database. To support data migration, an official tool is provided to copy existing records from your previous IdentitySuite database into the new schema. While migration is not mandatory, the tool offers a straightforward way to preserve user and configuration data when upgrading to version 2.0.

In version 1.x, integer keys were originally chosen with a performance‑first mindset, aiming at simplicity and speed in relational operations. However, evolving requirements have made security and compliance more critical: non‑predictable identifiers strengthen protection against enumeration attacks, ensure stronger GDPR alignment, improve uniqueness guarantees in distributed environments, and better align with modern identity management practices.

Before You Begin

Backup your existing IdentitySuite 1.x database

Migration Steps

1
Configure Database Settings

From the UI, navigate to Configuration Settings → General. Update the database name in the connection string, enable the Initialize database switch, and save changes.
2
Update NuGet Packages

Upgrade the following packages to version 2.0:
- IdentitySuite
- IdentitySuite.EntityFrameworkCore (for your chosen database provider)
Before starting version 2 for the first time, make sure to back up and then delete the Certificates folder. Version 2 will automatically generate new certificates that are fully compatible with the new system.

In version 2 there are important changes to some namespaces. Please update your code accordingly:
- IdentitySuite.Core.Models.Endpoints → IdentitySuite.Abstractions.Models.Endpoints
- IdentitySuite.Core.Services.Interfaces → IdentitySuite.Abstractions.Interfaces
- IdentitySuite.Core.Data.Entities → IdentitySuite.Abstractions.Data.Entities
These changes reflect the new structure introduced in version 2, where common contracts and models have been moved under the IdentitySuite.Abstractions namespace.

Configure Certificates

Ensure your IdentitySuiteSettings.[Environment].json contains the following section (inside OpenIddictOptions):

copy


"SecuritySettings": {
  "UseDataProtection": true,
  "EnableAccessTokenEncryption": true,
  "Certificates": {
    "Mode": "Builtin",
      "Signing": {
        "ForceRotation": false,
        "Source": "FileSystem",
        "Thumbprint": "",
        "StoreLocation": "CurrentUser",
        "StoreName": "My"
      },
      "Encryption": {
        "ForceRotation": false,
        "Source": "FileSystem",
        "Thumbprint": "",
        "StoreLocation": "CurrentUser",
        "StoreName": "My"
      },
      "ExpiredCertificates": [],
      "NotifyEmail": "",
      "CertificateExpiryAlertThresholdDays": 7
  }
}

4
Run Application

Start your application - the new database will be initialized automatically

Run Data Migration Tool

Optionally use the official console application IdentitySuite Migration Tool to migrate data from the old database to the new one. Configure appsettings.json with source and target connection strings:

copy


{
    "SourceDatabase": {
        "Provider": "SqlServer",
        "ConnectionString": "Data Source=localhost;Initial Catalog=IdentitySuiteDb;Integrated Security=True;Trust Server Certificate=True"
    },
    "TargetDatabase": {
        "Provider": "SqlServer",
        "ConnectionString": "Data Source=localhost;Initial Catalog=IdentitySuiteDb.V2;Integrated Security=True;Trust Server Certificate=True"
    }
}

Execute the program to transfer all data into the v2.0 schema.

From 1.0.x to 1.1.0

Important database changes require following these steps

Before You Begin

Backup your database

Migration Steps

1
Enable Migrations

In your application configuration, activate the Apply migrations option located in the Database settings section of the General menu
2
Update NuGet Packages

Upgrade the following packages to version 1.1.0:
- IdentitySuite
- IdentitySuite.EntityFrameworkCore (for your chosen database provider)

Configure Rate Limiting

Ensure your IdentitySuiteSettings.[Environment].json contains the following section (typically after Cors):

copy


"RateLimiting": {
  "Enabled": false,
  "EnableMetrics": false,
  "Policies": {
    "oidc-critical-endpoints": {
      "PermitLimit": 20,
      "SegmentsPerWindow": 10,
      "Window": "00:05:00",
      "QueueLimit": 0,
      "AutoReplenishment": true
    },
    "oidc-default-endpoints": {
      "PermitLimit": 60,
      "SegmentsPerWindow": 10,
      "Window": "00:05:00",
      "QueueLimit": 0,
      "AutoReplenishment": true
    },
    "global-endpoints": {
      "PermitLimit": 100,
      "SegmentsPerWindow": 5,
      "Window": "00:05:00",
      "QueueLimit": 0,
      "AutoReplenishment": true
    }
  },
  "WhitelistedIPs": [],
  "BlacklistedIPs": []
}

4
Run Application

Start your application - the migrations will be applied automatically