In the world of OpenID Connect and OAuth 2.0, signing keys are the foundation of trust. They ensure that tokens issued by your identity provider (IdP) are authentic and haven't been tampered with. Managing these keys properly, whether manual or automatically, is an important aspect of running a secure IdentityServer implementation.
This post explores the technical rationale behind key rotation, how Duende IdentityServer handles it, and best practices for implementing production-grade identity solutions.
Understanding the Role of Signing Keys
At its core, an OpenID Connect provider like Duende IdentityServer issues JSON Web Tokens (JWTs) that are cryptographically signed. While a JWT can technically be created in an unsigned format, this poses a security risk and is strongly discouraged: it makes the token untrustworthy and vulnerable to tampering. In other words: for any practical and secure use, a JWT must be signed.
When a client application or API receives a signed token, it can validate the signature using the public key published at the JSON Web Key Set (JWKS) endpoint.
The signing process relies on asymmetric cryptography, typically using RSA or ECDSA algorithms. Duende IdentityServer holds the private key and uses it to sign tokens, while clients and APIs use the corresponding public key to verify signatures. This separation provides a powerful security model: the private key never leaves your identity provider (IdP), yet any party can verify token authenticity.
However, this security model comes with a critical responsibility: the private key must remain secure throughout its lifecycle. If a private key is compromised, an attacker could forge tokens, impersonating any user and accessing protected resources.
Beyond the threat of compromise, there are other important reasons to rotate keys regularly: adherence to security policies and compliance requirements, alignment with cryptographic best practices as algorithms and key strengths evolve, and maintaining operational readiness for emergency key changes.
Why Key Rotation Matters
Rotating keys might seem like unnecessary complexity. It is a good and recommended practice to generate new signing keys and phase out old ones. Key rotation serves several purposes:
Limiting Exposure Window: Even with perfect operational security, keys can be compromised through various attack vectors—memory dumps, insider threats, software vulnerabilities, or side-channel attacks. By rotating keys regularly, you limit the time window during which a compromised key can be exploited. If a key is rotated monthly and later discovered to have been compromised, the impact is limited to that month's exposure.
Meeting Compliance Requirements: Many security frameworks and compliance standards (such as PCI DSS, NIST guidelines, and various data protection regulations) mandate periodic key rotation as a security best practice. Automated rotation helps organizations meet these requirements without manual intervention.
Cryptographic Best Practices: As computational power increases, the effective security of cryptographic keys diminishes over time. Regular rotation ensures that keys remain within their intended operational lifetime and that older, potentially weaker keys are retired before they become vulnerable.
Operational Resilience: A well-implemented rotation strategy means your infrastructure is designed to handle key transitions smoothly. This resilience pays dividends when you need to perform emergency key rotation due to a suspected compromise.
The Challenge of Manual Key Rotation
In Duende IdentityServer, signing keys can be rotated manually or automatically. While manual key rotation is a viable option, it comes with a number of drawbacks:
Human error: Manual processes are inherently risky. Forgetting to publish a new public key or prematurely removing an old one could break authentication across an entire system.
Coordination complexity: In distributed environments you have to make sure all parties have the updated keys requires careful coordination and timing. While it's technically possible to announce multiple keys in the JWKS endpoint to smooth the transition, manually coordinating the timing of adding new keys, switching to use them for signing, and removing old keys requires careful orchestration.
Neglect: Because manual rotation is, well, manual, it often gets postponed or skipped entirely, leaving keys in use for years and increasing security risk.
Duende IdentityServer Automatic Key Rotation
Duende IdentityServer addresses the challenges of manual key rotation with its automatic key management system.
When enabled, IdentityServer automatically generates new signing keys at specified intervals. The key management infrastructure handles the entire lifecycle without administrator intervention. You can configure the rotation interval based on your security requirements: some organizations rotate weekly, others monthly or quarterly.
IdentityServer also handles key rotation gracefully. When a new key is generated, it doesn't immediately replace the old key. Instead, both keys coexist and overlap for a configured period.
First, a new signing key is generated and added to the JWKS endpoint, but it's not yet used for signing. This gives clients and APIs time to discover and cache the new public key.
After an announcement period (often 24-48 hours), IdentityServer begins using the new key for signing new tokens while the old key remains valid for verification.
The old key continues to be published in the JWKS endpoint for a retirement period, allowing tokens signed with it to remain valid until they naturally expire. This prevents disruption to users with existing sessions.
Only after both the announcement and retirement periods have elapsed is the old key fully removed from the system.
---
config:
theme: default
gantt:
useWidth: 800
useMaxWidth: false
---
gantt
title 90 Day Key Rotation Schedule per Signing Algorithm
todayMarker off
section RS256
Signing :active, rsa_s, 2025-01-01, 76d
Retire :rsa_r, after rsa_s, 14d
Delete :crit, rsa_d, after rsa_r, 1d
Announce :rsa_na, 2025-03-03, 14d
Signing :active, rsa_ns, after rsa_na, 62d
Retire :rsa_nr, after rsa_ns, 14d
Delete :crit, rsa_nd, after rsa_nr, 1d
section ES256
Signing :active, es_s, 2025-01-01, 76d
Retire :es_r, after es_s, 14d
Delete :crit, :es_d, after es_r, 1d
Announce :es_na, 2025-03-03, 14d
Signing :active, es_ns, after es_na, 62d
Retire :es_nr, after es_ns, 14d
Delete :crit, es_nd, after es_nr, 1d
This overlapping approach ensures zero-downtime rotation. At any given moment, the system can verify tokens signed with multiple keys, preventing authentication failures during transitions.
Operational Storage Considerations
For production deployments, especially those running multiple IdentityServer instances behind a load balancer, key storage becomes critical. Duende IdentityServer supports various key storage mechanisms including:
- File System Storage: Suitable for single-instance deployments or when using shared storage.
- Database Storage: Enables key sharing across multiple IdentityServer instances using Entity Framework Core with support for SQL Server, PostgreSQL, MySQL, and SQLite.
- Custom Implementations: The extensible architecture allows integration with enterprise key management systems, Hardware Security Modules (HSMs), or cloud key vaults.
Database storage is particularly important for high-availability scenarios. All IdentityServer instances read from the same key store, ensuring they use identical keys for signing and validation. The rotation process is coordinated through database-level locking mechanisms, preventing race conditions when multiple instances might try to generate new keys simultaneously.
Implementing Automatic Key Rotation
Setting up automatic key rotation in Duende IdentityServer can be done in startup code. You'll configure the key management system through the KeyManagement options when registering adding IdentityServer:
builder.Services.AddIdentityServer(options =>
{
// new key every 30 days
options.KeyManagement.RotationInterval = TimeSpan.FromDays(30);
// announce new key 2 days in advance in discovery
options.KeyManagement.PropagationTime = TimeSpan.FromDays(2);
// keep old key for 7 days in discovery for validation of tokens
options.KeyManagement.RetentionDuration = TimeSpan.FromDays(7);
// don't delete keys after their retention period is over
options.KeyManagement.DeleteRetiredKeys = false;
});
You'll want to fine-tune the rotation parameters based on your organization's security policies, compliance requirements, and token lifetime configurations:
RotationInterval: How often new keys are generatedPropagationTime: The announcement period before a new key is used for signingRetentionDuration: How long retired keys remain valid for verificationDeleteRetiredKeys: Do you want to delete retired keys from storage?
Generally, your key retirement age should exceed your longest token lifetime. If you issue refresh tokens valid for 30 days, your retirement period should be at least 30 days to ensure those tokens remain verifiable throughout their lifetime.
What About The Client?
While server-side rotation is automatic, ensure your client applications properly handle key rotation.
Clients should:
- Cache JWKS responses but respect cache control headers
- Retry token validation with refreshed keys when signature validation fails
- Avoid hardcoding key IDs or public keys
Don't wait for your first production rotation. In your staging environment, consider more aggressive rotation intervals (e.g., daily) to regularly exercise the rotation logic and ensure your clients handle key changes gracefully.
Conclusion
Automatic key rotation in Duende IdentityServer puts you in control of balancing security and operational convenience. By automating a critical security practice, it removes the burden from administrators while ensuring consistent use of cryptographic best practices.
The overlapping key validity approach is very convenient here as well. Rather than forcing a hard cutover that might break existing sessions, IdentityServer gracefully transitions between keys.
Configuring automatic key rotation is a foundational element of a secure, production-ready OpenID Connect implementation that improves your security posture and at the same time gives operational peace of mind.
For more detailed information on implementing and configuring key management in Duende IdentityServer, consult the documentation about Key Management, which covers advanced scenarios, custom storage implementations, and troubleshooting guidance.
As always, you can use the comments below to discuss.