ADR-0004: SAML Certificate Rotation
- Status: Proposed
- Date: 2026-01-27
- Author: @digiwedge/engineering
Context
SAML IdPs rotate signing certificates periodically. If the IDP validates only a single certificate, tenants will experience login failures during rotation windows. We need a rotation strategy that allows overlap without compromising security.
Decision
Allow multiple active signing certificates per tenant and validate assertions against any active cert. Rotation is handled by updating metadata to include both the current and next certificates for a grace period.
Specific policy:
- Store an array
signingCertificates[]. - Accept any certificate marked
active: true. - Prefer the certificate marked
primary(or first in list) when creating SP-initiated requests (if signing is enabled). - Remove the old certificate only after a defined grace period (e.g., 7 days) or after successful validation events confirm the new cert is in use.
Consequences
Positive
- Seamless IdP rotations without downtime.
- Clear operational guidance for enterprise onboarding.
- Reduced support escalations during cert changes.
Negative
- Slightly broader trust window while two certs are active.
- Requires metadata refresh and monitoring to detect stale certs.
Alternatives Considered
| Alternative | Pros | Cons | Why not chosen |
|---|---|---|---|
| Single active cert only | Minimal config | Rotation causes outages | Not acceptable |
| Hard-coded grace period without metadata refresh | Simple | Can miss rotations | Operationally risky |
| Auto-trust any cert in metadata forever | Less work | Expands trust unnecessarily | Security risk |
Follow-ups
- Add monitoring for expired or soon-to-expire certs
- Emit audit events on cert changes
- Document rotation steps in ops runbook