Implementing a MasterKeyEncryptor using AWS KMS - PingFederate - 11.0

PingFederate Server

bundle
pingfederate-110
ft:publication_title
PingFederate Server
Product_Version_ce
PingFederate 11.0
category
Product
pf-110
pingfederate
ContentType_ce

During initial startup, PingFederate automatically generates a randomized master key, which by default is not encrypted. If you are running in Amazon Web Services (AWS), you can configure PingFederate to use Amazon Key Management Services (KMS) to encrypt the master key.

  • Make sure that you have an active connection to AWS.
  • Use AWS KMS to generate a key to use for the PingFederate master key encryption.
  • See https://docs.aws.amazon.com/kms/latest/developerguide/overview.html for general information about how you can manage access rights to your keys using key policies or AWS Identity and Access Management (IAM).

To configure the encryption of the PingFederate master key, modify two files: hivemodule.xml and com.pingidentity.crypto.jwk.MasterKeySet.xml.

  1. Stop PingFederate.
  2. Open <pf_install>/pingfederate/server/default/conf/META-INF/hivemodule.xml in a text editor.
  3. Locate the following lines near the bottom of the file.
    <service-point id="MasterKeyEncryptor" interface="com.pingidentity.sdk.key.MasterKeyEncryptor">
        <create-instance class="com.pingidentity.crypto.jwk.NoOpMasterKeyEncryptor"/>
    </service-point>
  4. To enable master key encryption using AWS KMS, replace the lines shown in step 3 with the following lines.
    <service-point id="MasterKeyEncryptor" interface="com.pingidentity.sdk.key.MasterKeyEncryptor">
        <create-instance class="com.pingidentity.pingcommons.aws.key.AwsKmsMasterKeyEncryptor"/>
    </service-point>
  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>
    
  7. Uncomment the <con:item name="keyId"> attribute and specify the key that you generated using AWS 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">b3867a2c-4d15-8e0c-6f7b-0b1e61f7ad36</con:item>
        <con:item name="jwkEncrypted">false</con:item>
    </con:config>
    
  8. Save and close the file.
  9. Start PingFederate.
After configuring and starting PingFederate, the PingFederate master key file, pf.jwk, is encrypted.