workflow_idを指定する必要もありません。
バックエンドが認証を開始してその結果を取得し、インターフェースが、ウォレットで要求される認証を本人が完了できるよう案内します。
API連携であっても、本人が認証を行い、身元情報の共有を承認する必要があります。
そのような操作なしに、個人識別子を送信するだけで本人を認証することはできません。
認証の仕組み
- バックエンドでウォレットカタログを確認し、アプリケーションのAPIキーを使って、利用可能なウォレットのstartエンドポイントを呼び出します。
- Diditは認証の参照情報と、本人が行う必要のあるアクションを返します。
- アプリケーションで認証ページを開くか、ウォレットの承認手順を表示します。
- 本人がウォレットで認証を行います。
- バックエンドで認証結果を取得し、完了通知を処理します。
バックエンド連携
デジタルIDウォレットの一覧取得を使用して、アプリケーションで利用できる最新のエンドポイント、必須フィールド、提供状況を取得します。x-api-keyはバックエンドで管理してください。
ブラウザ用のバンドルやモバイルアプリケーションには含めないでください。
新しい認証の試行ごとに異なるIdempotency-Keyを使用し、同じ開始リクエストを再試行する際にはそのキーを再利用してください。
キーを再利用しながらリクエスト内容を変更すると、新しい認証の試行ではなく競合として扱われます。
各ウォレットには固有の開始URLがあります。たとえばFinnish Trust Networkの場合は/v3/id-verification/wallets/ftn/です。
request_idは、以降の操作でスタンドアロン認証を識別するためのものです。
独自の参照情報には最大2,000 UTF-8バイトまでのvendor_dataを使用し、任意のJSONオブジェクトにはmetadataを使用します。
どちらも結果と完了Webhookに含まれて返されます。
これらの操作には、認証を開始したアプリケーションのAPIキーを使用します。
ポーリングと認証の利用可否は、選択したウォレットによって異なります。
キャンセルを行うと、保留中の認証は料金が発生することなく却下され、完了済みの認証は変更されずにそのまま返されます。
Smart-IDとMobile-IDでは、ポーリングが承認を確認している最中にキャンセルが届いた場合、そのポーリングの完了を数秒間待機します。
その後、認証を却下するか、本人がすでに承認していた場合は
verifiedとして返します。
本人がまさに完了しようとしている認証はキャンセルできません。この場合、レスポンスは409となり、error: "verification_in_progress"とRetry-Afterヘッダーが返されます。
指定された秒数が経過してから再試行し、完了した結果を取得してください。
戻り先を登録する
リダイレクト型のウォレットは、認証後に本人をアプリケーションへ戻します。 認証を開始する前に、正確なホスト名を登録してください。return_url(例: https://app.example.com/identity/complete)を送信します。
allowed_return_hostsには、スキーム、パス、ワイルドカードを含まないホスト名のみを指定してください。
使用するサブドメインはそれぞれ個別に登録し、最大20個のホスト名まで登録できます。
allowed_return_hostsを更新すると登録済みのリストが置き換えられるため、残したいホスト名はすべて含めてください。
GET /v3/webhook/は現在のリストを返します。詳しくはWebhookの設定を参照してください。
戻り先の登録に、ワークフローやホワイトラベルのドメインは必要ありません。
戻り先はブラウザで表示される戻りページです。バックエンド向けの完了Webhookは別途設定してください。
Finnish Trust Networkの例
戻り先のホスト名を登録したら、Finnish Trust Networkの認証を開始します。request_idを保存し、typeがredirectの場合は本人のブラウザをwallet_verification.next_action.urlにリダイレクトさせます。
本人が戻ってきたら、バックエンドから結果を取得します。
wallet_verification.outcomeを確認します。
実際の本人確認では、結果が
verifiedで、かつsimulatedがfalseの場合にのみ身元情報を使用してください。
保留中のレスポンスには次のアクションが含まれる場合がありますが、最終状態のレスポンスには次のアクションは含まれません。
認証方式
リダイレクト型ウォレットは認証URLを返します。 そのURLを本人のブラウザで開き、ウォレットの認証プロセスを完了してもらってから、登録済みの戻り先に戻してください。 戻りURLのパラメーターを本人確認の証拠として信頼せず、結果はバックエンドから取得してください。 Smart-IDとMobile-IDは、本人のスマートフォンに表示される承認プロンプトを使用します。 必要な個人識別子はお客様のインターフェースで収集します。Mobile-IDでは、紐づく電話番号も必要です。 照合コードを表示し、スマートフォンに表示されたコードと一致する場合にのみ承認するよう本人に案内してください。 PINはウォレットまたはスマートフォンのプロンプトで入力するものであり、お客様のフォームやAPIリクエストで扱ってはなりません。 返されたpoll_interval_secondsの間隔で、プロンプトの応答をバックエンドからポーリングしてください。
Diditは保留中のスマートフォン承認もバックグラウンドで確認するため、本人がページを閉じた後でも完了通知がWebhookに届くことがあります。
Google Walletには、リダイレクトを使わず、Digital Credentials APIを通じてお客様自身のページやアプリから要求します。詳しくはDigital Credentialsウォレット (Google Wallet)を参照してください。
利用できる操作方法は、選択したウォレットによって異なります。
すべてのウォレットが埋め込みフォーム、QRコード、ブラウザを使わない認証に対応していると想定しないでください。
Digital Credentialsウォレット (Google Wallet)
Google Walletには、W3C Digital Credentials APIを使用して、お客様のWebページまたはAndroidアプリから直接要求します。 リダイレクト、Diditがホストするページ、DiditのQRコードはいずれもありません。 本番環境では近日公開です。サンドボックスアプリケーションとステージング環境では動作し、本番環境での利用はGoogleの承認後に可能になります。 お使いのアプリケーションで現在開始できるものは、デジタルIDウォレットの一覧で確認してください。1
オリジンを指定して開始する
バックエンドから、本人の
country(USA、GBR、BRA、SGPまたはTWN)と、ウォレットに要求を行うoriginを指定してPOST /v3/id-verification/wallets/google-wallet/を呼び出します。
originはhttps://app.example.comのようなページのHTTPSオリジンであり、そのホストは登録済みの戻り先ホスト名またはホワイトラベルドメインのいずれかである必要があります。
Androidアプリの場合は、android:apk-key-hash:の後に、アプリの署名証明書のSHA-256をパディングなしのbase64で続けたものです。
ウォレットは、それ以外のオリジンからのリクエストを拒否します。
return_urlはありません。2
ユーザー操作の中でウォレットに要求する
レスポンスには
wallet_verification.interaction = "digital_credentials"とnext_action.type = "request_digital_credential"が含まれます。
開始時に指定したoriginでのタップまたはクリックをきっかけに、next_action.digital_credentials.requestをブラウザまたはAndroid Credential Managerに渡します。
デスクトップでは、ウォレットが別のデバイスにある場合、ブラウザが独自のQRコードを表示します。3
ウォレットが返した内容を送信する
返された
{protocol, data}をバックエンドに送り、そこから{"response": {...}}としてPOST /v3/id-verification/wallets/verifications/{request_id}/response/に送信します。
リクエストを送信できるのは1回のみです。2回目の送信では、すでに判定済みの認証が返されます。4
結果を取得する
送信に対するレスポンスは判定済みの認証です。
GET /v3/id-verification/wallets/verifications/{request_id}/で取得するか、完了Webhookで受け取ることもできます。"DigitalCredential" in windowがtrueの場合など、ブラウザが対応している環境でのみ提供してください。
navigator.credentials.getはユーザー操作の中で実行する必要があるため、非同期処理の後ではなく、クリックハンドラーから呼び出してください。
Androidでは、同じリクエストでJetpack Credential Manager(androidx.credentials 1.5.0以降)を使用します。
検証に失敗した資格情報は、エラーレスポンスではなく、結果が
failedの判定済み認証になります。
ウォレットから送信されるのは認証が要求するフィールドのみで、結果にはウォレットが返した本人属性が含まれます。
Google WalletのIDパスや米国州のモバイル運転免許証は、顔写真を返しません。
サンドボックスアプリケーションでは、同じステップでフローがシミュレートされ、simulated: trueが返されます。
送信されたレスポンスはいずれもsandbox_scenarioに従って認証を判定するため、実際の資格情報がなくてもブラウザやアプリの一連の流れを構築できます。
完了Webhook
Webhook連携ガイドに従って、status.updated用のアプリケーションのWebhookの送信先を設定してください。
ここで説明する判定の構造を使用するには、webhook_version: "v3"を使用してください。
処理する前に、バックエンドでWebhookの署名を検証してください。
Webhookのsession_idは、ウォレットAPIが返すrequest_idと一致します。
完了したウォレット本人確認は、Webhookのdecision.id_verifications配列にverification_method: "wallet"として含まれます。
この識別子を使用して、ウォレット専用APIの結果を取得することもできます。
承認と却下の通知を処理してください。キャンセルされた認証や期限切れの認証も含みます。
失敗した配信は再試行されるため、Webhookハンドラーは冪等にしてください。
ブラウザでの戻りは完了Webhookではなく、そのクエリパラメーターは本人確認の証拠にはなりません。
返される本人情報
氏名と生年月日については、正規化された本人情報フィールドが返される場合はそれを使用してください。 ウォレット固有の属性は、選択したウォレットが共有した本人情報を表します。 利用できる属性はウォレットと国によって異なります。 本人の認証が完了しても、顔写真、住所、その他要求したすべての属性が利用できるとは限りません。サンドボックスでのテスト
Didit のサンドボックスモードのアプリケーションは、ウォレットプロバイダーに接続することなく、またクレジットを消費することなく、ウォレット認証をシミュレートします。 これらのリクエストは、レスポンス内のwallet_verification.simulated: trueで識別できます。
シミュレートされた承認はサンプルデータであり、実在の人物の本人確認が完了したことを示すものではありません。
リダイレクト型ウォレットの場合は、返されたURLにアクセスして、コールバックを実行し、アプリケーションに戻ります。
Smart-IDまたはMobile-IDの場合は、ポーリングエンドポイントを使用してシミュレートされた承認を完了します。電話への通知は送信されません。
失敗時の処理をテストするには、リクエストの開始時にsandbox_scenarioをwallet_cancelled、wallet_timeoutまたはwallet_provider_errorに設定します。
本番環境のアプリケーションはsandbox_scenarioを拒否します。
Didit のサンドボックスシミュレーションは、プロバイダー独自のテスト環境でのテストとは別のものです。
シミュレーションが成功しても、本番環境でプロバイダーにアクセスできることや、本番環境で利用できることが確認されたわけではありません。
ConnectIDプロバイダーのサンドボックス
ConnectIDのプロバイダーサンドボックスはテスト用の銀行を使用し、Didit のサンドボックスシミュレーションとは別のものです。 連携に対してプロバイダーサンドボックスへのアクセスが設定されている場合は、選択した銀行のauthorisation_server_idをConnectID開始エンドポイントに渡します。
ConnectIDの銀行選択画面から返されたIDを使用してください。銀行のURLや任意の発行者を送信しないでください。
このフィールドを省略すると、デフォルトのテスト用銀行が選択されます。
このフィールドはConnectID固有のものであり、要求する本人情報の属性は変わりません。
初期のバンドルでは、名、姓、生年月日を要求します。
返されたnext_actionに従って認証を行い、その後に認証結果を取得またはポーリングします。
認証の成功を確定できるのは、ステータスが承認済みである完了した結果のみです。アプリケーションに戻ったことは認証の成功を意味しません。
ConnectIDは、オンボーディングと認定が完了するまで、本番環境では引き続きComing soonとなります。