Key Rotation Builder

Key Rotation for OpenIddict provides a builder API for registering services and configuring their behaviour. To use it, call the .AddRskKeyRotation extension method on the OpenIddictServerBuilder and supply a configuration action. This action allows you to customize the Key Rotation settings.

Fluent API

Key Rotation has a fluent API for configuring its behaviour, so if your modifications are minimal, you can make use of it. Alternatively, there is the option to configure the options object directly with the .ConfigureKeyRotation method.

Registering the License

When using OpenIddict Key Rotation, you must register a valid license. This can be done using the .AddLicense method on the Key Rotation builder. This method sets the Licensee and LicenseKey values in the options object.

services.AddServer(openIddictBuilder => {
    // Existing config ...
    openIddictBuilder.AddRskKeyRotation(keyRotationBuilder =>
    {
        // Other config ...

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

Configuring Key Generation

By default, Key Rotation generates an RSA key with a length of 2048 bits. You can change this configuration. Currently, Key Rotation supports generating asymmetric keys, RSA and ECDSA. The following methods are available:

.DisableSigningKeyManagement()

Sets EnableSigningKeyRotation to false, will be overridden if subsequent call to .UseXForSigning() builder methods are called where 'X' is the key type.

services.AddServer(openIddictBuilder => {
    // Existing config ...
    openIddictBuilder.AddRskKeyRotation(keyRotationBuilder =>
    {
        // Other config ...

        keyRotationBuilder
            // Existing Fluent API Calls ...
            .DisableSigningKeyManagement();
    });
});

.DisableEncryptionKeyManagement()

Sets EnableEncryptionKeyRotation to false, will be overridden if subsequent call to .UseXForEncryption() builder methods are called where 'X' is the key type.

services.AddServer(openIddictBuilder => {
    // Existing config ...
    openIddictBuilder.AddRskKeyRotation(keyRotationBuilder =>
    {
        // Other config ...

        keyRotationBuilder
            // Existing Fluent API Calls ...
            .DisableEncryptionKeyManagement();
    });
});

.UseRsaForSigning([optional] int keySize)

The keySize parameter defaults to 2048.
Sets EnableSigningKeyRotation to true and sets SigningKeyType to SupportedRskKeys.Rsa and sets the RsaKeySize to the provided value.

services.AddServer(openIddictBuilder => {
    // Existing config ...
    openIddictBuilder.AddRskKeyRotation(keyRotationBuilder =>
    {
        // Other config ...

        keyRotationBuilder
            // Existing Fluent API Calls ...
            .UseRsaForSigning(/* optionally specify a size `int` */);
    });
});

.UseEcdsaForSigning([optional] EcCurveType curveType)

The curveType parameter defaults to Ps256.
Sets EnableSigningKeyRotation to true and sets SigningKeyType to SupportedRskKeys.Ecdsa and sets the EcCurveType to the provided value.

services.AddServer(openIddictBuilder => {
    // Existing config ...
    openIddictBuilder.AddRskKeyRotation(keyRotationBuilder =>
    {
        // Other config ...

        keyRotationBuilder
            // Existing Fluent API Calls ...
            .UseEcdsaForSigning(/* optionally specify a curve `EcCurveType` */);
    });
});

.UseRsaForEncryption([optional] int keySize)

The keySize parameter defaults to 2048. Sets EnableEncryptionKeyRotation to true and sets EncryptionKeyType to SupportedRskKeys.Rsa and sets the RsaKeySize to the provided value.

services.AddServer(openIddictBuilder => {
    // Existing config ...
    openIddictBuilder.AddRskKeyRotation(keyRotationBuilder =>
    {
        // Other config ...

        keyRotationBuilder
            // Existing Fluent API Calls ...
            .UseRsaForEncryption(/* optionally specify a key size `int` */);
    });
});

.UseAesForEncryption([optional] int keySize)

The keySize parameter defaults to 256. Sets EnableEncryptionKeyRotation to true and sets EncryptionKeyType to SupportedRskKeys.Aes and sets the AesKeySize to the provided value.

services.AddServer(openIddictBuilder => {
    // Existing config ...
    openIddictBuilder.AddRskKeyRotation(keyRotationBuilder =>
    {
        // Other config ...

        keyRotationBuilder
            // Existing Fluent API Calls ...
            .UseAesForEncryption(/* optionally specify a key size `int` */);
    });
});

.SetSigningKeyLifespan(int publishDays, int activeDays, int retiredDays)

Sets SigningKeyPublishTime to TimeSpan generated from the value of publishDays, SigningKeyLifetime to TimeSpan generated from the value of activeDays, and SigningKeyRetirementTime to TimeSpan generated from the value of retiredDays.

services.AddServer(openIddictBuilder => {
    // Existing config ...
    openIddictBuilder.AddRskKeyRotation(keyRotationBuilder =>
    {
        // Other config ...

        keyRotationBuilder
            // Existing Fluent API Calls ...
            .SetSigningKeyLifespan(4, 60, 4);
    });
});

.SetEncryptionKeyLifespan(int activeDays, int retiredDays)

Sets EncryptionKeyLifetime to TimeSpan generated from the value of activeDays, and EncryptionKeyRetirementTime to TimeSpan generated from the value of retiredDays.

services.AddServer(openIddictBuilder => {
    // Existing config ...
    openIddictBuilder.AddRskKeyRotation(keyRotationBuilder =>
    {
        // Other config ...

        keyRotationBuilder
            // Existing Fluent API Calls ...
            .SetEncryptionKeyLifespan(60, 4);
    });
});

Manually Setting Options

You can also manually configure the options using .ConfigureKeyRotation(Action<KeyRotationOptions>). This is useful if you prefer to define all settings in one place, including timing-related values:

services.AddServer(openIddictBuilder => {
    // Existing config ...
    openIddictBuilder.AddRskKeyRotation(keyRotationBuilder =>
    {
        // Other config ...
        keyRotationBuilder.ConfigureKeyRotation(conf =>
        {
            // Licensing
            conf.Licensee           = "DEMO";
            conf.LicenseKey         = "***LicenseKey***";

            // Key Generation Settings
            conf.SigningKeyType     = SupportedKeyTypes.Rsa;
            conf.EncryptionKeyType  = SupportedKeyTypes.Rsa;
            conf.AesKeySize         = 256;
            conf.RsaKeySize         = 2048;

            // Timing Settings
            conf.CheckInterval      = 3600;

            // Lifetime Settings
            conf.SigningKeyPublishTime     = TimeSpan.FromDays(10);
            conf.SigningKeyLifetime        = TimeSpan.FromDays(200);
            conf.SigningKeyRetirementTime  = TimeSpan.FromDays(15);

            conf.EncryptionKeyLifetime        = TimeSpan.FromDays(200);
            conf.EncryptionKeyRetirementTime  = TimeSpan.FromDays(15);
        });
    });
});