Certification rotation is a per-certificate configuration. When certificate rotation is enabled for a certificate and a new certificate using a new key pairs becomes available, PingFederate deploys the new certificate to all enabled connections using that certificate. The actions taken by PingFederate vary depending on the role of the certificate.
Although optional, it is recommended that you turn on notifications for certificate events in thescreen. When configured, PingFederate notifies the configured recipient when a new certificate becomes available and when it is activated. Depending on the role of the certificate, you can update your partner accordingly.
When the Creation Buffer threshold is reached, a new certificate is created. For all Browser 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 becomes available, PingFederate performs the following tasks for all SAML 2.0 connections using the same decryption key:
- Push the current decryption key from primary to secondary.
- Place the new certificate as the primary decryption key.
- Update the decryption key with the new certificate in the metadata.
- Start 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 supports the RSA key algorithm only. When EC (elliptic curve) is selected as the Key Algorithm value on the Certificate Rotation screen, 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 for you before the Activation Buffer threshold is reached.
Federation metadata for Browser SSO connections
PingFederate updates the metadata for the applicable Browser SSO connections as soon as a new certificate becomes available.
To ensure that your partners are aware of the new certificate, you can provide the partners their respective federation metadata URL or metadata export.
- Metadata by URL
- PingFederate runtime engine provides an endpoint
(/pf/federation_metadata.ping) to return metadata for
Browser SSO connections. An SP or an 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=IdP1
Note that the base URL for the PingFederate runtime engine is https://www.example.com:9031.Important:
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 in thescreen when the new certificate becomes available, such that the federation metadata for these connections are 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
Manage All connections management screen or the wizard. Note:
PingFederate does not deploy new certificates or update metadata for inactive connections.
WS-Trust STS connections
For connections with only the WS-Trust 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 Browser SSO profile. Your partner can reuse the certificate from the metadata (by URL or manual export) and apply it to its STS configuration.