データのマスキングと非表示

Edge で API 呼び出しをデバッグする場合、コンテンツには、マスクする必要のあるクレジットカードや個人を特定できる医療情報（PHI）などの機密データが含まれることがあります。

Edge では、トレースセッションとデバッグセッションでセンシティブデータの非表示やマスキングなどの方法を複数用意しています。

機密データの非表示

接頭辞が「private.」のカスタム変数を作成することで、Trace ツールとデバッグセッションに機密データが表示されないようにできます。

たとえば、Key Value Map Operations ポリシーを使用し、暗号化された Key-Value マップから値を取得する場合、トレースセッションまたはデバッグセッションに値が表示されないようにするには、次のように変数名をフォーマットします。

<Get assignTo="private.hiddenData">

機密変数の非表示は、次に説明するデータマスキングの代替手法です。非表示とマスキングの違いは、非表示の変数が一切表示されないのに対し、マスクされた値はトレースセッションとデバッグセッションでアスタリスクに置き換えられる点です。

「private.」接頭辞の付いていない変数は、データが暗号化された Key-Value マップなどの暗号化されたデータストアから取得された場合でも、トレースセッションとデバッグセッション内ではクリアテキストで表示されます。これらの値をマスクするには、マスキング（下記）を使用します。

機密データのマスキング

Edge では、トレースセッションやデバッグセッションで特定のデータをマスクするための「マスク構成」を定義できます。マスク構成は、グローバル（組織レベル）またはローカル（API プロキシレベル）に設定できます。

データがマスクされると、トレース出力でアスタリスクに置き換えられます。例:

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

マスク構成の使用

マスク構成を使用すると、次のソースのセンシティブデータを識別できます。

XML ペイロード: XPath を使用して、リクエストメッセージまたはレスポンスメッセージのペイロードから除外する XML 要素を識別します。
JSON ペイロード: JSONPath を使用して、リクエストメッセージまたはレスポンスメッセージのペイロードから除外する JSON プロパティを識別します。
フロー変数: デバッグ出力でマスクする必要がある変数のリストを指定できます。request.content、response.content、またはmessage.content のフロー変数を指定すると、リクエスト本文またはレスポンス本文もマスクされます。

マスク構成の基本構造は、次の XML 表現で示されています。

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

マスク構成リソースの構成

次の要素を使用してマスク構成を定義します。

ヒント: ServiceCallout を使用してリクエストを行う場合、そのリクエストの情報は通常のマスク構成でマスクされません。ServiceCallout リクエスト情報をマスクする場合は、フロー変数 ServiceCallout.request を <MaskDataConfiguration> 構成の <Variables> 要素に追加します。

フィールド名	説明	デフォルト	必須
XPathsRequest	リクエストパスの XML ペイロード（ある場合）に対して評価される XPath 式のリスト。正常に解決された XPath では、XML 要素の値がマスクされます。	なし	×
XPathsResponse	レスポンスパスの XML ペイロード（ある場合）に対して評価される XPath 式のリスト。正常に解決された XPath では、XML 要素の値がマスクされます。	なし	×
JSONPathsRequest	リクエストパスの JSON ペイロード（ある場合）に対して評価される JSONPath 式のリスト。正常に解決された JSONPath では、JSON プロパティの値がマスクされます。	なし	×
JSONPathsResponse	レスポンスパスの JSON ペイロード（ある場合）に対して評価される JSONPath 式のリスト。正常に解決された JSONPath では、JSON プロパティの値がマスクされます。	なし	×
XPathsFault	（フローの任意のポイントで障害がスローされた場合に実行される）エラーフローの XML ペイロード（ある場合）に対して評価される XPath 式のリスト。正常に解決された XPath では、XML 要素の値がマスクされます。	なし	×
JSONPathsFault	（フローの任意のポイントで障害がスローされた場合に実行される）エラーフローの JSON ペイロード（ある場合）に対して評価される JSON 式のリスト。正常に解決された JSONPath では、JSON プロパティの値がマスクされます。	なし	×
変数	値をマスクする（事前定義またはカスタム）変数のリスト。デフォルトの変数のリストについては、変数のリファレンスをご覧ください。注: `request.content`、`response.content`、または `message.content` のフロー変数を指定すると、リクエスト本文またはレスポンス本文もマスクされます。	なし	×

マスク構成 API

マスク構成は、RESTful 管理 API を使用してアップロードおよびダウンロードする XML 形式または JSON 形式のファイルとして定義されます。データマスキング API の完全なリストについては、データマスクをご覧ください。

既存のマスク構成は、組織内の API リソース /maskconfigs を呼び出すだけで表示できます。

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

この例は、認証用の基本構文を示しています。Oauth2 や SAML など、他の種類の認証を使用することもできます。

特定の API プロキシに対して定義されたマスク構成を確認するには、/maskconfigs API を呼び出します。

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

特定のマスク構成を表示するには、マスクの名前を指定します。

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

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

マスク構成を作成するには、POST 動詞を使用して、マスク構成を定義するペイロードを送信します。

$ curl -H "Content-type:text/xml" -X POST -d \
'<MaskDataConfiguration name="default">
    <Namespaces>
        <Namespace prefix="myco">http://example.com</Namespace>
    </Namespaces>
    <XPathsRequest>
        <XPathRequest>/myco:Greeting/myco:User</XPathRequest>
    </XPathsRequest>
    <XPathsResponse>
        <XPathResponse>/myco:Greeting/myco:User</XPathResponse>
    </XPathsResponse>
    <JSONPathsRequest>
        <JSONPathRequest>$.store.book[*].author</JSONPathRequest>
    </JSONPathsRequest>
    <JSONPathsResponse>
        <JSONPathResponse>$.store.book[*].author</JSONPathResponse>
    </JSONPathsResponse>
    <XPathsFault>
        <XPathFault>/myco:Greeting/myco: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

特定の API プロキシにスコープが設定されたマスク構成を作成します。

$ curl -H "Content-type:text/xml" -X POST -d \
'<MaskDataConfiguration name="default">
    <Namespaces>
        <Namespace prefix="myco">http://example.com</Namespace>
    </Namespaces>
    <XPathsRequest>
        <XPathRequest>/myco:Greeting/myco:User</XPathRequest>
    </XPathsRequest>
    <XPathsResponse>
        <XPathResponse>/myco:Greeting/myco:User</XPathResponse>
    </XPathsResponse>
    <JSONPathsRequest>
        <JSONPathRequest>$.store.book[*].author</JSONPathRequest>
    </JSONPathsRequest>
    <JSONPathsResponse>
        <JSONPathResponse>$.store.book[*].author</JSONPathResponse>
    </JSONPathsResponse>
    <XPathsFault>
        <XPathFault>/myco:Greeting/myco: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

マスク構成を削除するには、DELETE 動詞を使用します。

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

この例は、認証用の基本構文を示しています。Oauth2 や SAML など、他の種類の認証を使用することもできます。

DELETE オペレーションに対するレスポンスは、メッセージコンテンツのない HTTP コード 204 です。

XML 名前空間のマスキング

マスク構成では、XML ペイロードで名前空間が定義されていない限り、XPATH 定義に <Namespace> 要素は必要ありません。XML ペイロードがデフォルトの名前空間を使用する場合も同様です。

たとえば、XML ペイロードは名前空間を定義しません。

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

そのため、マスク構成には <Namespace> 要素は必要ありません。

<MaskDataConfiguration>
    <XPathsRequest>
        <XPathRequest>/employee/name</XPathRequest>
    <XPathsRequest>
</MaskDataConfiguration>

XML ペイロードに名前空間と接頭辞が含まれている場合:

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

次に、マスク構成の定義に <Namespace> 要素を含める必要があります。

<MaskDataConfiguration>
    <Namespaces>
        <Namespace prefix="myco">http://example.com</Namespace>
    </Namespaces>
    <XPathsRequest>
        <XPathRequest>/myco:employee/myco:name</XPathRequest>
    <XPathsRequest>
</MaskDataConfiguration>

XML ペイロードに名前空間があるものの接頭辞がない場合、すなわちデフォルトの名前空間の場合:

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

次に、ここでもマスク構成に <Namespace> 要素を含める必要があります。

<MaskDataConfiguration>
    <Namespaces>
        <Namespace prefix="myco">http://example.com</Namespace>
    </Namespaces>
    <XPathsRequest>
        <XPathRequest>/myco:employee/myco:name</XPathRequest>
    <XPathsRequest>
</MaskDataConfiguration>