Certificate rotation uses a number of inherent capabilities which enable it to deploy new certificates to replace current certificates in enabled connections.
Certification rotation is a per-certificate configuration. When certificate rotation is enabled for a certificate and a new certificate using new key pairs becomes available, PingFederate deploys the new certificate to all enabled connections that use the original certificate. The actions taken by PingFederate vary depending on the role of the certificate.
Although optional, you can turn on notifications for certificate events in PingFederate notifies the configured recipient when a new certificate is available and when it is activated. Depending on the role of the certificate, you can update your partner accordingly.. When configured,
When the Creation Buffer threshold is reached, a new certificate is created. For all web browser single sign-on (SSO) (SAML and WS-Federtion) connections using the same signing certificate, PingFederate starts including the new certificate (along with the current certificate) in their metadata. PingFederate keeps using the current certificate for signing until the remaining lifetime of the current certificate reaches the Activation Buffer threshold, at which point PingFederate starts signing with the new certificate and removes the previous certificate from the metadata.
To prevent SSO outages, partners must update their connections to use the new certificate to verify digital signatures before the Activation Buffer threshold is reached.
When a new certificate is made available, PingFederate performs the following tasks for all SAML 2.0 connections using the same decryption key:
- Pushes the current decryption key from primary to secondary
- Places the new certificate as the primary decryption key
- Updates the decryption key with the new certificate in the metadata
- Starts using the new decryption key to decrypt inbound messages. If the primary decryption key fails, PingFederate fails over to the secondary decryption key
When the remaining lifetime of the current certificate reaches the Activation Buffer threshold, the secondary decryption key is removed from the SAML 2.0 connections.
When PingFederate is configured to generate notifications for certificate events, PingFederate also notifies the configured recipient when the existing RSA decryption key is about to expire.
For XML decryption keys, PingFederate only supports the RSA key algorithm. When EC (elliptic curve) is selected as the Key Algorithm value on the Certificate Rotation tab, PingFederate does not update the SAML 2.0 connections and their metadata.
To prevent SSO outages, partners must update their connections to use the new certificate to encrypt messages before the Activation Buffer threshold is reached.
Federation metadata for Browser SSO connections
PingFederate updates the metadata for the applicable web browser SSO connections as soon as a new certificate is available.
To ensure that your partners are aware of the new certificate, you can provide their respective federation metadata by URLs or exports.
- Metadata by URL
- PingFederate runtime engine provides an endpoint
(/pf/federation_metadata.ping) to return metadata for web
browser SSO connections. A service provider (SP) or an identity provider (IdP) is
identified by its entity IDs using the PartnerSpId query
parameter or the PartnerIdpId query parameter, respectively,
as illustrated in the following examples.
Partner Federation metadata URL to be given to the partner An SP partner with an entity ID of SP1. https://www.example.com:9031/pf/federation_metadata.ping?PartnerSpId=SP1 An IdP partner with an entity ID of IdP1. https://www.example.com:9031/pf/federation_metadata.ping?PartnerIdpId=IdP1Note:
The base URL for the PingFederate runtime engine is https://www.example.com:9031Important:
In a clustered environment, because the console node is responsible for creating and applying the new certificates to all applicable connections, you must replicate the new certificate to the engine nodes inwhen the new certificate is available, so that the federation metadata for these connections is updated accordingly.
The administrative console reminds you to replicate configuration when it detects configuration changes.
- Metadata by manual export
- Alternatively, you can export a metadata file for a connection from the
Connections Management window or . Note:
PingFederate does not deploy new certificates or update metadata for inactive connections.
WS-Trust STS connections
For connections with only the WS-Trust security token service (STS) profile, you must export the new pending certificate and pass it to your partners out-of-band before the Activation Buffer threshold is reached.
If a connection contains both the Browser SSO and the WS-Trust STS profiles, the new certificate is included in the federation metadata for the Web Browser SSO profile. Your partner can reuse the certificate from the metadata by URL or manual export and apply it to its STS configuration.