メインコンテンツまでスキップ

身元確認/eKYC

← 導入ガイドに戻る

できること​

本人確認フローの統合管理​

eKYCの申込みから審査結果の反映まで、一貫して管理できます。

外部eKYCサービスとの連携を柔軟に設定し、あなたのサービス独自の本人確認フローを構築できます。

申込みプロセスの柔軟な設計​

外部eKYCサービスのAPI仕様に合わせた申込みフローを構築できます。

  • 複数ステップの管理: 基本情報入力 → 書類撮影 → 完了確認
  • プロセス依存関係: 前のステップ完了を必須化
  • リトライ制御: 書類撮影失敗時の再実行を許可
  • ステータス遷移: 申込み中 → 審査中 → 承認/否認の流れ

典型的な流れ:

1. ユーザーが基本情報を入力（氏名、生年月日、住所）
2. 書類撮影（運転免許証、マイナンバーカード）
3. 外部eKYCサービスに送信
4. 審査中
5. 審査結果を受信（承認/否認）

外部eKYCサービスとの連携​

専門事業者のAPIと柔軟に連携できます。

  • HTTP/REST APIでの連携
  • OAuth 2.0、HMAC、Basic認証に対応
  • リクエスト/レスポンスのマッピング（外部API仕様に合わせた変換）
  • コールバックAPI（審査結果の非同期受信）

OIDC4IDA準拠のverified_claims発行​

確認済み情報を標準形式で発行します。

  • IDトークンに含める: claimsパラメータで要求
  • アクセストークンに含める: verified_claims:xxxスコープで個別属性を要求
  • OIDC4IDA標準準拠: 業界標準フォーマットで相互運用性を確保

verified_claimsの内容:

  • verification（確認方法、trust_framework、証拠情報）
  • claims（氏名、生年月日、住所等の確認済み情報）

本人確認必須機能の実現​

特定機能を本人確認済みユーザーのみに制限できます。

  • 高額送金は本人確認必須
  • 証券取引は本人確認必須
  • 一般機能は本人確認不要

仕組み:

未確認ユーザーが送金機能にアクセス → エラー（本人確認必須）
確認済みユーザーが送金機能にアクセス → 許可

申込み状況の追跡​

ユーザーの申込み状況をリアルタイムで管理できます。

  • ステータス管理（requested、applying、applied、examination_processing、approved、rejected等）
  • 申込み一覧取得
  • 申込み詳細取得
  • 申込みキャンセル

導入時に決めること​

1. 身元確認の実施方法​

選択肢説明向いているケース
idp-server経由で申込みアプリ → idp-server → eKYCサービスの全フロー管理新規構築、統合管理したい
eKYC結果のみ登録別システムのeKYC結果をidp-serverに登録既存eKYCシステムあり

idp-serverでの設定:

  • 申込みフローの場合: テンプレートで申込みプロセスを定義
  • 結果登録の場合: 登録用APIの設定

2. 申込みプロセスの設計​

外部eKYCサービスのAPI仕様に合わせて、申込みの流れを定義します。

決めること選択肢の例
プロセスの数1ステップ（申込みのみ）、複数ステップ（申込み → 書類提出 → 完了）
プロセスの順序自由、順序固定（依存関係あり）
リトライ可否再実行可能、1回のみ

典型的なプロセス例:

1. apply（基本情報入力）
2. request-ekyc（書類撮影・提出）
3. complete-ekyc（完了確認）
4. callback-examination（審査中通知、外部からのコールバック）
5. callback-result（審査結果通知、外部からのコールバック）

idp-serverでの設定:

  • テンプレートでプロセスを定義
  • プロセス依存関係（required_processes）を設定
  • 各プロセスのリトライ可否（allow_retry）を設定

3. 外部eKYCサービスとの連携​

決めること選択肢の例
連携タイミング各プロセスで都度連携、最後にまとめて連携
データ送信範囲全データ送信、必要な項目のみ
認証方式OAuth 2.0、HMAC認証、Basic認証

idp-serverでの設定:

  • 各プロセスのexecutionで外部APIエンドポイントを設定
  • リクエスト/レスポンスのマッピングルールを定義
  • 認証情報（OAuth、HMAC等）を設定

4. ステータス遷移の条件​

決めること選択肢の例
承認条件外部サービスのレスポンスで判定、特定フィールドの値で判定
否認条件外部サービスのレスポンスで判定
キャンセル条件ユーザー操作のみ、一定期間放置で自動キャンセル

idp-serverでの設定:

  • 各プロセスのtransitionで遷移条件を定義
  • 条件式（JSONPath、比較演算子）を設定

5. verified_claimsへの変換​

外部eKYCサービスから返却されたデータを、OIDC4IDA標準のverified_claims形式に変換します。

決めること選択肢の例
保存する情報氏名・生年月日・住所全て、最小限のみ（氏名・生年月日）
trust_frameworkjp_aml、eidas、独自の値
evidence情報保存する、保存しない

idp-serverでの設定:

  • resultセクションでverified_claims_mapping_rulesを定義
  • 外部サービスのレスポンスからverified_claims形式へのマッピング

6. 確認済み情報の活用​

使い方実現方法
IDトークンに含めるclaimsパラメータで要求
アクセストークンに含めるverified_claims:xxxスコープで要求
特定機能を本人確認必須にするrequired_identity_verification_scopesで制御
後続の申込みで活用するbody_mapping_rulesで $.user.verified_claims を参照

idp-serverでの設定:

  • テナント設定でverified_claims出力を有効化
  • required_identity_verification_scopesを設定

身元確認結果を活用した申込み​

承認済みのverified_claimsを、後続の申込みで自動的に外部サービスに送信できます。

1回目の身元確認で取得した情報（氏名、生年月日、外部申込み番号など）を、2回目以降の申込みで再利用できるため、ユーザーの入力負担を軽減しつつ、外部サービス側でデータの紐づけが可能になります。

典型的な流れ:

1. 初回の身元確認（authentication-assurance）
   → 外部サービスが申込み番号を発行
   → verified_claimsに氏名・生年月日・申込み番号を保存

2. 継続的身元確認（ongoing-verification）
   → 前回の申込み番号をverified_claimsから自動取得
   → 外部サービスに previous_application_id として送信
   → 外部サービスで前回の審査結果と紐づけた処理が可能

verified_claimsの更新ルール: 新しい身元確認が承認されると、同じキーの値は上書きされます。異なるキーの値はそのまま保持されます。詳細は身元確認申込みガイドの「verified_claimsのライフサイクル」を参照してください。

まとめ​

身元確認/eKYCを導入する際の重要なポイント:

必ず決めること​

  1. 実施方法: idp-server経由で申込み、または結果のみ登録
  2. 申込みプロセス設計: ステップ数、順序、リトライ可否
  3. 外部サービス連携: 連携タイミング、データ範囲、認証方式
  4. ステータス遷移条件: 承認・否認・キャンセルの判定ロジック
  5. verified_claims設計: 保存する情報、trust_framework、evidence
  6. 活用方法: IDトークン/アクセストークン出力、機能制限

idp-serverが提供すること​

  • 申込みフロー管理（複数プロセス、依存関係、リトライ制御）
  • 外部eKYCサービス連携（HTTP API、OAuth/HMAC/Basic認証）
  • テンプレート駆動設計（JSON設定で柔軟に変更可能）
  • ステータス管理（requested → applying → applied → examination_processing → approved/rejected）
  • OIDC4IDA準拠のverified_claims発行
  • 本人確認必須スコープの制御（required_identity_verification_scopes）
  • リクエスト/レスポンスのマッピング（外部API仕様に合わせた変換）

自分で実装すること​

  • 申込み画面（UI）
  • 書類撮影画面（UI）
  • 申込み状況確認画面（UI）
  • 外部eKYCサービスとの契約・API仕様の把握
  • リソースサーバー側のverified_claimsチェック

セキュリティの注意点​

  • 本人確認書類画像はidp-serverに保存せず、外部サービス側のみ保存推奨
  • 最小限の情報のみverified_claimsに保存（必要な属性のみ）
  • 審査結果の受信は認証必須（不正なコールバック防止）
  • verified_claimsの有効期限を設定（定期的な更新を促す）

テンプレートで試す​

ローカル環境ですぐに試せるテンプレートが用意されています。

cd config/templates/use-cases/ekyc
./setup.sh

セットアップ後の動作確認:

ガイド内容
VERIFY.md基本動作確認（認証フロー → eKYC申請 → verified_claims 取得）
VERIFY-CONFIG-CHANGES.md設定変更の実験（mock↔http_request切替、リトライ、エラー処理等）
VERIFY-CONFIG-CHANGES-ADVANCED.mdマッピング関数リファレンス（全20関数の設定例・テスト手順）

詳細: config/templates/use-cases/ekyc/

関連ドキュメント​

最終更新: 2026-01-27