Obfuscating response data

Cloud API supports the ability to obfuscate data that is included in a response. Response data can be either nullified or masked.

  • When response data is nullified, its value is returned as null.
  • When response data is masked, a portion of its value is returned with placeholder characters, such as a tax ID being returned as "xxx-xx-1781".

The primary type of response data that is obfuscated is Personally Identifiable Information (PII). Insurers must comply with any 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. These regulations often specify that Personally Identifiable Information (PII) must be obfuscated.

Nullifying response data

You can nullify the response data by configuring the mapper for the relevant property. This is done in a mapping extension file. For more information on mapping extension files, see Syntax for schema configuration files.

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 response data

You can mask response data by writing a Gosu method and modifying the mapper for the relevant resource property to use that method.

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 Syntax for schema configuration files. For details on allowlisting fields, see Endpoint access.

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.

Unmasking the base configuration taxID field

Contact resources have a taxID field which stores the tax ID of the contact. In the Cloud API base configuration, this field is masked in responses so that only the last four digits appear. For example, the following is the response for a GET that retrieves a contact.

{
    "data": {
        "attributes": {
            "displayName": "Ray Newton",
            "taxId": "***-**-6789"
        }
    }
}

For some callers, such as internal or external users, the masking of tax ID may be appropriate as it protects personally identifiable information. For other callers, such as services, this masking may cause a problem as the callers may reference contacts internally using the tax ID.

There are two ways that the taxId field can be unmasked:

  • You can configure the field so that it is always unmasked, as described in the previous topic.
  • You can grant the caller the restunmasktaxid system permission. Any caller who has a role with this permission will get responses with unmasked tax IDs. For information on how to configure this, see Endpoint access.

Note that the restunmasktaxid system permission changes the behavior of the base configuration taxId field only. It has no impact on any other masked data.