応答データの難読化
Cloud API は、応答に含まれているデータの難読化をサポートしています。応答データは無効化することもマスクすることもできます。
- 応答データが無効化されている場合は、その値が null として返されます。
- 応答データがマスクされている場合は、そのデータの一部がプレースホルダ文字付きで返されます。例えば、納税者番号が「xxx-xx-1781」として返される場合です。
難読化された応答データの主要なタイプは、個人情報（PII）です。保険会社は、その所在地の管轄のデータ保護およびプライバシー規則に従う必要があります。例えば、欧州連合で運営している会社は、その管轄内の一般データ保護規則（GDPR）に従う必要があります。このような規則では、多くの場合、個人情報（PII）を難読化するように義務付けられています。
応答データの無効化
応答データは、関連プロパティ用にマッパーをコンフィギュレーションすることによって無効化できます。これは、マッピング拡張ファイルで行われます。マッピング拡張ファイルの詳細については、コンフィギュレーションファイルの概要を参照してください。
ClaimContact リソース用のスキーマには、taxId プロパティが含まれています。
例えば、クレームには ClaimContact が含まれています。ビジネスの目的によっては、ClaimContact に関する税識別情報を取得しなければならない場合があります。後で、システム API の呼び出し元が ClaimContact を要求し、応答内のその連絡先の納税者番号を表示できます。このデータの公開を避けるために、リソースマッパーでその値を無効化できます。
"ClaimContact": {
"type": "object",
"x-gw-extensions": {
"discriminatorProperty": "contactSubtype"
},
"properties": {
. . .
"taxId": {
"type": "string"
},
. . .
}
}taxId プロパティの値を無効化するには、次のように、ClaimContact マッパーでそのプロパティを変更します。
"ClaimContact": {
"schemaDefinition": "ClaimContact",
"root": "entity.ClaimContact",
"properties": {
. . .
"taxId": {
"path": "null as String",
"predicate": "false"
},
. . .
}
}taxId.path プロパティを "null as String" に設定すると、期待値が null 文字列に変換されます。taxId.predicate を false に設定すると、元の値、このケースでは PII が評価されなくなります。
応答データのマスク
応答データは、Gosu メソッドを作成し、そのメソッドを使用するように関連リソースプロパティ用のマッパーを変更することによって、マスクすることができます。
- Gosu コードの実装に関する詳細については、『コンフィギュレーションガイド』を参照してください。
- マッピング拡張ファイルの詳細については、コンフィギュレーションファイルの概要を参照してください。
例えば、クレームには ClaimContact が含まれています。ビジネスの目的によっては、ClaimContact に関する税識別情報を取得しなければならない場合があります。後で、システム API の呼び出し元が ClaimContact を要求し、応答内のその連絡先の納税者番号を表示できます。このデータの公開を制限するために、その値をマスクすることができます。
ClaimContact リソース用のスキーマには、taxId プロパティが含まれています。
"ClaimContact": {
"type": "object",
"x-gw-extensions": {
"discriminatorProperty": "contactSubtype"
},
"properties": {
. . .
"taxId": {
"type": "string"
},
. . .
}
}このプロパティは、ClaimContact.Contact エンティティの TaxID フィールドにマップされます。納税者番号文字列をマスクする、このエンティティ用の Gosu メソッドを作成する必要があります。この例では、メソッドは maskTaxId という名前です。
その後で、次のように、ClaimContact マッパー内の taxId プロパティを変更します。
"ClaimContact": {
"schemaDefinition": "ClaimContact",
"root": "entity.ClaimContact",
"properties": {
. . .
"taxId": {
"path": "ClaimContact.Contact.maskTaxId(ClaimContact.Contact.TaxID)"
},
. . .
}
}taxId.path プロパティが ClaimContact.Contact.maskTaxId(ClaimContact.Contact.TaxID) に設定されている場合は、呼び出し元に公開される前に、TaxID の値が maskTaxId メソッドを介して渡されます。
マスクパターンの変更
リソースプロパティに適用されたマスクパターンを変更するために、既存のマスク Gosu メソッドを変更することも、新しいメソッドを作成することもできます。
PII のマスク解除
逆に、ベースコンフィギュレーションでマスクされた PII をマスク解除できます。これは、PII を管理者などの特定の内部役割に公開する必要がある場合に必要になります。このような状況では、マスクされたプロパティ用の新しいスキーマ拡張を作成するように推奨されています。例えば、taxId プロパティをマスク解除したい場合は、TaxID エンティティフィールドに直接マップされる taxIdUnmasked_Ext スキーマプロパティを作成します。このようなケースでは、拡張されたプロパティを許可リストに登録して、認定された役割だけが表示できるようにすることも推奨されています。リソース拡張の作成に関する詳細については、スキーマコンフィギュレーションの概要を参照してください。フィールドの許可リスト登録に関する詳細については、『Cloud API 認証ガイド』で API 役割ファイルに関するセクションを参照してください。
taxId をフィルタ可能なパラメータまたは並べ替え可能として指定すると、URL の一部として要求内に含めることができるため、アプリケーションログに表示される可能性があります。ベースコンフィギュレーション taxID フィールドのマスク解除
Contact リソースには、連絡先の納税者番号を保存する taxID フィールドがあります。クラウド API のベースコンフィギュレーションでは、このフィールドは応答内でマスクされており、末尾 4 桁のみが表示されます。例えば、以下は連絡先を取得する GET の応答です。
{
"data": {
"attributes": {
"displayName": "Ray Newton",
"taxId": "***-**-6789"
}
}
}一部の呼び出し元（内部または外部のユーザーなど）では、個人識別情報の保護のために納税者番号のマスクは適切な場合があります。しかし、その他の呼び出し元（サービスなど）では、このマスクのために、呼び出し元が納税者番号を使用して連絡先を内部参照することがあり、問題が生じる可能性があります。
taxId フィールドのマスクを解除するには、次の 2 つの方法があります。
- 前のトピックで説明したように、常にマスクされていない状態にフィールドをコンフィギュレーションできます。
- 呼び出し元に
restunmasktaxidシステム権限を付与できます。この権限を持つ役割の呼び出し元は、マスクされていない納税者番号を含む応答を取得します。このコンフィギュレーション方法の詳細については、『Cloud API 認証ガイド』の API 役割の特別な権限に関するセクションを参照してください。
restunmasktaxid システム権限は、ベースコンフィギュレーション taxId フィールドの動作しか変更しないことに注意してください。他のマスクされたデータには影響を与えません。