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 more information on general schema configuration, see Configuring schemas.

The schema for the ClaimContact resource contains a taxId property:

For example, a claim has ClaimContacts. Depending on business purposes, it might have been necessary to obtain tax identification information for a ClaimContact. Later, a system API caller could request the ClaimContact 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.

"ClaimContact": {
  "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 ClaimContact mapper as follows:

"ClaimContact": {
  "schemaDefinition": "ClaimContact",
  "root": "entity.ClaimContact",
  "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 more information on general schema configuration, see Configuring schemas.

For example, a claim has ClaimContacts. Depending on business purposes, it might have been necessary to obtain tax identification information for a ClaimContact. Later, a system API caller could request the ClaimContact 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 ClaimContact resource contains a taxId property:

"ClaimContact": {
  "type": "object",
  "x-gw-extensions": {
    "discriminatorProperty": "contactSubtype"
  },
  "properties": {
    . . .
    "taxId": {
      "type": "string"
    },
    . . .
  }
}

This property is mapped to the TaxID field of the ClaimContact.Contact entity. You must create a Gosu method for this entity that masks the tax ID string. In this example, the method is named maskTaxId.

You then modify the taxId property in the ClaimContact mapper as follows:

"ClaimContact": {
  "schemaDefinition": "ClaimContact",
  "root": "entity.ClaimContact",
  "properties": {
    . . .
    "taxId": {
      "path": "ClaimContact.Contact.maskTaxId(ClaimContact.Contact.TaxID)"
    },
    . . .
  }
}

With the taxId.path property set to ClaimContact.Contact.maskTaxId(ClaimContact.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 Configuring schemas. For details on allowlisting fields, see the section on API role files in Cloud API Authentication Guide.

Important: Nothing in the Cloud API infrastructure prevents configuration that could expose PII in a sensitive way. For example, if you specify 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.