Installation | OpenIddict Key Rotation

Adding Key Rotation to OpenIddict

This guide outlines the steps to integrate the OpenIddict Key Rotation component into an existing OpenIddict server implementation. A completed example is available on GitHub.

Note: This component requires a license to operate. You can request a demo or contact us at sales@openiddictcomponents.com for purchasing information.

NuGet Installation

Install the Rsk.KeyRotation.OpenIddict package from NuGet in your OpenIddict project:

dotnet add package Rsk.KeyRotation.OpenIddict

Initial Configuration

To enable Key Rotation, call OpenIddictServerBuilder.AddKeyRotation within your OpenIddict configuration. This method accepts a delegate that provides an instance of OpenIddictKeyRotationBuilder for configuring the component. Below is a basic example:

.AddServer(openIddictBuilder =>
{
    ...

    openIddictBuilder.AddKeyRotation(keyRotationBuilder =>
    {
        keyRotationBuilder.UseEntityFrameworkCore()
            .AddKeyRotationDbContext(dbBuilder =>
            {
                // Example using the SQL Server provider; you may use any supported EF Core provider.
                // The MigrationsAssembly should match the current project’s assembly name.
                // If using a Startup class, you can retrieve this using:
                // typeof(Startup).GetTypeInfo().Assembly.GetName().Name
                dbBuilder.UseSqlServer("***ConnectionString***", opt => 
                    opt.MigrationsAssembly("CurrentProject.Assembly.Name"));
            });

        keyRotationBuilder.AddLicense("DEMO", "***LicenseKey***");
    });

    ...
});

Check for Static Signing Keys

Key Rotation inserts its keys into the OpenIddictServerOptions SigningCredentials list, placing active keys first, followed by any existing keys, and finally its inactive keys. If your application defines high-priority static RSA or ECDSA keys, these may override the dynamic keys generated by Key Rotation.

For more details, see OpenIddict signing key prioritisation.

Setting Up the Database with EF Core

The Key Rotation component requires two database tables. You can use Entity Framework Core tools to generate and apply the necessary migrations, or apply them manually using our provided SQL script.

Prerequisites

Install the Microsoft.EntityFrameworkCore.Design package:

dotnet add package Microsoft.EntityFrameworkCore.Design

Generate the migration files:

dotnet ef migrations add KeyRotation_Initial --context KeyRotationDbContext

Apply the migration to the database:

dotnet ef database update --context KeyRotationDbContext

Previous Next