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
<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
, ormessage.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" ] }'
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.
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.