# 確認結果へのアクセス 機密データである確認結果にアクセスする方法をご紹介します。 [ID 文書を収集するためのモーダルを表示するコードを記述できます](https://docs.stripe.com/identity/verify-identity-documents.md)。また、[検証結果を処理します](https://docs.stripe.com/identity/handle-verification-outcomes.md)。後日、ユーザーの生年月日や収集した文書の写真など、機密性の高い検証結果にアクセスする必要がある場合があります。そのためのオプションがいくつかあります。 まず、[Identity ダッシュボード](https://dashboard.stripe.com/identity)を使用して、機密データである確認結果にアクセスすることを検討します。必要な場合、Stripe アカウントへの[制御されたアクセスをチームメンバーに付与します](https://docs.stripe.com/get-started/account/teams.md)。こうすることで、開発時間が削減され、機密情報である確認データが Stripe で[安全に](https://support.stripe.com/questions/managing-your-id-verification-information)保たれるようになります。 [シークレットキー](https://docs.stripe.com/keys.md)を使用して、確認チェックの結果やユーザーの名前と住所など、[ほとんどの確認の詳細にプログラムでアクセス](https://docs.stripe.com/identity/verification-sessions.md#results)できます。より機密性の高いフィールドへのアクセスには、[制限付き API キー](https://docs.stripe.com/keys-best-practices.md#limit-access)が必要です。 | 確認結果 | ダッシュボードでの使用 | シークレットキーによるアクセス | 制限付きの API キーへのアクセス | 推奨される確認セッション (Recommended Verification Session) フィールド | Expand プロパティ | | --------- | ----------- | --------------- | ------------------ | ------------------------------------------------------------ | --------------------------------------------------- | | 住所 | ✓ はい | ✓ はい | ✓ はい | `verified_outputs.address` | `verified_outputs` | | 書類の種類 | ✓ はい | ✓ はい | ✓ はい | `last_verification_report.document.type` | `last_verification_report` | | 氏名 | ✓ はい | ✓ はい | ✓ はい | `verified_outputs.first_name and verified_outputs.last_name` | `last_verification_report` | | 書類の発行国 | ✓ はい | ✓ はい | ✓ はい | `last_verification_report.document.issuing_country` | `last_verification_report` | | 検証チェックの結果 | ✓ はい | ✓ はい | ✓ はい | `status` | Expand は不要 | | 書類の発行日 | ✓ はい | ✓ はい | ✓ はい | `last_verification_report.document.issued_date` | `last_verification_report` | | ID 番号の種類 | ✓ はい | ✓ はい | ✓ はい | `last_verification_report.document.id_number.type` | `last_verification_report` | | メールアドレス | ✓ はい | ✓ はい | ✓ はい | `verified_outputs.email` | `verified_outputs` | | 電話番号 | ✓ はい | ✓ はい | ✓ はい | `verified_outputs.phone` | `verified_outputs` | | 書類の有効期限 | ✓ はい | ✗ いいえ | ✓ はい | `last_verification_report.document.expiration_date` | `last_verification_report.document.expiration_date` | | 生年月日 | ✓ はい | ✗ いいえ | ✓ はい | `verified_outputs.dob` | `verified_outputs.dob` | | 書類の ID 番号 | ✓ はい | ✗ いいえ | ✓ はい | `last_verification_report.document.number` | `last_verification_report.document.number` | | 書類の画像 | ✓ はい | ✗ いいえ | ✓ はい | `last_verification_report.document.files` | `last_verification_report` | | 顔の画像 | ✓ はい | ✗ いいえ | ✓ はい | `last_verification_report.selfie.selfie` | `last_verification_report` | | ID 番号 | ✓ はい | ✗ いいえ | ✓ はい | `verified_outputs.id_number` | `verified_outputs.id_number` | 制限付き API キーを使用すると、それに関連するセキュリティー対策に基づきアクセスが許可されます。 - **制限付きキー**: 過去 48 時間に処理された検証を対象に、機密データである確認結果へのアクセスを許可します。 - **制限付きの API キー**: すべての検証を対象に機密データである確認結果へのアクセスを許可します。 このガイドでは、以下の方法を説明します。 1. 機密データのアクセス要件を慎重に検討します。 1. 制限付きの API キーを作成します。 1. 機密データである確認結果を取得するには、API リクエストをします。 1. キーが不正にアクセスされた場合、キーを更新します。 1. 機密データである確認結果とセキュリティー対策をユーザーに知らせます。 1. 機密データである確認結果に長期的にアクセスするには、キーにIP 制限を追加します。 1. 機密データのアクセス要件を慎重に検討します。 1. 制限付きの API キーを作成します。 1. 機密データである確認結果を取得するには、API リクエストをします。 1. キーが不正にアクセスされた場合、キーを更新します。 1. 機密データである確認結果とセキュリティー対策をユーザーに知らせます。 ## 機密データのアクセス要件を慎重に検討します ユーザーのプライバシーを優先する Stripe Identity でシステムを構築するには、アクセスする必要がある最小限の PII をまず決定します。最も機密性が高いデータ (制限付きの API キーによる認証を必要とするもの) にアクセスする必要がない場合は、シークレットキーのみを使用して認証するように実装を設定できます。 確認から得られた PII にアクセスするには、VerificationSession を取得し、[verified_outputs](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-verified_outputs) フィールドまたは (確認結果についてより詳細な情報が必要な場合は) [last_verification_report](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-last_verification_report) のいずれかを[展開](https://docs.stripe.com/api/expanding_objects.md)します。これらのフィールドのいずれかを展開すると、シークレットキーのみを必要とする PII フィールドがすべて自動的に含まれます。 `verified_outputs` フィールドを展開して、Stripe Identity によって本人確認が行われたユーザーの名前を取得する例を次に示します。 #### Node.js ```javascript // Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. // Find your keys at https://dashboard.stripe.com/apikeys. const stripe = require('stripe')('<>'); const verificationSession = await stripe.identity.verificationSessions.retrieve( '{{SESSION_ID}}', { expand: [ 'verified_outputs', ], } ); const firstName = verificationSession.verified_outputs.first_name; ``` 制限付きのキーを必要とする機密 PII にアクセスする必要がない場合は、このガイドのステップに従ってください。 ## 制限付き API キーを作成する [ダッシュボード] アカウントのシークレットAPIキーを使用して、制限なく API リクエストを実行できます。機密性の高い確認結果にアクセスするには、より安全な[制限付きキー](https://docs.stripe.com/keys-best-practices.md#limit-access)が必要です。 制限付きキーを新規作成する 1. ダッシュボードの [API キーのページ](https://dashboard.stripe.com/apikeys)に移動して、[**制限付きのキーを作成**](https://dashboard.stripe.com/apikeys/create)をクリックします。 1. キーに名前を付けます。 1. Identity の**確認セッションとレポート**、および**Access recent sensitive verification results (最近の機密データである確認結果にアクセス** の権限が **読み取り**に設定されていることを確認します。 1. (オプション) 収集された画像へのアクセスが必要な場合は、ファイルの**書き込み**権限を追加します。 1. **キーを作成**をクリックします。 1. キーは安全に保管してください。[キーの安全管理についてもっと知る](https://docs.stripe.com/keys-best-practices.md)。 ![](https://b.stripecdn.com/docs-statics-srv/assets/rak_identity_permissions.51347778adedec20ad9aaec2cb5a5bb9.png) ## 機密データである確認結果を取得するために API リクエストをする [サーバー側] [VerificationReport](https://docs.stripe.com/api/identity/verification_reports.md) には、送信されたセッションから収集されたすべてのデータと確認結果が含まれます。セッションのすべての本人確認チェックが処理されると VerificationReport が作成されます。VerificationReport を確認することで、本人確認チェックが失敗した理由と、どのデータが正常に確認されたかを把握できます。 [last_verification_report](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-last_verification_report) セッションフィールドを[拡張](https://docs.stripe.com/expand.md)することで、関連する VerificationReport を取得できます。 デフォルトでは、VerificationReports に機密データである確認結果は含まれません。これらにアクセスするには、次のことを行う必要があります。 1. ステップ 1 で作成した制限付きの API キーを使用して認証する。 1. アクセス対象のフィールドを[拡張](https://docs.stripe.com/api/expanding_objects.md)する。 ここでは、[書類チェック](https://docs.stripe.com/identity/verification-checks.md?type=document)で抽出された生年月日、ID 番号、書類の番号にアクセスする例を示します。 #### Node.js ```javascript // Set your restricted key. Remember to switch to a live restricted key in production. // See your keys here: https://dashboard.stripe.com/apikeys const stripe = require('stripe')('rk_test_...'); const verificationSession = await stripe.identity.verificationSessions.retrieve( '{{SESSION_ID}}', { expand: [ 'verified_outputs.dob', 'verified_outputs.id_number', 'last_verification_report.document.number', 'last_verification_report.document.expiration_date', ], } ); const dateOfBirth = verificationSession.verified_outputs.dob; const idNumber = verificationSession.verified_outputs.id_number; const documentNumber = verificationSession.last_verification_report.document.number; const documentExpirationDate = verificationSession.last_verification_report.document.expiration_date; ``` ## 収集された画像へのアクセス セッションの一部として収集された本人確認書類および顔画像は、[File Upload API](https://docs.stripe.com/file-upload.md) を使用して取得できます。VerificationReport の以下のフィールドは、Stripe API の [File (ファイル)](https://docs.stripe.com/api/files.md) リソースへの参照を保持できます。 - [document.files](https://docs.stripe.com/api/identity/verification_reports/object.md#identity_verification_report_object-document-files) - 本人確認書類の画像 - [selfie.document](https://docs.stripe.com/api/identity/verification_reports/object.md#identity_verification_report_object-selfie-document): 写真付き本人確認書類の表面の画像 - [selfie.selfie](https://docs.stripe.com/api/identity/verification_reports/object.md#identity_verification_report_object-selfie-selfie): ユーザーの顔写真画像 > 書類と顔の画像は非常に機密性が高く、ドイツなど一部の国では、身分証の画像を共有したり、必要以上に長く保管することが法律で禁止されています。画像コンテンツにはできるだけ有効期限の短い FileLinks でアクセスし、ファイルコンテンツのコピーは作成しないようにします。また、セッションや収集された画像は収集した目的での使用を終えたら、収集された画像や[セッションを非表示にします](https://docs.stripe.com/identity/verification-sessions.md#redact)。 ファイルのコンテンツにアクセスするには、事前に作成した制限付きのキーを使用して認証を行い、有効期限の短い [FileLink を作成](https://docs.stripe.com/api/file_links/create.md)し、[url](https://docs.stripe.com/api/file_links/object.md#file_link_object-url) をクライアントに送信する必要があります。 #### Node.js ```javascript // Set your restricted key. Remember to switch to a live restricted key in production. // See your keys here: https://dashboard.stripe.com/apikeys const stripe = require('stripe')('rk_test_...'); // Get the VerificationReport const session = await stripe.identity.verificationSessions.retrieve( '{{SESSION_ID}}', { expand: ['last_verification_report'], } ); // Retrieve the File id const report = session.last_verification_report; const documentFrontFile = report.document.files[0]; // Create a short-lived FileLink const fileLink = await stripe.fileLinks.create({ file: documentFrontFile, expires_at: Math.floor(Date.now() / 1000) + 30, // link expires in 30 seconds }); // Access the FileLink URL to download file contents const fileUrl = fileLink.url; ``` > 書類および顔写真ファイルの FileLinks は 30 秒以内に期限切れになります。ファイルの内容はサーバーにダウンロードせずに、FileLink URL をクライアントに送信して画像を表示することをお勧めします。 Identity によって収集された機密データに攻撃者がアクセスしたと思われる場合は、[サポートにお問い合わせください](https://support.stripe.com/contact)。 ## キーが不正にアクセスされた場合、そのキーを更新します [ダッシュボード] Identity 権限のみを持つ制限付きの API キーを使用すると、他の Stripe 製品の組み込みに影響を与えることなく、緊急時にキーを更新できます。 制限付きキーの使用状況を定期的に監視し、キーにアクセスしている者がいないか確認することをお勧めします。[ダッシュボード](https://dashboard.stripe.com/apikeys)でオーバーフローメニュー (**…**) を使用して、特定の API キーのリクエストログを表示し、そのキーから行われたすべてのリクエストを確認できます。 API キーが不正にアクセスされた場合は、そのキーを[ダッシュボード](https://dashboard.stripe.com/apikeys)で更新してブロックし、新規キーを生成します。不正行為者が機密情報を取得するのを防ぐために、ただちにキーを失効させてください。 > 更新すると、当該の API キーがブロックされ、新しいキーが生成されます。[セキュリティ履歴](https://dashboard.stripe.com/security_history)を参照して、このキーに関連するイベントを確認することをお勧めします。このキーで作成した Webhook エンドポイントは、このキーの更新後も引き続き有効です。 Identity によって収集された機密データに攻撃者がアクセスしたと思われる場合は、[サポートにお問い合わせください](https://support.stripe.com/contact)。 ## 機密データの使用とセキュリティ対策について知らせます。 プライバシーポリシーに機密データである確認結果の司法方法が含まれていることを確認します。これは、セキュリティの取り扱いに関する方法を提供することも有益です。 **参照情報** - [ビジネスとして本人確認データを扱う際のプライバシーへの考慮事項](https://support.stripe.com/questions/privacy-considerations-for-handling-id-verification-data-as-a-business) - [ユーザーに提供する FAQ](https://docs.stripe.com/identity/explaining-identity.md) ## Optional: 結果に長期的にアクセスできるように、IP 制限を追加します [ダッシュボード] 機密データである確認結果にプログラムで長期的にアクセスすると、API キーの漏洩による影響が増加します。こうすることが、実際のユースケースでどうしても必要かどうかご判断ください。サポートが必要な場合は、[サポートにお問い合わせください](https://support.stripe.com/contact)。 **機密データである確認結果へのアクセス**権限を持つ制限付きのAPI キーを使用すると、過去 48 時間に送信された確認にプログラムでアクセスできます。 48 時間を超える確認にプログラムでアクセスする場合、IP 制限を追加して、制限付きのキーに新たにセキュリティを追加する必要があります。 1. ダッシュボードの [API キーのページ](https://dashboard.stripe.com/apikeys)に入ります。 1. オーバーフローメニュー (**…**) で、ステップ 1 で作成した制限付きキーの **IP 制限の管理**をクリックします。 1. 本番サーバーの IP アドレスを指定します。これらの原点を単純に IP v4 アドレスとして記述するか、または IP アドレスの全範囲を CIDR ([Classless Inter-Domain Routing](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing)) 記法で記述することができます。[IP キーの制限](https://docs.stripe.com/keys-best-practices.md#ip-allowlist)の追加について、詳しくはこちらをご覧ください。 1. キーを**保存する** 1. キーを編集して、**機密データである確認結果へのアクセス**許可を追加します。 48 時間より前に送信された機密データである確認結果にアクセスできるようになりました。 ## See also - [レスポンスを拡張する](https://docs.stripe.com/api/expanding_objects.md) - [API キー](https://docs.stripe.com/keys.md) - [Stripe のセキュリティ](https://docs.stripe.com/security.md)