Masking and hiding data

When you debug APIs calls in Apigee, the content can sometimes contain sensitive data, such credit cards or personally identifiable health information (PHI) that needs to be masked.

Apigee provides different ways of masking or hiding sensitive data from Trace and debug sessions.

Masking sensitive data

Apigee enables you to define mask configurations to mask specific data in trace and debug sessions. When data is masked, it is replaced with asterisks in the trace output. For example:

<description>**********</description>

The mask configuration is a singleton resource that you define at the environment level. By default, no data masking is in effect.

Structure of a mask configuration

Mask configurations are JSON-formatted files that enable you to identify sensitive data in the following sources:

XML payloads: Using XPath, you identify XML elements to be filtered from request or response message payloads.
JSON payloads: Using JSONPath, you identify JSON properties to be filtered from request or response message payloads.
Flow variables: You can specify a list of variables that should be masked in debug output. When you specify the request.content, response.content, or message.content flow variables, the request/response body is also masked.

The following provides an example of the basic structure of a mask configuration in JSON format. For more information about the mask configuration fields shown in the example, see DebugMask.

{
  "namespaces": {
    "myco": "http://example.com"
  },
  "requestXPaths": [
    "/myco:Greeting/myco:User"
  ],
  "responseXPaths": [
    "/myco:Greeting/myco:User"
  ],
  "faultXPaths": [
    "/myco:Greeting/myco:User"
  ],
  "requestJSONPaths": [
    "$.store.book[*].author"
  ],
  "responseJSONPaths": [
    "$.store.book[*].author"
  ],
  "faultJSONPaths": [
    "$.store.book[*].author"
  ],
  "variables": [
    "request.header.user-agent",
    "request.formparam.password"
  ]
}

Viewing the mask configuration in an environment using the API

To view the mask configuration in an environment, issue a GET to the following resource:

/organizations/{org}/environments/{env}/debugmask

For example:

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/debugmask" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

Where $TOKEN is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl. For a description of the environment variables used, see Setting environment variables for Apigee API requests.

The following provides an example of the response:

{
  "name": "organizations/myorg/environments/test/debugmask"
  "namespaces": {
    "myco": "http://example.com"
  },
  "requestXPaths": [
    "/myco:Greeting/myco:User"
  ],
  "responseXPaths": [
    "/myco:Greeting/myco:User"
  ]
}

Updating the mask configuration in an environment using the API

To update the mask configuration singleton resource in an environment, issue a PATCH to the following resource:

/organizations/{org}/environments/{env}/debugmask/{debugmask}

Optionally, you can pass the following query parameters:

Set the updateMask query parameter to specify a field mask that includes a comma-separated list of fully-qualified names of fields in the debug mask. For example: "requestJSONPaths"
Set the replaceRepeatedFields query parameter to specify whether to replace existing values in the debug mask when doing an update. By default, values are appended (false)

For example:

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/debugmask/{debugmask}" \
  -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-type: application/json" \
  -d \
  '{
    "requestXPaths": [
      "/myco:employee/myco:name"
    ]
   }'

Masking for XML namespaces

A mask configuration doesn't require the <Namespace> element in an XPATH definition unless a namespace is defined in the XML payload. This is also true if the XML payload uses a default namespace.

For example, the XML payload does not define a namespace:

<employee>
    <name>abc</name>
    <age>50</age>
</employee>

Therefore, the mask configuration doesn't require the <Namespace> element:

{
  "requestXPaths": [
    "/employee/name"
  ]
}

If the XML payload contains a namespace and prefix:

<employee xmlns:myco="http://example.com">
    <myco:name>xyz</myco:name>
    <myco:age>50</myco:age>
</myco:employee>

Then the mask configuration definition should contain the <Namespace> element:

{
  "namespaces": {
    "myco": "http://example.com"
  },
  "requestXPaths": [
    "/myco:employee/myco:name"
  ]
}

If the XML Payload has a namespace but no prefix, meaning the default namespace:

<employee xmlns="http://example.com">
    <name>xyz</name>
    <age>50</age>
</employee>

Then the mask configuration should still contain the <Namespace> element:

{
  "namespaces": {
    "myco": "http://example.com"
  },
  "requestXPaths": [
    "/myco:employee/myco:name"
  ]
}

Hiding sensitive data

You can prevent sensitive data from appearing in the Trace tool and debug sessions by creating custom variables prefixed with "private.".

For example, when using the Key Value Map Operations policy to retrieve values from an encrypted key value map, format the variable names as follows to ensure the values don't appear in Trace or debug sessions:

<Get assignTo="private.hiddenData">

Hiding sensitive variables is an alternative to using data masking, described next. The difference between hiding and masking is that hidden variables don't appear at all, and masked values are replaced with asterisks in Trace and debug sessions.

Variables without the "private." prefix are displayed in clear text in Trace and debug sessions even if the data comes from an encrypted data store such as an encrypted key value map. Use masking (below) if you want to mask these values.