Implementing a MasterKeyEncryptor using AWS KMS - PingFederate - 11.3

PingFederate Server
bundle
pingfederate-113
ft:publication_title
PingFederate Server
Product_Version_ce
PingFederate 11.3 (Latest)
category
Administrator
Administratorguide
Audience
Capability
ContentType
DeploymentMethod
Guide
Product
Productdocumentation
SingleSignonSSO
Software
SystemAdministrator
pf-113
pingfederate
ContentType_ce
Guide > Administrator Guide
Product documentation
Guide

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: service-points.conf and com.pingidentity.crypto.jwk.MasterKeySet.xml.

  1. Stop PingFederate.
  2. Open <pf_install>/pingfederate/server/default/conf/service-points.conf in a text editor.
  3. Locate the following lines near the bottom of the file. 
    master.key.encryptor=com.pingidentity.crypto.jwk.NoOpMasterKeyEncryptor
  4. To enable master key encryption using AWS KMS, replace the lines shown in step 3 with the following lines. 
    master.key.encryptor=com.pingidentity.pingcommons.aws.key.AwsKmsMasterKeyEncryptor
  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.