# 確認結果へのアクセス 機密データである確認結果にアクセスする方法をご紹介します。 [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. 機密データのアクセス要件を慎重に検討します。 2. 制限付きの API キーを作成します。 3. 機密データである確認結果を取得するには、API リクエストをします。 4. キーが不正にアクセスされた場合、キーを更新します。 5. 機密データである確認結果とセキュリティー対策をユーザーに知らせます。 6. 機密データである確認結果に長期的にアクセスするには、キーにIP 制限を追加します。 ## 機密データのアクセス要件を慎重に検討します ユーザーのプライバシーを優先する 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)をクリックします。 2. キーに名前を付けます。 3. **本人確認結果**および**最近の詳細な確認結果**の権限が、**読み取り**に設定されていることを確認します。 4. (オプション) 収集された画像へのアクセスが必要な場合は、ファイルの**書き込み**権限を追加します。 5. **キーを作成**をクリックします。 6. キーは安全に保管してください。[キーの安全管理についてもっと知る](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 キーを使用して認証する。 2. アクセス対象のフィールドを[拡張](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)に入ります。 2. オーバーフローメニュー (**…**) で、ステップ 1 で作成した制限付きキーの **IP 制限の管理**をクリックします。 3. 本番サーバーの 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)の追加について、詳しくはこちらをご覧ください。 4. キーを**保存する** 5. キーを編集して、**すべての詳細な確認結果**の権限を追加します。 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)