# マイナアプリ 認証API

<br>

## **概要**

認証APIは、インターネット等でログインする際に「ログインした者が利用者本人であること」を確かめるためのAPIです。
マイナンバーカードのICチップから利用者証明用電子証明書を読み取り、利用者によって作成された乱数を秘密鍵を使用して暗号化することで利用者の真正性を検証するための電子署名を生成します。
これにより、マイページ等のログインの際に、ログインしてきた者が利用者本人であることを確認できます。また、ID・パスワードによる認証よりもセキュリティの高いログイン認証が可能となります。
券面事項入力補助APを用いた基本4情報連携機能も利用可能です。

:::caution[]
券面事項入力補助APによる基本4情報連携を利用される場合は、別途料金がかかります。
:::
   
## **アクセスコントロール**

<AccordionGroup>
    <Accordion title="マイナンバーカード">
        利用者証明用電子証明書の暗証番号（4桁の数字） 
:::caution[]
3回連続で利用者証明用電子証明書の暗証番号を間違えた場合には、マイナンバーカードにロックがかかってしまいますのでご注意ください。
:::
    </Accordion>
    <Accordion title="スマートフォンのマイナンバーカード">
        利用者証明用電子証明書の暗証番号（4桁の数字） 
:::caution[]
3回連続で利用者証明用電子証明書の暗証番号を間違えた場合には、マイナンバーカードにロックがかかってしまいますのでご注意ください。
:::
    </Accordion>
 </AccordionGroup>

## **処理の流れ**


<Tabs>
  <Tab title="対面">
<Steps>
    <Step title="認証の要求（サービスプロバイダ事業者）">
        署名対象となる乱数からハッシュ値を生成し、Base64形式にエンコードします。生成した署名対象データ、リダイレクト先URL、券面事項入力補助APより取得する基本4情報の項目をAPIに送信します。
    </Step>
    <Step title="マイナアプリの起動（サービスプロバイダ事業者）">
        受信した認証用URLにアクセスすることで、利用者のスマートフォンでマイナアプリが起動します。PCまたはタブレットの場合は、認証用のQRコードがブラウザやアプリ画面に表示されますので、利用者はマイナアプリの「二次元コードを読み取る」をタップすることでカメラを起動し、表示されたQRコードを読み取ることで、マイナアプリに表示された6桁のパスコードをPCまたはタブレットの画面で入力します。
    </Step>
    <Step title="利用者の認証・認可（サービスプロバイダ事業者）">
        マイナアプリ起動後、利用者は画面の案内に従って操作を行い、ログインのための認証を行います。認証完了後、リダイレクトによりパラメータをAPIへ送信します。また、デジタル庁サーバとJ-LIS間による利用者証明用電子証明書の有効性確認も行われます。
        <AccordionGroup>
            <Accordion title="マイナンバーカードを読み取る">
                <Steps>
                    <Step>「マイナンバーカードを使って認証します」画面の「ほかの方法を選ぶ」を選択します。</Step>
                    <Step>「実物のマイナンバーカード」を選択します。</Step>
                    <Step>PCまたはタブレットの場合のみ、マイナアプリ画面に6桁のパスコードが表示されますので、PCまたはタブレットに表示されているパスコード入力欄に入力します。</Step>
                    <Step>署名対象の内容が画面に表示されるので、内容を確認後、「確認して次へ」をタップします。</Step>
                    <Step>4桁の利用者証明用電子証明書のパスワードを入力し、「次へ」をタップします。基本4情報も取得する場合は、続けて4桁の券面事項入力補助のパスワードを入力します。</Step>
                    <Step>「読み取り開始」をタップし、NFC機能でマイナンバーカードを読み取ります。</Step>
                    <Step>ご利用サービスへマイナンバーカードから読み取った認証情報の提供を求められますので、「提供」をタップすることで認証が完了します。</Step>
                </Steps>
            </Accordion>
            <Accordion title="iPhoneのマイナンバーカードを読み取る">
                <Steps>
                    <Step>「マイナンバーカードを使って署名します」画面の「Face IDで認証」を選択します。</Step>
                    <Step>PCまたはタブレットの場合のみ、マイナアプリ画面に6桁のパスコードが表示されますので、PCまたはタブレットに表示されているパスコード入力欄に入力します。</Step>
                    <Step>マイナアプリ画面の「Face IDで認証」をタップし、Face IDによる認証を行います。。基本4情報も取得する場合は、続けてAppleウォレットが起動し、マイナアプリに対する基本4情報共有を確認されるので、電源ボタンをダブルタップすることで承認します。</Step>
                    <Step>ご利用サービスへマイナンバーカードから読み取った認証情報の提供を求められますので、「提供」をタップすることで認証が完了します。</Step>
                </Steps>
            </Accordion>
            <Accordion title="Androidスマホ用電子証明書を読み取る">
                <Steps>
                    <Step>「マイナンバーカードを使って署名します」画面の「端末のロックで認証」を選択します。</Step>
                    <Step>PCまたはタブレットの場合のみ、マイナアプリ画面に6桁のパスコードが表示されますので、PCまたはタブレットに表示されているパスコード入力欄に入力します。</Step>
                    <Step>マイナアプリ画面の「端末のロックで認証」をタップし、Android端末のロックによる認証を行います。</Step>
                    <Step>ご利用サービスへマイナンバーカードから読み取った認証情報の提供を求められますので、「提供」をタップすることで認証が完了します。</Step>
                    
                </Steps>
:::caution[]
現時点でAndroidスマホ用電子証明書では、基本4情報の取得に対して非対応のため、基本4情報の取得をご希望の場合は、マイナンバーカードをご利用ください。
:::
            </Accordion>
        </AccordionGroup>
    </Step>
    <Step title="CSRF対策検証（プラットフォーム事業者）">
        リダイレクトで受信したデータをもとに、CSRF攻撃の有無を検証します。攻撃が検知された場合は、認証処理を中断しエラーを返却します。
    </Step>
    <Step title="認証結果の取得（プラットフォーム事業者）">
        検証が正常に完了した場合、マイナアプリで生成された認証結果を取得します。取得した内容に異常がある場合は、エラーを返却し処理を中断します。
    </Step>
    <Step title="認証IDの返却（プラットフォーム事業者）">
        認証IDをリダイレクトで返却し、ログイン完了画面へ遷移します。
    </Step>
    <Step title="基本4情報の取得（サービスプロバイダ事業者）">
        取得した認証IDをAPIに送信することで、利用者識別用のID、券面事項入力補助APの基本4情報が返却されます。
    </Step>
</Steps>
  </Tab>
  <Tab title="非対面">
<Steps>
    <Step title="認証の要求（サービスプロバイダ事業者）">
        署名対象となる乱数からハッシュ値を生成し、Base64形式にエンコードします。生成した署名対象データ、リダイレクト先URL、券面事項入力補助APより取得する基本4情報の項目をAPIに送信します。
    </Step>
    <Step title="マイナアプリの起動（サービスプロバイダ事業者）">
        受信した認証用URLにアクセスすることで、利用者のスマートフォンでマイナアプリが起動します。PCまたはタブレットの場合は、認証用のQRコードがブラウザやアプリ画面に表示されますので、利用者はマイナアプリの「二次元コードを読み取る」をタップすることでカメラを起動し、表示されたQRコードを読み取ることで、マイナアプリに表示された6桁のパスコードをPCまたはタブレットの画面で入力します。
    </Step>
    <Step title="利用者の認証・認可（サービスプロバイダ事業者）">
        マイナアプリ起動後、利用者は画面の案内に従って操作を行い、ログインのための認証を行います。認証完了後、リダイレクトによりパラメータをAPIへ送信します。また、デジタル庁サーバとJ-LIS間による利用者証明用電子証明書の有効性確認も行われます。
        <AccordionGroup>
            <Accordion title="マイナンバーカードを読み取る">
                <Steps>
                    <Step>「マイナンバーカードを使って認証します」画面の「ほかの方法を選ぶ」を選択します。</Step>
                    <Step>「実物のマイナンバーカード」を選択します。</Step>
                    <Step>PCまたはタブレットの場合のみ、マイナアプリ画面に6桁のパスコードが表示されますので、PCまたはタブレットに表示されているパスコード入力欄に入力します。</Step>
                    <Step>署名対象の内容が画面に表示されるので、内容を確認後、「確認して次へ」をタップします。</Step>
                    <Step>4桁の利用者証明用電子証明書のパスワードを入力し、「次へ」をタップします。基本4情報も取得する場合は、続けて4桁の券面事項入力補助のパスワードを入力します。</Step>
                    <Step>「読み取り開始」をタップし、NFC機能でマイナンバーカードを読み取ります。</Step>
                    <Step>ご利用サービスへマイナンバーカードから読み取った認証情報の提供を求められますので、「提供」をタップすることで認証が完了します。</Step>
                </Steps>
            </Accordion>
            <Accordion title="iPhoneのマイナンバーカードを読み取る">
                <Steps>
                    <Step>「マイナンバーカードを使って署名します」画面の「Face IDで認証」を選択します。</Step>
                    <Step>PCまたはタブレットの場合のみ、マイナアプリ画面に6桁のパスコードが表示されますので、PCまたはタブレットに表示されているパスコード入力欄に入力します。</Step>
                    <Step>マイナアプリ画面の「Face IDで認証」をタップし、Face IDによる認証を行います。。基本4情報も取得する場合は、続けてAppleウォレットが起動し、マイナアプリに対する基本4情報共有を確認されるので、電源ボタンをダブルタップすることで承認します。</Step>
                    <Step>ご利用サービスへマイナンバーカードから読み取った認証情報の提供を求められますので、「提供」をタップすることで認証が完了します。</Step>
                </Steps>
            </Accordion>
            <Accordion title="Androidスマホ用電子証明書を読み取る">
                <Steps>
                    <Step>「マイナンバーカードを使って署名します」画面の「端末のロックで認証」を選択します。</Step>
                    <Step>PCまたはタブレットの場合のみ、マイナアプリ画面に6桁のパスコードが表示されますので、PCまたはタブレットに表示されているパスコード入力欄に入力します。</Step>
                    <Step>マイナアプリ画面の「端末のロックで認証」をタップし、Android端末のロックによる認証を行います。</Step>
                    <Step>ご利用サービスへマイナンバーカードから読み取った認証情報の提供を求められますので、「提供」をタップすることで認証が完了します。</Step>
                    
                </Steps>
:::caution[]
現時点でAndroidスマホ用電子証明書では、基本4情報の取得に対して非対応のため、基本4情報の取得をご希望の場合は、マイナンバーカードをご利用ください。
:::
            </Accordion>
        </AccordionGroup>
    </Step>
    <Step title="CSRF対策検証（プラットフォーム事業者）">
        リダイレクトで受信したデータをもとに、CSRF攻撃の有無を検証します。攻撃が検知された場合は、認証処理を中断しエラーを返却します。
    </Step>
    <Step title="認証結果の取得（プラットフォーム事業者）">
        検証が正常に完了した場合、マイナアプリで生成された認証結果を取得します。取得した内容に異常がある場合は、エラーを返却し処理を中断します。
    </Step>
    <Step title="認証IDの返却（プラットフォーム事業者）">
        認証IDをリダイレクトで返却し、ログイン完了画面へ遷移します。
    </Step>
    <Step title="基本4情報の取得（サービスプロバイダ事業者）">
        取得した認証IDをAPIに送信することで、利用者識別用のID、券面事項入力補助APの基本4情報が返却されます。
    </Step>
</Steps>
  </Tab>
</Tabs>

## **シーケンス図**


<Tabs>
  <Tab title="対面">

```mermaid
%%{init:{'theme':'natural'}}%%
sequenceDiagram
autonumber
    participant 利用者
    participant マイナアプリ
    participant サービスプロバイダ事業者
    participant プラットフォーム事業者
    participant デジタル庁サーバ
    participant J-LIS

    利用者->>サービスプロバイダ事業者: [01] 「アプリを使って認証」押下
    Note Over サービスプロバイダ事業者,プラットフォーム事業者:1.認証の要求
    サービスプロバイダ事業者->>プラットフォーム事業者: [02] 認証の要求
    プラットフォーム事業者->>プラットフォーム事業者: 認証用URL生成
    プラットフォーム事業者-->>サービスプロバイダ事業者: 認証用URLの返却

    Note Over 利用者,サービスプロバイダ事業者:2.マイナ認証アプリの起動
    alt スマートフォン（同一端末）
        サービスプロバイダ事業者->>マイナアプリ: [03] 認可リクエスト [04] リダイレクト
        マイナアプリ->>利用者: マイナアプリ起動
    else PC・タブレット（別端末）
        サービスプロバイダ事業者->>マイナアプリ: [03] 認可リクエスト [04] リダイレクト（QRコード表示）
        マイナアプリ->>利用者: マイナアプリ起動<br>QRコードの読み取り・パスコード認証
    end
    Note Over 利用者,デジタル庁サーバ:3.利用者の認証・認可
    利用者->>利用者: マイナアプリの操作
    利用者->>マイナアプリ: 利用者証明用電子証明書の読み取り<br>暗証番号の入力
    マイナアプリ->>デジタル庁サーバ: [05] 利用者の認証（有効性確認）
    デジタル庁サーバ->>J-LIS: 利用者証明用電子証明書の有効性確認
    J-LIS->J-LIS: 有効性確認
    J-LIS->>デジタル庁サーバ: 有効性確認結果の返却
    デジタル庁サーバ->>マイナアプリ: [05] 利用者の認可
    マイナアプリ->>デジタル庁サーバ: 認証完了
    Note Over プラットフォーム事業者,デジタル庁サーバ:4.CSRF対策検証
    デジタル庁サーバ->>プラットフォーム事業者: [06] 認可レスポンス [07] リダイレクト
    Note Over プラットフォーム事業者,デジタル庁サーバ:5.認証結果の取得
    プラットフォーム事業者->>デジタル庁サーバ: [08] トークンリクエスト
    デジタル庁サーバ-->>プラットフォーム事業者: [09] トークンレスポンス
    プラットフォーム事業者->>デジタル庁サーバ: [10] UserInfoリクエスト
    デジタル庁サーバ-->>プラットフォーム事業者: [11] UserInfoレスポンス
    Note Over サービスプロバイダ事業者,プラットフォーム事業者:6.認証IDの返却
    プラットフォーム事業者->>サービスプロバイダ事業者: [12] レスポンス（リダイレクトで画面遷移）
    サービスプロバイダ事業者->>プラットフォーム事業者: 認証結果の取得
    Note Over サービスプロバイダ事業者,プラットフォーム事業者:7.基本4情報の取得
    プラットフォーム事業者-->>サービスプロバイダ事業者: 基本4情報・ユーザ情報の返却
```
  </Tab>
  <Tab title="非対面">

```mermaid
%%{init:{'theme':'natural'}}%%
sequenceDiagram
autonumber
    participant 利用者
    participant マイナアプリ
    participant サービスプロバイダ事業者
    participant プラットフォーム事業者
    participant デジタル庁サーバ
    participant J-LIS

    利用者->>サービスプロバイダ事業者: [01] 「アプリを使って認証」押下
    Note Over サービスプロバイダ事業者,プラットフォーム事業者:1.認証の要求
    サービスプロバイダ事業者->>プラットフォーム事業者: [02] 認証の要求
    プラットフォーム事業者->>プラットフォーム事業者: 認証用URL生成
    プラットフォーム事業者-->>サービスプロバイダ事業者: 認証用URLの返却

    Note Over 利用者,サービスプロバイダ事業者:2.マイナ認証アプリの起動
    alt スマートフォン（同一端末）
        サービスプロバイダ事業者->>マイナアプリ: [03] 認可リクエスト [04] リダイレクト
        マイナアプリ->>利用者: マイナアプリ起動
    else PC・タブレット（別端末）
        サービスプロバイダ事業者->>マイナアプリ: [03] 認可リクエスト [04] リダイレクト（QRコード表示）
        マイナアプリ->>利用者: マイナアプリ起動<br>QRコードの読み取り・パスコード認証
    end
    Note Over 利用者,デジタル庁サーバ:3.利用者の認証・認可
    利用者->>利用者: マイナアプリの操作
    利用者->>マイナアプリ: 利用者証明用電子証明書の読み取り<br>暗証番号の入力
    マイナアプリ->>デジタル庁サーバ: [05] 利用者の認証（有効性確認）
    デジタル庁サーバ->>J-LIS: 利用者証明用電子証明書の有効性確認
    J-LIS->J-LIS: 有効性確認
    J-LIS->>デジタル庁サーバ: 有効性確認結果の返却
    デジタル庁サーバ->>マイナアプリ: [05] 利用者の認可
    マイナアプリ->>デジタル庁サーバ: 認証完了
    Note Over プラットフォーム事業者,デジタル庁サーバ:4.CSRF対策検証
    デジタル庁サーバ->>プラットフォーム事業者: [06] 認可レスポンス [07] リダイレクト
    Note Over プラットフォーム事業者,デジタル庁サーバ:5.認証結果の取得
    プラットフォーム事業者->>デジタル庁サーバ: [08] トークンリクエスト
    デジタル庁サーバ-->>プラットフォーム事業者: [09] トークンレスポンス
    プラットフォーム事業者->>デジタル庁サーバ: [10] UserInfoリクエスト
    デジタル庁サーバ-->>プラットフォーム事業者: [11] UserInfoレスポンス
    Note Over サービスプロバイダ事業者,プラットフォーム事業者:6.認証IDの返却
    プラットフォーム事業者->>サービスプロバイダ事業者: [12] レスポンス（リダイレクトで画面遷移）
    サービスプロバイダ事業者->>プラットフォーム事業者: 認証結果の取得
    Note Over サービスプロバイダ事業者,プラットフォーム事業者:7.基本4情報の取得
    プラットフォーム事業者-->>サービスプロバイダ事業者: 基本4情報・ユーザ情報の返却
```
  </Tab>
</Tabs>



<br>