This article shows step-by-step of how to encrypt sensitive data such as PII (Personal Identifiable Information) in Pega applications using Attribute-Based Access Control (ABAC) security model in Pega Platform and demonstrates various results.  (For how to mask data using ABAC, read this article).

This article largely consists of four parts:

1. Create an encryption key outside Pega.

• Using Google Cloud KMS (Key Management Service)

2. Configure data encryption in Pega Platform.

• Using Attribute-Based Access Control (ABAC) with PropertyEncrypt action.

3. Verify the results.

4. In addition, encrypt an embedded property (pagelist) under pyWorkPage.

Configurations

[Part 1] Create an encryption key outside Pega using Google KMS.

Note: you will need a Google Cloud account.  In this example, I used a free trial version.

1. Click Create Key Ring.

2. Enter details and click Create.

3. Enter additional details and click Create.

4. Click ‘Copy resource name’.

• The copied value will be later entered into Pega keystore - “projects/will-pega/locations/us-east4/keyRings/PegaEncryptionKey/cryptoKeys/PegaEncryptionKey”

5. Create a Google service account to access Cloud KMS Service.

• Click CREAT SERVICE ACCOUNT.

6. Enter the Service account details and click CREATE AND CONTINUE.

• Select Service Role to “Cloud KMS CryptoKey Encrypter/Decrypter”.

• The new service account is now added.

7. Open the new service account and create a new key.

• Create a new JSON key type.

• The JSON file will be automatically downloaded.

[Part 2] Configure data encryption using Attribute-Based Access Control (ABAC) with PropertyEncrypt action in Pega Platform.

1. First, configure a new keystore that will be used to encrypt & decrypt data in Pega.

• In DEV Studio, go to Security > Keystore and click Create.

• Enter the keystore details and save.
  • Keystore location = select “Google Cloud KMS”
  • Upload file = Upload the JSON file downloaded using Google Cloud KMS above.
  • Customer master key ID = enter the resource name copied from the new key ring created above – “projects/will-pega/locations/us-east4/keyRings/PegaEncryptionKey/cryptoKeys/PegaEncryptionKey”

• Test the connectivity.

2. Go to the Configure > System > Settings > Data Encryption landing page.

• Select the ‘Platform cipher’ option and activate the new keystore created above.

• Under the System data encryption section, click Regenerate.

3. Create an Access Control Policy rule with Action=PropertyEncrypt under your work class.

• In this example, we will be encrypting an SSN property.

[Part 3] Test and verify the results.

• Result 1 (clipboard) – we can no longer see the SSN property in clipboard.

• Result 2 (UI) – it is shown as decrypted at UI level.

• Result 3 (UI, combined with PropertyRead access control policy) – another Access Control Policy with Action=PropertyRead on the same SSN property is working as usual.  It shows a decrypted and masked value.  This article explains how to mask property values using ABAC.

• Result 4 (database) – at DB level, it is encrypted.

• Result 5 (Tracer) – from the Tracer view, it is encrypted.

• Result 6 (log) – at the logging level, it is encrypted

• Result 7 (data page) – in the data page view, it is encrypted.

• Result 8 (report definition) - In report definition, it is decrypted.

[Part 4] In addition, encrypt an embedded property (pagelist) under pyWorkPage.

1. Create a pagelist property.

• First, create a data class which will be used as definition of the pagelist.

• Create a pagelist property under your work class.

In this example, we want to encrypt the Name property under the pyWorkPage.MyList() pagelist.

2. Add .MyList().Name to the Access Control Policy (PropertyEncrypt) created in your work class.

3. Test and verify the results.

• Result 1 (clipboard) - pyWorkPage.MyList(1).Name is now hidden from the clipboard.
  • Only MyID property is showing since it’s not added to the Access Control Policy rule.

• Results 2 (log) - pyWorkPage.MyList(1).Name is encrypted in the log.  
  • On the other hand, pyWorkPage.MyList(1).MyID property value is exposed.

Additional notes

• One caveat - when i included the encrypted property to a BIX extract, it was throwing an error ("Platform cipher is used for data encryption. Extraction can only be done in clear text mode.").  It is possible that BIX doesn't allow extracting encrypted properties by design.  Project teams should discuss with business before deciding what data to encrypt in Pega application and their implications to BIX extract/enterprise reporting.
  • Updated (6/4/24): Got a solution from Pega Engineering.  Add the following code to prconfig.xml and restart the server.  I was able to bix extract an encrypted property.

<env name="bix/getClearTextWhileExtraction" value="true" />

• When you expose a property (e.g. Right click on the property to 'Optimize for reporting') to store an encrypted string, Pega may set the table column length to 32 by default and this may not be sufficient to store an encrypted string.  For us, this caused the decryption to fail later.  To set a sufficient column length in DB, set the Max length field in the Advanced tab of property rule form before exposing the property to a new table column.  This fixed the issue for us.

Feel free to leave any question or feedback.

===

Other reference - How to "mask" sensitive data using Attribute-Based Access Control (ABAC) in Pega