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 Certificate rotation.
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.
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.