Was this Helpful?

Overview

Apigee Edge enables developers to capture message content to enable runtime debugging of APIs calls. In many cases, API traffic contains sensitive data, such credit cards or personally identifiable health information (PHI) that needs to filtered out of the captured message content.

To meet this requirement, Edge defines 'mask configurations' that enable you to specify data that will be filtered out of trace sessions. Masking configurations can be set globally (at the organization-level) or locally (at the API proxy level). Role-based capabilities govern which users have access to the data that is defined as sensitive.

Data masking is only enabled when a trace session (also called a 'debug' session) is enabled for an API proxy. If no trace session are enabled on an API proxy, then the data will not be masked.

Using Mask Configurations

Mask configurations enable you to identify sensitive data in these 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.

The basic structure of a mask configuration is shown by the following XML representation:

The name of the mask must be default.

<MaskDataConfiguration name="default">
  <XPathsRequest>
	<XPathRequest>/apigee:Greeting/apigee:User</XPathRequest>
  </XPathsRequest>
  <XPathsResponse>
    <XPathResponse>/apigee:Greeting/apigee:User</XPathResponse>
  </XPathsResponse>
  <JSONPathsRequest>
    <JSONPathRequest>$.store.book[*].author</JSONPathRequest>
  </JSONPathsRequest>
  <JSONPathsResponse>
	<JSONPathResponse>$.store.book[*].author</JSONPathResponse>
  </JSONPathsResponse>
  <XPathsFault>
	<XPathFault>/apigee:Greeting/apigee:User</XPathFault>
  </XPathsFault>
  <JSONPathsFault>
	<JSONPathFault>$.store.book[*].author</JSONPathFault>
  </JSONPathsFault>
  <Variables>
	<Variable>request.header.user-agent</Variable>
    <Variable>request.formparam.password</Variable>
  </Variables>
</MaskDataConfiguration>

Configuring a mask configuration resource

Configure a Maskconfig resource using the following elements.

If you use ServiceCallout to make a request, the information in that request is not masked with the normal Maskconfig configuration. If you wish to mask ServiceCallout request information, add flow the variable ServiceCallout.request to the <Variables> element of the Maskconfig configuration. 

Field Name Description Default Required?
XPathsRequest A list of XPath expressions that will be evaluated against XML payloads (if any) in the request path. Any XPaths that successfully resolve will result in the value of the XML element being masked. N/A No
XPathsResponse A list of XPath expressions that will be evaluated against XML payloads (if any) in the response path. Any XPaths that successfully resolve will result in the value of the XML element being masked. N/A No
JSONPathsRequest A list of JSONPath expressions that will be evaluated against JSON payloads (if any) in the request path. Any JSONPaths that successfully resolve will result in the value of the JSON property being masked. N/A No
JSONPathsResponse A list of JSONPath expressions that will be evaluated against JSON payloads (if any) in the response path. Any JSONPaths that successfully resolve will result in the value of the JSON property being masked. N/A No
XPathsFault A list of XPath expressions that will be evaluated against XML payloads (if any) in the error flow (which executes if a fault is thrown at any point in the flow). Any XPaths that successfully resolve will result in the value of the XML element being masked. N/A No
JSONPathsFault A list of JSON expressions that will be evaluated against XML payloads (if any) in the error flow (which executes if a fault is thrown at any point in the flow). Any JSONPaths that successfully resolve will result in the value of the XML element being masked. N/A No
Variables A list of variables (either pre-defined or custom) who values will be masked. For a list of default variables, see Variables reference. N/A No

Mask configuration API

Mask configurations are defined as XML- or JSON-formatted files that you upload and download using the RESTful management API. For a complete list of data masking APIs, see Data Masks.

To see existing mask configurations, you can simply call the API resource /maskconfigs in your organization:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/maskconfigs \
-u myemail:mypass

To see mask configurations defined for specific API proxies, you can call the /maskconfigs API:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apis/{api_name}/maskconfigs \
-u myemail:mypass

To see a specific mask configuration, specify the name of the mask:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/maskconfigs\default \
-u myemail:mypass
$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apis/{api_name}/maskconfigs\default \
-u myemail:mypass

To create a mask configuration, use the POST verb to submit a payload that defines the mask configuration:

$ curl -H "Content-type:text/xml" -X POST -d \
'<MaskDataConfiguration name="default">
  <XPathsRequest>
	<XPathRequest>/apigee:Greeting/apigee:User</XPathRequest>
  </XPathsRequest>
  <XPathsResponse>
    <XPathResponse>/apigee:Greeting/apigee:User</XPathResponse>
  </XPathsResponse>
  <JSONPathsRequest>
    <JSONPathRequest>$.store.book[*].author</JSONPathRequest>
  </JSONPathsRequest>
  <JSONPathsResponse>
	<JSONPathResponse>$.store.book[*].author</JSONPathResponse>
  </JSONPathsResponse>
  <XPathsFault>
	<XPathFault>/apigee:Greeting/apigee:User</XPathFault>
  </XPathsFault>
  <JSONPathsFault>
	<JSONPathFault>$.store.book[*].author</JSONPathFault>
  </JSONPathsFault>
  <Variables>
	<Variable>request.header.user-agent</Variable>
    <Variable>request.formparam.password</Variable>
  </Variables>
</MaskDataConfiguration>' \
https://api.enterprise.apigee.com/v1/o/{org_name}/maskconfigs \
-u email:password
To create a mask configuration that is scoped to a specific API proxy:
$ curl -H "Content-type:text/xml" -X POST -d \
'<MaskDataConfiguration name="default">
  <XPathsRequest>
	<XPathRequest>/apigee:Greeting/apigee:User</XPathRequest>
  </XPathsRequest>
  <XPathsResponse>
    <XPathResponse>/apigee:Greeting/apigee:User</XPathResponse>
  </XPathsResponse>
  <JSONPathsRequest>
    <JSONPathRequest>$.store.book[*].author</JSONPathRequest>
  </JSONPathsRequest>
  <JSONPathsResponse>
	<JSONPathResponse>$.store.book[*].author</JSONPathResponse>
  </JSONPathsResponse>
  <XPathsFault>
	<XPathFault>/apigee:Greeting/apigee:User</XPathFault>
  </XPathsFault>
  <JSONPathsFault>
	<JSONPathFault>$.store.book[*].author</JSONPathFault>
  </JSONPathsFault>
  <Variables>
	<Variable>request.header.user-agent</Variable>
    <Variable>request.formparam.password</Variable>
  </Variables>
</MaskDataConfiguration>' \
https://api.enterprise.apigee.com/v1/o/{org_name}/apis/{api_name}/maskconfigs \
-u email:password

You can delete a mask configuration using the DELETE verb:

$ curl -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/apis/{api_name}/maskconfigs/{maskconfig_name} \
-u email:password

The response to a DELETE operation is an HTTP code 204 with no message content.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)