Encrypt data using Attribute-Based Access Control (ABAC)

[Will_Cho]

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.

• If needed, the encrypted value can be decrypted using Java code. In our project, we used the Java code to decrypt an encrypted property value and passed it to invoke an external service. See a sample code below. Note: decrypt1 is defined as a local variable in the activity rule.

String encryptedString = myStepPage.getString(".TIN");
oLog.infoForced("*** TIN (encrypted) = " + encryptedString);

decrypt1=tools.getPRCrypto().decrypt(encryptedString);
oLog.infoForced("*** TIN (decrypt1) = " + decrypt1);

Feel free to leave any question or feedback.

===

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

[IFFATHCTS (Kareema Iffath)]

@Will ChoThe article is really helpful. Is there anyway to mask/encrypt only at clipboard and UI level. Not DB etc.

[Gaurav25 (Gaurav Sharma)]

@IFFATHCTS At UI level you can do it via validate rule or javascript code.

JS Example:

1. Save jQuery js file in your ruleset. Source https://github.com/igorescobar/jQuery-Mask-Plugin/blob/master/src/jquery.mask.js.

Records → Technical → Text File → Create

• Label - JQueryMaskerInput
• Identifier - JQueryMaskerInput
• App Name - webwb
• File Type - js

2. Add to end of new js file (JQueryMaskerInput) mask format(s), for example

$(document).ready(function(){
$(‘.PhoneNumber input’).mask(‘(000) 000-00-00’);
});

3. Include new js file to harness, where section will be used (may be Performe Harness). See Scripts & styles on harness rule.

4. Add to text input field class PhoneNumber.

5. Open Setting of Text input field

6. Presentation tab

7. Advanced Presentation Options

8. Set “Cell read-write classes” set value Phone

[AravinthR (Aravinth Rathnakumar)]

@Will Cho- Is it mandatory to invoke @decrypt function to use these encrypted properties if they are referred in any business logics? Can we not just use PropertyEncrypt and PropertyRead to encrypt and decrypt a property using these two options?

[Will_Cho]

@AravinthRIn my POC above, when the property is shown at the UI level, the encrypted value is shown as decrypted. I didn’t have to call @decrypt function. When the encrypted property is used in the business logics like when rule or decision tree, i haven’t tested the scenario thus can’t confirm right now. I recall, however, one of my team members was trying to set the encrypted property as a request parameter using Data Transform to call an external service, and he was testing with Java code to decrypt and get the actual property value first.

Sample code:

String encryptedString = myStepPage.getString(".TIN");
oLog.infoForced("*** TIN (encrypted) = " + encryptedString);

decrypt1=tools.getPRCrypto().decrypt(encryptedString);
oLog.infoForced("*** TIN (decrypt1) = " + decrypt1);

Note: decrypt1 is defined as a local variable in the activity rule.

[Dewdun (Dewdun Hewage)]

@Will Cho ,

I have a pagelist property added in ABAC/PropertyEncrypt. The pagelist values are saved encrypted into an Index table using a Declare Index rule. To retrieve the data we need to manually encrypt and pass the search value as an encrypted text.

The problem is after the encryption key rotation happens the encrypted search string does not match the DB saved value and no matching results returned.

How to resolve this?

[Will_Cho]

@Dewdun Thanks for posting your question. That is an interesting use case. Unfortunately, i haven’t tested the specific scenario that you described above where the encrypted property is used for a search parameter. I would hope that the platform handles it OOTB. My suggestion is to raise a Pega incident ticket to verify whether it is a gap in the product and also whether there is any workaround or future enhancement.

[Dewdun (Dewdun Hewage)]

@Will Cho , Thanks for your reply. It’s not handled OOTB since it’s the index class we are trying to query, and I have raised this with Pega waiting for a solution.

[Chunzhi_Hong]

@AravinthR as of Pega v25.1.1, @decrypt function is required for those encrypted fields in your business logic…recently, my client reported that validation rule on an “access policy controled” field doesn’t work as expected because the value of the field is already-encrypted when the validation rule picks it…ideally, decryption/encryption should work transparently(i.e. has no side effect on business logics regardless a field is access controlled or not) and happens only at the aboundary of IO between the Pega app server and the Pega database…

[Gaurav25 (Gaurav Sharma)]

@IFFATHCTS Clipboard means the data at rest should be encrypted and the whole article shared in this post is what you are looking for then.

[Will_Cho]

@IFFATHCTS From my observation, if we mask using ABAC/PropertyRead, the masked value still shows in the clipboard. If we encrypt using ABAC/PropertyEncrypt, then the property will be removed from the clipboard. So far, i haven’t found a way to mask in the clipboard.

I have also written one article about ABAC/masking - https://support.pega.com/discussion/mask-data-using-attribute-based-access-control-abac?

[IFFATHCTS (Kareema Iffath)]

@Will Cho Yes thats what i found too. Thanks Will.

[BhanuPrakash_G]

@Will Cho Thank you for the detailed article. I was just wondering what happens to encrypted values when a key rotation occurs?

[Will_Cho]

@BhanuPrakash_G That is a good question. I did some Copilot search against internal Pega documents and this is what came up. Hope this helps.

When key rotation occurs in ABAC encryption on Pega Infinity, all previously encrypted values remain unchanged and fully decryptable because envelope encryption allows the new master key to unwrap the existing data keys; only newly encrypted values use the new master key, and old master keys must be retained to ensure continued decryption of previously encrypted data.

[IFFATHCTS (Kareema Iffath)]

@gasharma Thank you.Yes UI there are lot of ways but was checking if there is any solution for masking clipboard data especially through access control policies. Not encryption but masking.