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

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.contentresponse.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>

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

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

フィールド名 説明 デフォルト 必須
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 プロパティの値がマスクされます。 なし ×
変数

値をマスクする(事前定義またはカスタム)変数のリスト。デフォルトの変数のリストについては、変数のリファレンスをご覧ください。

なし ×

マスク構成 API

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

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

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

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

特定の 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

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

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>