PingFederate Server

Enabling certificate-based authentication

When client-certificate authentication is enabled, the API calls must be authenticated by X.509 client certificates; otherwise, the administrative API returns an error message.

About this task

In addition to X.509 client certificate authentication, the corresponding root certificate authority (CA) certificates must either be contained in the Java runtime or be imported into the PingFederate’s Trusted CA store. For more information, see Manage trusted certificate authorities.

The rest of the certificate-based authentication setup, including specifying the Issuer DN of the root CA certificates and the applicable roles of the client certificates, is available through <pf_install>/pingfederate/bin/cert_auth.properties. The roles assigned to the certificates affect the results of the API calls.

Steps

  1. Sign on to the administrative console with an account that has the role Crypto Admin.

  2. Ensure the client-certificate’s root CA and any intermediate CA certificates are contained in the trusted store, either for the Java runtime, or PingFederate, or both.

    To import a certificate, click Trusted CAs in the Certificate Management section under Server Configuration.

    Click the Serial number and copy the Issuer distinguished name (DN) to use in a couple steps later.

  3. Verify the pf.admin.api.authentication value in <pf_install>/pingfederate/bin/run.properties is set to cert. Update as needed.

  4. In the <pf_install>/pingfederate/bin/cert_auth.properties file, enter the Issuer DN for the client certificate as a value for the property: rootca.issuer.<x>, where <x> is a sequential number starting at 1. For more information, see the properties file.

    The configuration values are case-sensitive.

    If you copied the Issuer DN a couple steps earlier, paste this value.

  5. Repeat the previous step for any additional CAs as needed.

  6. Enter the certificate’s Subject DN for the applicable PingFederate permission roles, as described in the properties file. For information about permissions attached to the PingFederate roles, see the PingFederate User Access Control table in Configure access to the administrative API.

    The configuration values are case-sensitive.

    When assigning roles, keep in mind that all client certificates specified in cert_auth.properties can be used to access the administrative API and the administrative console.

  7. Repeat the previous step for all client certificates as needed.

  8. Restart PingFederate.

    In a clustered PingFederate environment, you only need to modify run.properties and cert_auth.properties on the console node.