OpenIddict Certificates

Manage Built-in or Custom certificates used by Openiddict

Certificates

Certificates are essential components in IdentitySuite. They are used by OpenIddict to sign and encrypt tokens, ensuring their authenticity and confidentiality, and by DataProtection to protect sensitive application data. IdentitySuite provides two modes of certificate management: fully automated built‑in certificates and custom certificates. Built‑in certificates are self‑signed and automatically rotated by the system, offering a convenient option for development and testing environments. For production deployments, however, administrators should configure their own certificates, which can be loaded either from files or from the Windows Certificate Store depending on the hosting platform. This flexibility allows seamless integration with enterprise certificate lifecycle management and compliance requirements.

Important: Built-in certificates are intended for development and testing only. They should not be used in production environments. For production, always configure and load your own certificates via file or Windows Certificate Store.

Built-in certificates

IdentitySuite provides built-in self-signed certificates for signing and encryption. In the configuration UI, these are displayed as two cards showing the main certificate details. Each card includes a button to trigger manual rotation.

Rotation Process:

  1. The user clicks the Perform manual rotation button for signing or encryption certificate.
  2. After the configuration is saved, on the next application restart, IdentitySuite performs the rotation:
    • The current active certificate is moved to the expired folder.
    • A new self-signed certificate is generated and promoted as the active certificate.
  3. Expired certificates remain loaded and are used by OpenIddict and DataProtection to decrypt information until the grace period expires.

The grace period is calculated based on the RefreshTokenLifetime parameter, ensuring that tokens issued before rotation can still be validated until they naturally expire.

Custom Certificates

IdentitySuite allows administrators to configure custom certificates for signing and encryption, offering full control over certificate lifecycle and compliance. Certificates can be loaded from the local filesystem or from the Windows Certificate Store, and mixed modes are supported. Supported file formats include .pfx, .p12, .pem, .crt, .cer, and .der.

File-based Certificate Loading

  1. The user uploads the certificate file and provides a password if required.
  2. Clicking Validate triggers certificate loading and verification:
    • Format validation
    • Validity period (NotBefore, NotAfter)
    • Key length (minimum 2048 bits)
    • Presence of private key
  3. If valid, the certificate is re-encoded as a .pfx file and stored securely with a system-generated password for internal use.
  4. Once both signing and encryption certificates are validated, the configuration can be saved.
  5. On the next application restart, IdentitySuite rotates the active certificate:
    • The previous certificate is moved to the expired folder.
    • The newly uploaded certificate is promoted as active.

Certificate Store Loading

On systems that support it, certificates can also be loaded from the Windows certificate store by specifying:

  • StoreName (e.g., My, Root)
  • StoreLocation (e.g., LocalMachine, CurrentUser)
  • Thumbprint of the target certificate

Clicking Validate loads and verifies the certificate using the same criteria as file-based validation. Rotation does not move certificates within the store: instead, IdentitySuite tracks rotated certificates internally and continues to load them until the grace period expires.

Manual Rotation Process

Unlike built-in certificates, custom certificates require manual rotation. This means that administrators must explicitly upload a new certificate when the current one is nearing expiration or needs to be replaced. Once the new certificate is validated and the configuration is saved, IdentitySuite will promote it as the active certificate on the next application restart. The previously active certificate is marked as expired and retained for decryption purposes until the grace period expires. This ensures continuity for issued tokens and encrypted data. Rotation does not modify or remove certificates from the Windows Certificate Store; instead, IdentitySuite tracks rotated certificates internally and excludes them once they fall outside the grace window. Manual rotation provides full control over certificate lifecycle, but requires proactive monitoring and timely updates to maintain operational security.

Expiration Alerts

You can configure an email address and a threshold (in days) to receive alerts when a certificate is approaching expiration. This feature requires that email delivery settings are defined in the General configuration menu.

Quick Configuration Summary

Built-in Certificates

Self-signed, auto-rotated on restart

Not recommended for production
Grace period based on token lifetime

Custom Certificates

Uploaded manually or loaded from store

Supports mixed modes
Manual rotation via upload or store reference

Expiration Alerts

Email notifications for certificate expiry

Requires email setup in General menu
Threshold configurable in days

Copyright © 2025
Privacy policy Cookie policy