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. In addition, the corresponding root CA certificate(s) must either be contained in the Java runtime or be imported into the PingFederate's Trusted CA store (see Managing trusted certificate authorities).

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

  1. Log 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.
    Tip:

    You may wish to click the Serial number and copy the Issuer 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 (see the properties file for more information).
    Important:

    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 role(s), 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.
    Important:

    The configuration values are case-sensitive.

    Note:

    When assigning role(s), 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.
    Note:

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