Manage digital signing certificates and decryption keys
On Security → Certificate & Key Management → Signing & Decryption Keys & Certificates, you can create and maintain certificates and their respective key pairs for the purpose of signing outgoing requests, responses, assertions, and access tokens, and for the purpose of decryption.
Use separate certificates for signing and decryption.
After creating your certificates, if they remain as self-signed certificates, you can enable automatic certificate rotation. See partial$pf_cert_rotation.adoc.
Certificate rotation
The optional automatic certificate rotation feature of PingFederate greatly reduces the cost of managing self-signed certificates.
PingFederate supports automatic certificate rotation for self-signed certificates created for signing SAML requests, responses, and assertions, or XML decryption for browser SSO and WS-Trust STS transactions on a per-certificate basis.
|
Certificate rotation is only available to self-signed certificates. Also, you can’t enable rotation on certificates that are used as a secondary signing certificate in a connection, or are used as the primary certificate in a connection configured with a secondary signing certificate. |
Certificate rotation happens over two stages, identified by the Creation Buffer and Activation Buffer settings.
-
The Creation Buffer is the number of days ahead of expiry that PingFederate creates a new key pair and a new certificate.
-
The Activation Buffer is the number of days ahead of expiry that PingFederate activates the certificate.
When you enable certificate rotation on a certificate, you can customize the values of the Creation Buffer and Activation Buffer settings. Alternatively, you can keep their default values, which are 25% and 10% of the original lifetime of the current certificate, respectively. The following examples illustrate the default values for both buffers based on a 100-day certificate and a 365-day certificate.
| Current certificate | The default value for theCreation Bufferfield | The default value for theActivation Bufferfield | The rotation window |
|---|---|---|---|
Self-signed certificate #1, valid for 100 days from January 1, 2017 to April 9, 2017 |
25 days ahead of expiry, which is March 16 |
10 days ahead of expiry, which is March 31 |
15 days from March 16 through March 30 |
Self-signed certificate #2, valid for 365 days from January 1, 2017 to December 31, 2017 |
91 days ahead of expiry, which is October 2 |
36 days ahead of expiry, which is November 26 |
55 days from October 2 through November 25 |
If the PingFederate server is shut down when the Creation Buffer threshold is reached for a given certificate, a new key pair and a new certificate are created if PingFederate is restarted during the rotation window.
In a clustered PingFederate environment, when the new signing certificate is ready, the administrative console displays a message to remind the administrators to replicate the new certificate to the engine nodes in System → Server → Cluster Management.
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.
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 thePartnerSpIdquery parameter or thePartnerIdpIdquery 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? |
An IdP partner with an entity ID of IdP1. |
https://www.example.com:9031/pf/federation_metadata.ping? |
|
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.
Managing certificate rotation settings
Use the Signing & Decryption Keys & Certificates window to customize certificate rotation settings for your certificates.
About this task
Manage certificate rotation settings for self-signed certificates on Security → Certificate & Key Management → Signing & Decryption Keys & Certificates.
Steps
-
On the Signing & Decryption Keys & Certificates window, select Certificate Rotation for the applicable certificate.
Certificate rotation is only available to self-signed certificates.
-
Select the check box to turn on certificate rotation for the selected certificate, then click Next.
If you want to turn off certificate rotation for the selected certificate, clear the check box and then click Save.
-
Optional: On the Certificate Rotation tab, modify the default values.
Field Description Creation buffer
The number of days ahead of expiry that PingFederate creates a new key pair and a new certificate.
The default value is 25% of the original lifetime of the current certificate.
Activation buffer
The number of days ahead of expiry that PingFederate activates the certificate.
The default value is 10% of the original lifetime of the current certificate.
Validity
The time during which the certificate is valid.
The default value matches that of the current certificate.
Key Algorithm
A cryptographic formula used to generate a key. PingFederate uses either of two algorithms, RSA or EC.
The default value matches that of the current certificate.
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.
Key Size
The number of bits used in the key. (RSA-1024, 2048 and 4096; and EC-256, 384 and 521.)
The default value matches that of the current certificate.
Signature Algorithm
The signing algorithm of the certificate. (RSA and ECDSA-SHA256, SHA384 and SHA512.)
The default value matches that of the current certificate.
-
On the Certificate Rotation Summary tab, review the rotation settings. Adjust as needed, and then click Save to turn on automatic certificate rotation for this certificate.
Managed SP connection to PingOne for Enterprise and signing certificate
Use managed service provider (SP) connections to PingOne for Enterprise to automatically rotate signing certificates being used by it.
PingFederate automatically rotates the signing certificate used by the managed SP connection to PingOne for Enterprise.
|
A managed SP connection to PingOne for Enterprise is a connection created either as part of the initial setup or the System → External Systems → Connect to PingOne for Enterprise configuration wizard in PingFederate 8.0 or later. |
The certificate rotation settings are as follows.
| Field | Values |
|---|---|
Creation Buffer (days) |
90 |
Activation Buffer (days) |
30 |
Validity (days) |
1095 |
Key Algorithm |
RSA |
Key Size |
2048 |
Signature Algorithm |
RSA SHA256 |
If the signing certificate should be manually rotated instead, disable automatic certificate rotation. See pf_managing_certificate_rotation_settings.adoc.
|
After making changes, the administrative console prompts for confirmation whether to update PingOne for Enterprise or to disconnect from PingOne for Enterprise in a banner message. See Managing PingOne for Enterprise settings. |
Creating new certificates
Use the functionality found in the Signing & Decryption Keys & Certificates window to create new, customized certificates.
Steps
-
On the Signing & Decryption Keys & Certificates window, click Create new.
-
On the Create Certificate tab, enter the required information.
For information about each field, refer to the following table.
Field Description Common Name
The common name (CN) identifying the certificate.
Subject Alternative Names
The additional DNS names or IP addresses possibly associated with the certificate.
Organization
The organization (O) or company name creating the certificate.
Organizational Unit
The specific unit within the organization (OU).
City
The city or other primary location (L) where the company operates.
State
The state (ST) or other political unit encompassing the location.
Country
The country © where the company is based.
Validity (days)
The time during which the certificate is valid.
Key Algorithm
A cryptographic formula used to generate a key. PingFederate uses either of two algorithms, RSA or EC.
Key Size (bits)
The number of bits used in the key. (RSA-1024, 2048 and 4096; and EC-256, 384 and 521.)
Signature Algorithm
The signing algorithm of the certificate. (RSA and ECDSA-SHA256, SHA384, and SHA512.)
-
When finished, click Next.
-
On the Summary window, review your configuration, amend as needed, and click Done.
Importing certificates and their private keys
You can import certificates and their private keys in the Signing & Decryption Keys & Certificates window.
About this task
This task describes how to import certificates and their private keys. Supported certificate and private key formats differ depending on whether you are running PingFederate with BCFIPS enabled or disabled.
-
Certificate and private key format:
-
In non-BCFIPS mode, we support PKCS12 and PEM formatted certificates and private keys, and automatically detect the format between PKCS12 and PEM.
-
In BCFIPS mode, we only support PEM formatted certificate and private keys. Only PBES2 and AES or Triple DES encryption is accepted and 128-bit salt is required. In practice, this may mean that only PEM files generated by PingFederate can be imported.
-
For PEM, the private key must precede the certificates.
-
-
Password requirement:
-
In BCFIPS mode, the password must contain at least 14 characters.
-
Steps
-
On the Signing & Decryption Keys & Certificates window, click Import.
-
On the Import Certificate tab, choose the applicable certificate file and enter its password.
If PingFederate is integrated with an HSM in hybrid mode, select the storage facility of the certificate from the Cryptographic Provider list.
-
Select HSM to store the certificate in the HSM.
-
Select Local Trust Store to store the certificate in the local trust store managed by PingFederate.
-
-
On the Summary window, review your configuration, amend as needed, and click Done.
Creating a certificate signing request (CSR)
Use the Certificate Signing functionality to generate and save a CSR file to submit it to a certificate authority (CA) for a signed certificate.
Steps
-
On the Signing & Decryption Keys & Certificates window, select Certificate Signing for the certificate.
This selection is inactive if you have not yet saved a newly created or imported certificate. Click Save and then return to this window to initiate the process.
The selection is also inactive if a previously signed certificate is revoked. Because the revocation could indicate that the private key is compromised, the best practice is to import or create a replacement certificate for certificate signing.
-
On the Certificate Signing tab, select the Generate CSR option.
-
On the Generate CSR tab, click Export to save the CSR file, and then click Done.
Once saved, you can submit this CSR file to a certificate authority for a CA-signed certificate.
Importing a certificate-authority response (CSR response)
Use the Certificate Signing functionality to import your own CSR response file into PingFederate.
Steps
-
On theSigning & Decryption Keys & Certificates window, select Certificate Signing for the certificate.
-
On the Certificate Signing tab, select the Import CSR Response option.
-
On the Import CSR Response tab, choose the applicable CSR response file.
-
On the Summary tab, review your configuration, and click Save.
Exporting certificates
On the Signing & Decryption Keys & Certificates window, you can export a certificate with or without its private key.
About this task
This task describes how to export certificates and their private keys. Supported certificate and private key formats differ depending on whether you are running PingFederate with BCFIPS enabled or disabled.
-
Certificate and private key format:
-
In non-BCFIPS mode, when the Certificate and Private Key option is selected, a Format field displays allowing you to choose between exporting a PKCS12 or a PEM formatted certificate and private key.
-
In BCFIPS mode, you can only export PEM-formatted certificates and private keys.
If you need to convert from PEM to PKCS12 format, use the following command:
openssl pkcs12 -export -inkey keypair.pem -in keypair.pem -out keypair.p12
-
-
Password requirement:
-
In BCFIPS mode, the password must contain at least 14 characters.
-
Steps
-
On the Signing & Decryption Keys & Certificates window, select Export for the certificate.
-
On the Export Certificate tab, select the export type.
-
Select Certificate Only to export the selected certificate without its private key. This is the default choice.
-
Select Certificate and Private Key to export the selected certificate with its private key. If you are not running in BCFIPS mode, the Format section appears, and you must select either PKCS12 or PEM.
You must also enter and confirm an Encryption Password, since this export contains the private key of the certificate.
If the selected certificate is stored in a hardware security module (HSM), the Certificate and Private Key option does not apply.
-
-
On the Export & Summary window, click Export to save the certificate file, and then click Done.
Reviewing certificates
Take a closer look at individual certificates to ensure their properties match your needs.
Steps
-
On the Signing & Decryption Keys & Certificates window, select the certificate by its serial number.
-
Review the selected certificate in the pop-up window.
-
When finished, close the pop-up window.
Reviewing a certificate’s usage
Take a look at a certificate’s usage data to get a sense of how often it’s used.
Steps
-
On the Signing & Decryption Keys & Certificates window, select Check Usage for the certificate.
If the certificate is not used by any configuration, the Check Usage option does not apply.
-
Review the information in the pop-up window.
-
When finished, close the pop-up window.