# デジタル認証アプリ 同意取得API

<br>

## **概要**
    
デジタル認証アプリ同意取得APIは、利用者の基本4情報（氏名・住所・生年月日・性別）の提供を受けるために、予め利用者から同意を取得するAPIです。
利用者からの同意は、本人の意思に基づくものであることを確実に示すため、署名用電子証明書を用います。署名用電子証明書を用いた同意は、サービスプロバイダ事業者とプラットフォーム事業者を経由したうえで、J-LISに送信されます。
各事業者及びJ-LISは、それぞれ同意情報に関するデータベース等を構築し、保存・管理を行います。

## **処理の流れ**
    
<Steps>
    <Step title="同意取得の要求（サービスプロバイダ事業者）">
        利用者の基本4情報（氏名・住所・生年月日・性別）提供に対する同意情報を取得し、リダイレクト先URLと併せてAPIに送信します。
    </Step>
    <Step title="署名トランザクションの開始（プラットフォーム事業者）">
        受信した同意情報に基づき同意申請書を生成し、その内容から署名対象データを作成します。署名対象データを同意申請書に追加し、署名トランザクションを開始します。正常に開始された場合、サービスプロバイダ事業者にデジタル認証アプリ用の同意URLを返却します。
    </Step>
    <Step title="デジタル認証アプリの起動（サービスプロバイダ事業者）">
        受信した同意URLにアクセスすると、利用者のスマートフォンでデジタル認証アプリが起動します。PCまたはタブレットを利用する場合は、認証用のQRコードがブラウザまたはアプリ画面に表示されますので、利用者はスマートフォンでQRコードを読み取り、表示された6桁のパスコードを入力して認証を行い、デジタル認証アプリを起動します。
    </Step>
    <Step title="署名値の生成（サービスプロバイダ事業者）">
        デジタル認証アプリ起動後、利用者は画面の案内に従って操作を行い、同意申請書に基づいて署名値を生成します。署名完了後、リダイレクトにより署名結果パラメータをAPIへ送信します。
    </Step>
    <Step title="CSRF対策検証（プラットフォーム事業者）">
        リダイレクトで受信したデータをもとに、CSRF攻撃の有無を検証します。攻撃が検知された場合は、認証処理を中断しエラーを返却します。
    </Step>
    <Step title="署名トランザクション結果の取得（プラットフォーム事業者）">
        検証が正常に完了した場合、デジタル認証アプリで生成された署名結果を取得します。取得した内容に異常がある場合はエラーを返却し、処理を中断します。
    </Step>
    <Step title="署名値・署名用電子証明書の追加（プラットフォーム事業者）">
        取得した署名結果から、署名値、署名用電子証明書を同意申請書に追加します。
    </Step>
    <Step title="同意申請の要求（プラットフォーム事業者）">
        署名値および署名用電子証明書を追加した同意申請書を使用し、J-LISに同意申請を送信します。
    </Step>
    <Step title="署名トランザクションIDの返却（プラットフォーム事業者）">
        同意申請が正常に完了した場合、署名トランザクションIDをリダイレクトで返却し、署名完了画面へ遷移します。
    </Step>
    <Step title="同意申請結果の取得（サービスプロバイダ事業者）">
        取得した署名トランザクションIDを各APIに送信することで、利用者識別用のID、同意申請結果が返却されます。
    </Step>
</Steps>

## **シーケンス図**
    
```mermaid
%%{init:{'theme':'natural'}}%%
sequenceDiagram
    participant 利用者
    participant デジタル認証アプリ
    participant サービスプロバイダ事業者
    participant プラットフォーム事業者
    participant デジタル庁サーバ
    participant J-LIS

    利用者->>サービスプロバイダ事業者: [01] 「はじめる」押下
    サービスプロバイダ事業者->>プラットフォーム事業者: [02] 同意取得の要求
    プラットフォーム事業者->>プラットフォーム事業者: [03] 同意情報XMLの署名対象ハッシュ値生成
    プラットフォーム事業者->>デジタル庁サーバ: [04] トークンリクエスト（client_credentials）
    デジタル庁サーバ-->>プラットフォーム事業者: [05] トークンレスポンス（client_credentials）
    プラットフォーム事業者->>デジタル庁サーバ: [06] 署名トランザクション開始リクエスト
    デジタル庁サーバ-->>プラットフォーム事業者: [07] 署名トランザクション開始レスポンス
    プラットフォーム事業者-->>サービスプロバイダ事業者: 同意取得用URLの返却

    alt スマートフォン（同一端末）
        サービスプロバイダ事業者->>デジタル認証アプリ: [08] 認可リクエスト [09] リダイレクト
        デジタル認証アプリ->>利用者: デジタル認証アプリ起動
    else PC・タブレット（別端末）
        サービスプロバイダ事業者->>デジタル認証アプリ: [08] 認可リクエスト [09] リダイレクト（QRコード表示）
        デジタル認証アプリ->>利用者: デジタル認証アプリ起動<br>QRコードの読み取り・パスコード認証
    end
    利用者->>利用者: デジタル認証アプリの操作
    利用者->>デジタル認証アプリ: 署名用電子証明書の読み取り<br>暗証番号の入力

    デジタル認証アプリ->>デジタル認証アプリ: [10] 利用者が同意情報に署名
    デジタル認証アプリ->>デジタル庁サーバ: 署名完了
    デジタル庁サーバ->>プラットフォーム事業者: [11] 認可レスポンス [12] リダイレクト

    プラットフォーム事業者->>デジタル庁サーバ: [13] トークンリクエスト
    デジタル庁サーバ-->>プラットフォーム事業者: [14] トークンレスポンス
    プラットフォーム事業者->>デジタル庁サーバ: [16] 署名トランザクション結果取得リクエスト
    デジタル庁サーバ-->>プラットフォーム事業者: [17] 署名トランザクション結果取得レスポンス
    プラットフォーム事業者->>デジタル庁サーバ: [18] UserInfoリクエスト
    デジタル庁サーバ-->>プラットフォーム事業者: [19] UserInfoレスポンス
    プラットフォーム事業者->>プラットフォーム事業者: 同意申請書の作成
    プラットフォーム事業者->>J-LIS: 同意の申請
    J-LIS->>プラットフォーム事業者: 同意結果の返却
    プラットフォーム事業者->プラットフォーム事業者: 同意結果の保存

    プラットフォーム事業者->>サービスプロバイダ事業者: [20] レスポンス（リダイレクトで署名トランザクションIDを返却）
    サービスプロバイダ事業者->>プラットフォーム事業者: 同意申請結果の取得要求
    プラットフォーム事業者-->>サービスプロバイダ事業者: 同意申請結果の返却
```
<br>