Obfuscating Personally Identifiable Information (PII)
Generally, enterprises that handle personal data must abide by the data protection and privacy regulations of the jurisdictions in which they operate. For example, companies operating in the European Union must abide by the General Data Protection Regulation (GDPR) within that jurisdiction.
One way to protect the privacy of individuals is to obfuscate Personally Identifiable Information (PII). This approach limits the exposure of designated PII, and is supported by the system APIs. PII can be obfuscated by either nullifying or masking. PII is nullified when its value is returned null. PII is masked when a portion of its value is returned with placeholder characters, such as 'XXXXXXX-3213' as a return value for an account number.
Nullifying PII
You can nullify the return value of PII by modifying the mapper for the relevant resource property. This can be done in a resource extension. For details on resource extensions, see Extending system API resources.
For example, an account has AccountContacts. Depending on business purposes, it might have been necessary to obtain tax identification information for an AccountContact. Later, a system API caller could request the AccountContact and then view the contact's tax ID in the response. To prevent the exposure of this data, you can nullify the value in the resource mapper.
The schema for the AccountContact resource contains a taxId
property:
"AccountContact": {
"type": "object",
"x-gw-extensions": {
"discriminatorProperty": "contactSubtype"
},
"properties": {
. . .
"taxId": {
"type": "string"
},
. . .
}
}
To nullify the value of the taxId
property, you can modify that
property in the AccountContact mapper as follows:
"AccountContact": {
"schemaDefinition": "AccountContact",
"root": "entity.AccountContact",
"properties": {
. . .
"taxId": {
"path": "null as String",
"predicate": "false"
},
. . .
}
}
Setting the taxId.path
property to "null as String"
converts the
expected value to a null string. Setting taxId.predicate
to false prevents the original value, in this case the PII, from being evaluated.
Masking PII
You can mask the return value of PII by writing a Gosu method and modifying the mapper for the relevant resource property to use that method. For details on implementing Gosu code, see the Configuration Guide. The mapper can be modified through a resource extension. For details on extending resources, see Extending system API resources.
For example, an account has AccountContacts. Depending on business purposes, it might have been necessary to obtain tax identification information for an AccountContact. Later, a system API caller could request the AccountContact and then view the contact's tax ID in the response. To limit the exposure of this data, you can mask that value.
The schema for the AccountContact resource contains a taxId
property:
"AccountContact": {
"type": "object",
"x-gw-extensions": {
"discriminatorProperty": "contactSubtype"
},
"properties": {
. . .
"taxId": {
"type": "string"
},
. . .
}
}
This property is mapped to the TaxID
field of the
AccountContact.Contact
entity. You must create a Gosu method that masks
the tax ID string. In this example, the method is named maskTaxId
.
You then modify the taxId
property in the AccountContact mapper as
follows:
"Contact": {
"schemaDefinition": "Contact",
"root": "entity.Contact",
"properties": {
. . .
"taxId": {
"path": "AccountContact.Contact.maskTaxId(AccountContact.Contact.TaxID)"
},
. . .
}
}
With the taxId.path
property set to
AccountContact.Contact.maskTaxId(AccountContact.Contact.TaxID)
, the
value of TaxID
is passed through the maskTaxId
method
before being exposed to the caller.
Changing the masking pattern
To change the masking pattern applied to a resource property, you can either revise the existing masking Gosu method or write a new one.
Unmasking PII
Conversely, you can unmask PII that has been masked in the base configuration. This can be
necessary when you need to expose the PII to a specific internal role, such as
administrator. In such circumstances, Guidewire recommends that you create a new schema
extension for the masked property. For example, if you wish to unmask the
taxId
property, you would create a taxIdUnmasked_Ext
schema property that is mapped directly to the TaxID
entity field.
In such a case, Guidewire recommends that you also allowlist the extended property
to make it visible only to authorized roles.
For details on creating resource extensions, see Extending system API resources. For details on allowlisting fields, see the section on API role files in
Cloud API Authentication Guide.
taxId
as a
filterable parameter or sortable, it can be included as part of the URL in a request and is
more likely to appear in application logs.