Objective
A signing certificate is a crucial component in securing SAML communications, it is used to ensure authentication requests and responses are trusted. For security reasons, a signing certificate is periodically rotated before its expiration. A single key for the Signing Certificate of an IDP is used by Access Management 2.0, so when the IDP begins using a new certificate, access will be denied until the new key is updated in Access Management.
This document describes how to change this key in Access Management.
Purpose
Following is a structured explanation of SAML Signing Certificates/Keys and how to update Keycloak’s SAML Identity Provider (IdP) configuration when Okta rotates its SAML signing certificate.
SAML Signing Certificates / Keys – Concept
1. Why This is Important
In a SAML 2.0 authentication flow:
- The Identity Provider (IdP) (e.g., Okta) digitally signs the SAML assertions using a private key.
- The Service Provider (SP) (e.g., Keycloak as a SAML IdP for another application) verifies this signature using the corresponding public certificate.
- This prevents tampering, ensures message authenticity, and verifies the identity of the sender.
2. Key Concepts
| Element | Purpose |
|---|---|
| Signing Key | Private key used by the IdP (Okta) to sign assertions |
| Certificate | X.509 cert (containing the public key) used by SP (Keycloak) to verify signature |
| Metadata File | Contains entity ID, endpoints, supported bindings, and certs |
Why Rotation Happens
- Okta periodically rotates signing certificates to comply with security best practices.
- After rotation:
- Old cert is deprecated (or valid temporarily).
- New cert must be trusted by Keycloak; otherwise, signature verification will fail and SAML login will break.
Different Rotation Scenarios -
1 - IDPs that do no support more than one Key
- Create the new Signing Certificate and Key in your IDP (logins start failing in Manhattan Solutions)
- Login to the Access Management to update the Key (logins succeed again)
2 - IDPs that support multiple Keys
- Generate the new Signing Certificate and Key in your IDP (but do not activate it)
- Configure the new Signing Key in Access Management (active key in IDP is old - logins start failing)
- activate the new Key in your IDP (now Keycloak allows login again)
Before you begin
You will need access to the AM 2.0 Admin Console using the System Management account (a non IDP based super user provided with your subscription.)
Steps
Follow these steps below to rotate a SAML signing key with your IdP -
Log in to the AM 2.0 Admin Console. Select the maactive realm.
Note: If you have Restricted Admin Access on AM 2.0, then use the URL:
https://<stack_name>-auth.<domain_name>/auth/admin/maactive/console/The Admin Console will appear as shown below:
Click on the Identity providers tab on the left panel and select the IdP provider whose signing certificate is to be changed.
Scroll down and toggle IdP configurations For the SP to be able to validate the signatures, the Want Assertions Signed and Validate Signatures toggle fields must be switched ON.
Update the IdP certificate on the SP side. Clear out the certificate that is already present on AM 2.0 from the field Validating X509 certificates. Paste the new X509 certificate to use it with the IdP.
Hit the Save button at the bottom.
You should be able to successfully set a new IdP signing certificate on the SP side.
Author
Shipra Choudhary: Tech Lead, Application Security, ActivePlatform™, R&D. e;, R&D._