PingFederate Server

Implementing a MasterKeyEncryptor using Google Cloud KMS

During initial startup, PingFederate automatically generates a randomized master key, which by default isn’t encrypted. If you’re running in Google Cloud, you can configure PingFederate to use Google Cloud Key Management Services (KMS) to encrypt the master key.

Before you begin

  • Make sure that you have an active connection to Google Cloud. Learn more about setting up Application Default Credentials (ADC) for authentication in the Google Cloud documentation.

  • Use Google Cloud KMS to generate a key to use for the PingFederate master key encryption. Learn more about generating keys in the Google KMS documentation.

About this task

To configure the encryption of the PingFederate master key, modify two files:

  • service-points.conf

  • com.pingidentity.crypto.jwk.MasterKeySet.xml

Steps

  1. Stop PingFederate.

  2. Open <pf_install>/pingfederate/server/default/conf/service-points.conf in a text editor.

  3. Locate the master.key.encryptor property:

    master.key.encryptor=com.pingidentity.crypto.jwk.NoOpMasterKeyEncryptor

  4. To enable master key encryption using Google Cloud KMS, replace the lines shown in step 3 with the following lines:

    master.key.encryptor=com.pingidentity.pingcommons.gcp.key.GcpKmsMasterKeyEncryptor

  5. Save and close the file.

  6. Open <pf_install>/pingfederate/server/default/data/config-store/com.pingidentity.crypto.jwk.MasterKeySet.xml in a text editor.

    the contents of the file are shown here:

    <?xml version="1.0" encoding="UTF-8"?>
<con:config xmlns:con="http://www.sourceid.org/2004/05/config">
    <!--
        Uncomment the below attribute to use an external key for encryption of PF Master Key.

        <con:item name="keyId"> put the key Id here </con:item>
    -->
    <con:item name="jwkEncrypted">false</con:item>
</con:config>

    Uncomment the <con:item name="keyId"> attribute and specify the key that you generated using Google Cloud KMS. The key ID is the resource ID of the key in the Google Cloud KMS. For example, after you’ve made the change, the file might look like the following:

    <?xml version="1.0" encoding="UTF-8"?>
<con:config xmlns:con="http://www.sourceid.org/2004/05/config">
    <con:item name="keyId">projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_ key}</con:item>
    <con:item name="jwkEncrypted">false</con:item>
</con:config>

    You can also set the key ID using the environment variable PI_GCP_MASTER_KEY_ENCRYPTOR_KEY_ID.

    If the key ID is set in both MasterKeySet.xml and the environment variable, and they’re different, PingFederate uses the key ID in MasterKeySet.xml.

  7. Save and close the file.

  8. Start PingFederate

Result

After configuring and starting PingFederate, the PingFederate master key file, pf.jwk, is encrypted.