Connection and federation metadata

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.

Notifications

Although optional, you can turn on notifications for certificate events in System → Monitoring & Notifications → Runtime Notifications. When configured, 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.

Signing certificate

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.

XML decryption

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

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

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

The base URL for the PingFederate runtime engine is https://www.example.com:9031

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 System → Server → Cluster Management when 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 System → Protocol Metadata → Metadata Export.

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.