デジタル認証アプリ
行政機関等・民間事業者向け実装ガイドライン
公開日
更新日
概要
「デジタル認証アプリ」は、マイナンバーカードを使った認証や署名を、安全に・簡単にするための、デジタル庁が提供するアプリです。行政機関や民間事業者は、デジタル認証アプリと連携するAPIを活用することで、マイナンバーカードを使った本人確認・認証や電子申請書類への署名機能を簡単に組み込むことができます。
サービスの概要については、以下の情報をご確認ください。
認証・署名のプロセスはOAuth 2.0 認可コードフロー、およびOpenID Connect 認可コードフローに基づきます。
署名プロセスのみ、認可コードフローにて署名処理を実施するためにクライアントクレデンシャルズフローが扱われます。
必要に応じて、トークンリフレッシュフローにてトークンのリフレッシュを行うことが可能です。
※「リソースオーナーパスワードクレデンシャルズフロー」ならびに「インプリシットフロー」は各プロセスにて採用しておりません。
対応OS
iOS及びAndroidのネイティブアプリとして提供します。デジタル認証アプリの推奨バージョンは以下の通りです。
プラットフォーム | バージョン |
---|---|
iOS | 16.0以降 |
Android | 11以降 |
用語定義
本ガイドラインにおいて扱われる用語について、以下のとおり定義します。
用語名 | 説明 |
---|---|
デジタル認証アプリ | マイナンバーカードの証明書を読込み、デジタル認証アプリサーバと通信してRPの認証、署名を行うクライアントソフトウェア。 |
デジタル認証アプリサーバ | デジタル認証アプリと共にRPの認証、署名を行うバックエンドサーバ。 |
デジタル認証アプリサービス | デジタル認証アプリのサービス全体を示す。 |
デジタル認証アプリサービスAPI | デジタル認証アプリサービスが行政機関等及び民間事業者向けに開発するAPI。 |
利用者識別子 | デジタル認証アプリサーバがRPへ発行する識別子(PPID)。RP内で利用者を特定することができる。RPごとにユニークな識別子を発行する。 |
同一端末 | デジタル認証アプリがインストールされている端末内でRPのアプリケーション、もしくはRPのWebサービスが実行されている状態。 |
別端末 | デジタル認証アプリがインストールされている端末とは別の端末でRPのアプリケーション、もしくはRPのWebサービスが実行されている状態。 |
クライアントID | RPを特定するID。 |
署名対象データ名 | 署名するデータの名称。 RP側で自由に設定可能。 |
署名対象識別コード | 署名するデータを識別するために、RPが発行するコード。 RP側のサイトで表示された署名対象識別コードと、デジタル認証アプリに表示された署名対象識別コードの一致を確認することで、利用者は、RP側で発行された電子署名対象に対して署名することを確認する。 |
属性情報 | 利用者個人に関わる基本的な情報群を示す。 |
デジタル認証アプリサービスシステムメンテナンス(バックエンド) | デジタル認証アプリサーバのメンテナンスのためにサービスを停止している状態。 |
デジタル認証アプリサービスシステムメンテナンス(JPKI) | J-LISのJPKIシステムがメンテナンスのためにサービスを停止している状態。 |
JPKI(公的個人認証サービス) | マイナンバーカードのICチップに搭載された電子証明書を利用(マイナンバーは利用しません)して、オンラインで利用者本人の認証や契約書等の文書が改ざんされていないことの確認を公的に行うための安全・確実な本人確認を行う。 |
利用者証明用電子証明書 | インターネットのウェブサイト等にログインする際に利用する(例:マイナポータルへのログイン、コンビニでの住民票の写し等の交付)。「ログインした者が、利用者本人であること」を証明することができる。 |
署名用電子証明書 | インターネット等で電子文書を作成・送信する際に利用する(例:e-Tax等の電子申請)。「作成・送信した電子文書が、利用者が作成した真正なものであり、利用者が送信したものであること」を証明することができる。 |
基本4情報 | 氏名・住所・生年月日・性別を示す。 |
券面事項入力補助AP | マイナンバーカード内に設定されているアプリケーションの一つ。デジタル認証アプリで券面事項入力補助APのPINを入力することで、券面事項入力補助APから基本4情報を取得できる。 |
RP | 「Relying Party」の略称。 OpenID Connect プロトコルにおける用語定義「Relying Party」に基づく。 行政機関等及び民間事業者が提供するサービスを指す。 |
認可コード | OAuth 2.0 認可フレームワークにおける用語定義「Authorization Code」に基づく。 |
IDトークン | OpenID Connect プロトコルにおける用語定義「ID Token」に基づく。 |
アクセストークン | OAuth 2.0 認可フレームワークにおける用語定義「Access Tokens」に基づく。 |
リフレッシュトークン | OAuth 2.0 認可フレームワークにおける用語定義「Refresh Tokens」に基づく。 |
PPID | 「Pairwise Pseudonymous Identifier」の略称。 |
JWT | コンパクトでURLセーフなクレームの表現手段。 |
JWK | 暗号鍵を表すJSONオブジェクト。 |
クライアントクレデンシャル | 下記参考リンクにおける「2.3. Client Authentication」内の「client credentials」に基づく。 |
OpenID Providerメタデータ | OpenIDプロパイダを構成するメタデータ。 |
エンドポイント
以下に、デジタル認証アプリサービスがサポートするエンドポイントの概要および使用目的を示します。
エンドポイント名 | 使用目的 |
---|---|
認可エンドポイント | OpenID Connect に準拠した、RPアプリを認可するための認可コードを取得するエンドポイント。 |
トークンエンドポイント | OpenID Connect に準拠した、トークンを発行するためのエンドポイント。 |
UserInfoエンドポイント | OpenID Connect に準拠した、利用者識別子および利用者の属性情報をRPアプリへ提供するためのエンドポイント。 |
署名トランザクション開始エンドポイント | デジタル認証アプリサービス独自に実装した、RPアプリから署名対象データを受け取るためのエンドポイント。 |
署名トランザクション結果取得エンドポイント | デジタル認証アプリサービス独自に実装した、RPアプリへ署名結果を返却するためのエンドポイント。 |
OpenID Provider Configuration エンドポイント | OpenID Connect に準拠した、RPアプリが各エンドポイントのURIを確認するためのエンドポイント。 |
JWK Set公開エンドポイント | OpenID Connect に準拠した、公開鍵の一覧を確認するためのエンドポイント。 |
APIリファレンス
APIのエンドポイントやリクエストヘッダ、クエリパラメータ、リクエストボディ、返却されるレスポンスヘッダ・レスポンスボディ・ステータス等はAPIリファレンスをご確認ください。
HTTPステータスコード
APIリクエストをすると、HTTPステータスコードが返却されます。
HTTPステータスコードの説明は、特に断りがない限り HTTP status code specification に準拠しています。
参考:HTTP status code specification
APIリクエスト後に返却されるHTTPステータスコードについて、本ガイドラインでは以下の名称でカテゴリを定義し、分類しています。
- 正常ケース
- 異常ケース
- リダイレクトケース
「異常ケース」に分類されるHTTPステータスコードが返却された場合、RPアプリは受け取ったエラーの制御を行ってください。
「リダイレクトケース」に分類されるHTTPステータスコードが返却された場合、RPアプリは受け取ったレスポンスを確認し、クエリパラメータの内容に応じてエラーの制御を行ってください。
詳しくは後述の「リダイレクトケース」をご参照ください。
正常ケース
HTTPステータスコード | 説明 |
---|---|
200 | リクエストが成功した場合に返却されます。 |
異常ケース
エンドポイントごとの異常ケースの詳細な説明は、
補足資料「エンドポイント毎のエラー時返却ステータスとメッセージ」
および別紙のAPIリファレンスを確認してください。
- HTTPステータス:400番台のエラーレスポンスが返却された場合
デジタル認証アプリサービス APIリファレンスに従い、リクエストのクエリパラメータ・リクエストボディ等を設定してください。
HTTPステータスコード | 説明 |
---|---|
400 | リクエストが不正の場合に返却されます。 |
401 | 一例として、アクセストークンによる認証が失敗した場合に返却されます。 |
- HTTPステータス:500番台のエラーレスポンスが返却された場合
必要に応じて、デジタル認証アプリサーバで異常が発生したことが分かるようエラーの制御を行ってください。
HTTPステータスコード | 説明 |
---|---|
500 | デジタル認証アプリサーバ内にエラーが発生した場合に返却されます。 |
503 | デジタル認証アプリサーバがシステムメンテナンス実施中の場合に返却されます。 |
リダイレクトケース
認可エンドポイントにおいて、HTTPステータスコードは必ず「302」で返却されます。
HTTPステータスコード | 説明 |
---|---|
302 | ・ 認可リクエストを正常に処理できた場合 |
アプリへの連携
利用者の認証・署名は、同一端末と別端末のケースに対応できます。
シーケンス図のうち、RPが関連するリクエスト、レスポンス、検証処理等は、RPアプリで実装してください。
デジタル認証アプリとRPアプリ(もしくはWEBサイト)が別端末の場合であっても、RPアプリとのAPI連携で特別な処理は必要なく、フローの差異はありません。
RPアプリをPCで開いている場合、デジタル認証アプリサービス側で、スマートフォンとの連携を行う二次元コードが含まれたWEBページを表示します。利用者は、デジタル認証アプリサービスに表示された二次元コードを、スマートフォンのカメラで読み取ることで、PCとスマートフォンの連携を行います。認証・署名が完了するまでの間、PCとスマートフォンは連携しており、スマートフォン側で認証・署名が完了した後、PC側の画面が、redirect_uriで指定した画面に遷移します。
シーケンス図:認証
利用者が、利用者証明用電子証明書を使って認証するシーケンスです。
APIの概要とAPI利用の流れについては、サービスサイトをご確認ください。
上記シーケンス図にて、RPアプリが関連するリクエストとレスポンスについて、詳しく説明します。
リクエスト・レスポンス | 説明 |
---|---|
[02] 認証開始リクエスト | RPアプリは、ブラウザから認証開始リクエストを受け取り、利用者の認証処理を開始してください。 |
[03] 認可リクエスト | RPアプリは、認可リクエストをデジタル認証アプリサービスへリダイレクトで送信してください。 |
[05] 利用者の認証・認可 | デジタル認証アプリにて、利用者の認証・認可を行うとともに、電子利用者証明の検証と利用者証明用電子証明書の有効性確認を行います。 |
[06] 認可レスポンス | デジタル認証アプリサービスは、利用者の認証・利用者の認可処理を行い、認可レスポンスをRPアプリへリダイレクトで送信します。 |
[08] トークンリクエスト | RPアプリは、トークンリクエストを送信して以下の各種トークンを取得してください。 |
[10] UserInfoリクエスト | 利用者の属性情報は、必要に応じて、UserInfoリクエストを用いて取得できます。 |
[12] レスポンス | フロー完了時にRPコンテンツのログイン済画面へ遷移します。 |
シーケンス図:署名
利用者が、署名用電子証明書を使って、文書に対して電子署名するシーケンスです。
APIの概要とAPI利用の流れについては、サービスサイトをご確認ください。
上記シーケンス図にて、RPアプリが関連するリクエストとレスポンスについて、詳しく説明します。
リクエスト・レスポンス | 説明 |
---|---|
[02] 署名開始リクエスト | RPアプリは、ブラウザから署名開始リクエストを受け取り、利用者の署名処理を開始してください。 |
[03] 署名対象ハッシュ値生成 | RPアプリは、署名対象データをもとに署名対象ハッシュ値をbase64エンコードにて生成してください。 |
[04] トークンリクエスト(client_credentials) | RPアプリは、署名トランザクションを開始する為、アクセストークンを取得してください。 |
[06] 署名トランザクション | RPアプリは、「[05]トークンレスポンス(client_credentials)」で取得したアクセストークンをもとに、 |
[08] 認可リクエスト | RPアプリは、認可リクエストをデジタル認証アプリサービスへリダイレクトで送信してください。 |
[10] 利用者が | デジタル認証アプリにて、利用者が署名対象ハッシュ値に署名します。行政機関向けには、署名値の作成、署名用電子証明書の認証パスの検証、署名用電子証明書の有効期間の検証、署名用電子証明書の有効性確認を行います。民間事業者向けには、署名値の作成、署名用電子証明書の認証パスの検証、署名用電子証明書の有効期間の検証を行います。行政機関向け、民間事業者向けどちらも、署名検証(署名対象データ、署名対象ハッシュ値、署名値の確認)は行いません。署名トランザクション結果受け取り後、署名検証をお願い致します。 |
[11] 認可レスポンス | デジタル認証アプリサービスは、利用者の認証と、RPアプリが利用者の属性情報を利用することの認可を行い、認可レスポンスをRPアプリへリダイレクトで送信します。 |
[13] トークンリクエスト | RPアプリは、トークンリクエストを送信して以下の各種トークンを取得してください。 |
[16] 署名トランザクション | RPアプリは、署名トランザクションの結果を取得し、署名用電子証明書の署名を検証してください。 |
[18] UserInfoリクエスト | 利用者の属性情報は、必要に応じて、UserInfoリクエストを用いて取得できます。 |
[20] レスポンス | フロー完了時にRPコンテンツの署名完了画面へ遷移します。 |
シーケンス図:デジタル認証アプリホーム画面・RPアプリとの接続解除
デジタル認証アプリサービスのホーム画面に関する機能及びRPとの接続解除に関連するシーケンスです。
上記シーケンス図にて、RPアプリが関連するリクエストとレスポンスについて、詳しく説明します。
リクエスト・レスポンス | 説明 |
---|---|
[04] RP一覧画面 RP解除 | 利用者がRPの解除・ログアウト・アカウントの削除を行う際、デジタル認証アプリサービスは、RPアプリに対して back-channel logout リクエストをします。 |
アプリが表示するエラーについて
マイナンバーカードの操作でエラーが発生した際、デジタル認証アプリにてエラー画面を表示します。エラー内容は以下の通りです。
事象 | エラー内容 |
---|---|
カードの読み取りが中断された場合 | もう一度カードを読み取ってください |
マイナンバーカード以外を読み取った場合 | 正しいカードを読み取ってください |
暗証番号が正しくない場合 | 暗証番号が正しくありません |
署名用電子証明書がロックされている場合 | 署名用電子証明書がロックされています |
署名用電子証明書がない場合 | 署名用電子証明書がありません |
署名用電子証明書の有効期限が切れている場合 | 署名用電子証明書の有効期限が切れています |
署名用電子証明書が失効している場合 | 署名用電子証明書が失効しています |
署名用電子証明書が正しくない場合 | 署名用電子証明書が正しくありません |
利用者証明用電子証明書がロックされている場合 | 利用者証明用電子証明書がロックされています |
利用者証明用電子証明書がない場合 | 利用者証明用電子証明書がありません |
利用者証明用電子証明書の有効期限が切れている場合 | 利用者証明用電子証明書の有効期限が切れています |
利用者証明用電子証明書が失効している場合 | 利用者証明用電子証明書が失効しています |
利用者証明用電子証明書が正しくない場合 | 利用者証明用電子証明書が正しくありません |
実装にあたっての必須対応事項
デジタル認証アプリサーバへの接続に関する補足事項
通信プロトコルは、HTTPS(TLS1.2、TLS1.3)です。また、以下のSSLサーバー証明書の検証が可能なルート証明書が必要となります。
証明書 | 内容 |
---|---|
SSLサーバー証明書 | |
ルート証明機関 |
リダイレクトURIの設定
以下の説明を確認のうえ、デジタル認証アプリサービスへの申込時に、各RPアプリへのリダイレクトURIを指定してください。
RPがネイティブアプリの場合
iOSは Universal Link、Androidは App Link を指定してください。
悪意のある他アプリによる乗っ取り攻撃の危険があるため、Custom URL Schema は指定しないでください。
RPがWEBアプリの場合
リダイレクトURIにWEBアプリのURIを指定することで、WEBアプリ上で認可レスポンスを取得できます。
RPがブラウザベースアプリの場合
トークンを安全に取り扱うため、BFFアーキテクチャ(Backend For Frontend)を採用してください。
リダイレクトURIにBFFのURIを指定してください。
IDトークンの検証
認可コードフローのトークンレスポンスには、IDトークンが含まれています。
※署名プロセスにおいてクライアントクレデンシャルズフローが扱われる過程がありますが、クライアントクレデンシャルズフローにおいてはIDトークンは含まれません。
RPアプリは、利用者認証情報を含む改ざん検知用の署名付きトークンであるIDトークンについて、トークンレスポンス取得後に必ず正当性を検証してください。
デジタル認証アプリサービスのJWTの署名アルゴリズムはES256です。
JWTはピリオド(".")区切りのヘッダ部、ペイロード部、シグネチャー部から構成され、各部位はBase64URLエンコードされています。
検証準備
- 取得したIDトークンをBase64URLデコードし、ヘッダ部、ペイロード部、シグネチャー部を(".")で分割します。
- デジタル認証アプリサービスの JWK Set公開エンドポイントを用いて、デジタル認証アプリサービス内の一連の公開鍵情報を取得します。公開鍵は定期的に更新されるため、IDトークン検証の度に取得してください。
JWT ヘッダ部の検証
- IDトークンヘッダ部の kid が検証準備で取得した公開鍵の kid と一致することを検証してください。
- 署名のアルゴリズム である alg と、検証準備で取得した公開鍵のアルゴリズムがともに「ES256」になっていることを検証してください。
署名の検証
RPアプリでご使用の開発言語や、使用されるライブラリ等によって異なります。
検証の概要を以下に示します。
- Base64URLエンコード状態のヘッダ部 + "." + ペイロード部をデータ部として保持 ・・・変数①
- Base64URLデコードしたシグネチャー部を保持 ・・・変数②
- 検証準備で取得した公開鍵を保持 ・・・変数③
- アルゴリズムを ES256 として保持 ・・・変数④
- 変数①~④を使用し、開発言語または使用されるライブラリで署名を検証
- 検証結果の正常・異常を判断
ペイロード部の検証
- IDトークンの発行者を示す Issuer Identifierクレーム(iss)がOpenID Providerメタデータの issuer の値と一致することを検証してください。
- IDトークンのaudienceクレーム(aud)に、RPアプリのクライアントIDが含まれていることを検証してください。
- IDトークンの有効期限を示す expiration timeクレーム(exp)が、検証時の時間より未来であることを検証してください。
- IDトークンの発行日時を示す Issued atクレーム(iat)が、 検証時のUNIXタイムスタンプ値 - 所要時間(秒) の値以上であることを検証してください。
所要時間は、RPアプリで決める必要があります。
nonce 保存からRPアプリがIDトークン受け取るまでの時間が目安です。
指定時間を経過していた場合は必要に応じて、RPアプリ側にて再認証を実施するなど、追加処理の実装を検討してください。 - IDトークンのat_hashクレームについて、以下のとおり検証してください。
- アクセストークンを、IDトークンヘッダ部のalgorithmクレーム(alg)と同じハッシュアルゴリズムを用いてハッシュ化し、ハッシュ化した結果の左半分のビット群をBase64URLにてエンコードしたうえで、IDトークンのat_hashと値が一致することを確認してください。
ヘッダ部 クレーム値の返却例 (ID トークン)
クレーム | 概要 | 例 |
---|---|---|
alg | 署名のアルゴリズム | ES256 |
typ | ヘッダ部の形式 | JWT |
kid | 署名検証に用いる公開鍵のKey ID | ts_Fae_OYkHZ7De4IiwkZrFO-OtW97HO2WwYJFV_G6E |
ペイロード部 クレーム値の返却例 (ID トークン)
クレーム | 概要 | 例 |
---|---|---|
exp | IDトークンの有効期限(UNIXタイム) | 1711074808 |
iat | IDトークンの発行日時期限 (UNIXタイム) | 1711073908 |
auth_time | 利用者が認証された時刻(UNIXタイム) | 1711073898 |
jti | JWT の一意の識別子 | 3b1fd777-3ac8-4b57-82c3-36ccb7a7261f |
iss | JWT の発行者 (issuer) を識別するための識別子 | https://auth-and-sign.go.jp/realms/main/ |
aud | RPアプリのクライアントID | 501b35d6-bb32-462e-b84c-0fd2bb0574d8 |
sub | 認証された利用者の識別子 | 37cf5dd9-d0b2-4370-9028-52d5fa3460dc |
typ | ペイロード部の形式 | ID |
azp | RPアプリのクライアントID | 501b35d6-bb32-462e-b84c-0fd2bb0574d8 |
nonce | RPアプリが指定したnonce | b04b31cee32645ab700dce72860047bd |
session_state | セッション識別子 | b93c05a7-1b42-452f-92fe-810923955f42 |
at_hash | アクセストークンのハッシュ値。 | V2zoAGqSLUR1kxDb7JJmNg |
sid | セッション識別子 | b93c05a7-1b42-452f-92fe-810923955f42 |
検証失敗時
- タイムスタンプの検証で失敗する場合は、有効期限切れや認証時刻が過ぎているため、認証処理を中断し、トークンリフレッシュにてIDトークンの再発行を行ってください。
- その他の検証で失敗する場合は、IDトークンが改ざんされている可能性があるため、認証処理を中断し、エラー処理等を行ってください。
参考
- JWT対応のライブラリを用いる場合は各ライブラリに従って適宜必要な処理を行ってください。
- IDトークンの詳細な検証手順は以下をご確認ください。
OpenID Connect > ID Token Validation
https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation
logout トークンの検証
デジタル認証アプリサービスからRPアプリへback-channel logoutリクエストを送信する際、logout トークンをPOSTパラメータへ含めます。
RPアプリは、logout トークンについて正当性の検証を含めて、利用者とのセッション終了処理を実施してください。
ヘッダ部 クレーム値の返却例 (logout トークン)
クレーム | 概要 | 例 |
---|---|---|
alg | 署名のアルゴリズム | ES256 |
typ | ヘッダ部の形式 | JWT |
kid | 署名検証に用いる公開鍵のKey ID | wuM3-vOGYNT9MyJCTKeyj2zGqaK2DFUP4cJXzky9oKA |
ペイロード部 クレーム値の返却例 (logout トークン)
クレーム | 概要 | 例 |
---|---|---|
iat | JWT が発行された日時(UNIXタイム) | 1711954838 |
jti | JWT の一意の識別子 | ee8c21aa-ab80-4a42-8379-60e424b8820d |
iss | JWT の発行者 (issuer) を識別するための識別子 | https://auth-and-sign.go.jp/realms/auth-and-sign |
aud | RPアプリのクライアントID | d579245d-2673-49e4-a6ab-22a17c2caacb |
sub | 認証された利用者の識別子 | 4d75797d-9546-3792-a9cd-95e644f91072 |
exp | JWT の有効期限 | 1711990838 |
sid | セッションID | 653a7ccb-3646-4c94-ac5e-8c5342f12f32 |
events | JWT がlogoutトークンであることを宣言する値 | {http://schemas.openid.net/event/backchannel-logout : {}} |
IDトークン署名検証用公開鍵のローテーションを考慮した準備
署名を検証するための公開鍵は、暗号漏えいが疑われる場合を想定し、有効期限内であってもローテーションする可能性があります。RPアプリに保持する公開鍵について、キー変更を自動的に処理するようにRPアプリを作成してください。
- JWK Set公開エンドポイント
https://auth-and-sign.go.jp/api/realms/main/protocol/openid-connect/certs - OpenID Provider Configuration エンドポイント
https://auth-and-sign.go.jp/api/realms/main/.well-known/openid-configuration
Webアプリケーションの脆弱性悪用への対策
悪意のあるリクエストを送信させることを目的とするクロスサイトリクエストフォージェリ(CSRF)への対策をしてください。
検証結果が一致しない場合はCSRFによる攻撃の可能性があるため、認証処理を中断し、エラー処理等を行ってください。
RPアプリの対応方法(CSRF)
- RPアプリは、state というランダムな値を生成して、認可リクエストに設定し、利用者のセッションにもその値を保存してください。
- state に設定する値については、別紙のAPIリファレンスをご参照ください。
- 必ず、認可リクエストごとに新しい state 値を生成してください。
- デジタル認証アプリサーバは、認可コードを含むリダイレクトをレスポンスする際に、state の値もRPへレスポンスします。
- RPアプリが生成した state と、デジタル認証アプリサーバからリダイレクトで送られた state が一致することを検証してください。
リプレイ攻撃への対策
利用者のログインセッション確立の際に、攻撃者がIDトークンを置き換えて不正ログインするリプレイ攻撃への対策をしてください。
検証結果が一致しない場合はリプレイ攻撃の可能性があるため、認証処理を中断し、エラー処理等を行ってください。
RPアプリの対応方法(nonce)
- RPアプリは、nonce というランダムな値を生成して、認可リクエストに設定し、利用者のセッションにもその値を保存してください。
- nonce に設定する値については、別紙のAPIリファレンスをご参照ください。
- 必ず、認可リクエストごとに新しい nonce 値を生成してください。
- デジタル認証アプリサーバは、アクセストークン発行レスポンスを返却する際、RPアプリが生成した nonce を含むIDトークンを返却します。
- RPアプリは、返却された nonce と自身が生成した nonce が一致することを検証してください。
認可コード横取り攻撃への対策
認可レスポンス受信時のリダイレクト処理における悪意のあるアプリへのなりすまし対策をしてください。
RPアプリの対応方法(PKCE)
- RPアプリは、認可リクエストに code_challenge、code_challenge_method パラメータを設定してください。
- 必ず、認可リクエストごとに新しい code_challenge 値を生成してください。
- code_challenge の生成方法となる code_challenge_method の値については、必ず「S256」を指定してください。
- code_challenge および code_challenge_method に設定する値の詳細については、 別紙のAPIリファレンスをご参照ください。
- 必ず、認可リクエストごとに新しい code_challenge 値を生成してください。
- デジタル認証アプリサービスでは、渡された code_challenge、code_challenge_method のほかに、code_verifier を用いて検証を行い、正規のリクエストに対してのみアクセストークンを発行します。
アクセストークン置き換え攻撃への対策
攻撃者がアクセストークンを置き換えて利用者になりすます攻撃の対策をしてください。
IDトークンのペイロードに含まれる at_hash を用いて、アクセストークンの置き換え対策のための検証を行ってください。
詳細な検証方法については以下をご参照ください。
参考:ペイロード部の検証
ログの保持
デジタル認証アプリサービスでは、API実行ログの提供は行いません。
問題が発生した際の原因や影響範囲の調査を行えるよう、API実行ログはRPアプリ内で一定期間保存してください。
内部ストレージからの漏洩対策のため、後述の保護対象のデータに記載されている情報は、ログの保存対象にしないでください。
プラットフォーム事業者に必要とされる証明書暗号対応
民間事業者が、デジタル認証アプリの署名APIを利用する場合、公的個人認証法に基づく大臣認定事業者(プラットフォーム事業者)と連携して電子署名の検証及び電子証明書の有効性確認を行う必要があります。
電子証明書の保持及び電子証明書の発行番号の取得・保持は、プラットフォーム事業者には認められていますが、プラットフォーム事業者に電子署名の検証等を委託する事業者(サービス提供事業者:SP事業者)には認められていないため、署名APIの利用申込みを行うSP事業者、連携するプラットフォーム事業者に以下の対応をお願い申し上げます。
民間事業者が署名APIを利用する場合、この対応は必須となります。
利用までの流れ
- SP事業者は、事前準備契約の申込書に対象となるサービスと連携するプラットフォーム事業者を記入します。(自社がプラットフォーム事業者であり、連携する事業者の役割を兼ねる場合は自社名を記入してください。プラットフォーム事業者に電子署名の検証等を委託する場合は委託先のプラットフォーム事業者名を記入してください。)
※暗号化用公開鍵の登録はサービス単位で行います。テスト環境と本番環境は別の鍵をご用意ください。 - テスト環境・本番環境の設定にあたり、デジタル庁から対象のプラットフォーム事業者に対して暗号化に用いる公開鍵の登録を依頼します。
- プラットフォーム事業者はサービスごとに鍵を生成しサービス名と公開鍵をデジタル庁に登録します。
- デジタル庁はSP事業者に対象となるサービスにおける公開鍵登録完了を連絡します。
署名用電子証明書と署名値の暗号化について
ECDH-ESの暗号化方式で署名用電子証明書と署名値を暗号化してデジタル認証サーバからプラットフォーム事業者側へ返却します。以下にデジタル認証サーバでの暗号化処理の概要を示します。
- 署名用電子証明書と署名値を暗号化するための鍵ペア(秘密鍵、公開鍵)を生成します。
- 生成した秘密鍵と取得したプラットフォーム事業者公開鍵で共有鍵を生成します。
- 署名用電子証明書と署名値をBase64エンコードします。
- 署名用電子証明書と署名値を共有鍵により暗号化し、JWE Compact Serialization 形式にシリアライズします。
- 生成した公開鍵、暗号化した署名用電子証明書および署名値を返却します。
公開鍵について
公開鍵はJWKフォーマットです。
参照情報:
パラメータ | 説明 | 必須項目 | 値 |
---|---|---|---|
kty | kty (key type) パラメータは、RSA や EC といった暗号アルゴリズムファミリーを示します。 | ○ | 必ず”EC”を設定 |
use | use (public key use) パラメータは当該公開鍵の用途を示します。use パラメータは、その鍵が暗号化目的で提供されるのか、署名検証目的で提供されるのかを示すために利用されます。 | ○ | 必ず”enc”を設定 |
alg | alg (algorithm) パラメータはその鍵で利用されるアルゴリズムを示します。alg 値は大文字小文字を区別する ASCII 文字列です。 | ○ | 必ず”ECDH-ES”を設定. |
crv | crv (Curve) パラメータは 楕円曲線暗号の曲線を示します。 | ○ | 必ず”P-256”を設定 |
x | x (X Coordinate) パラメータは楕円曲線暗号の X 座標を示します。Base64Url encode形式。 | ○ | 例:'ZvIoOu9BHnyM908tbt3XSk_vLP5StrzTID2zTMHdkdE' |
y | y (Y Coordinate) パラメータは楕円曲線暗号の Y 座標を示します。Base64Url encode形式。 | ○ | 例:'enLcIcBCtdBq9RMVz6Gq3khCl-y4cRYjtq1AjOnqvXQ' |
kid | kid (key ID) パラメータは特定の鍵を識別するために用いられます。例えば、鍵のロールオーバー時に JWK Set の中から必要な鍵を特定するなどの用途が考えられます。 kid 値の構造は未定義です。kid を JWK Set 内で用いる場合、JWK Set 内の異なる鍵は異なる kid 値を持つべきです。(異なる鍵が同じ kid 値を持つ例としては、kty (key type) は異なるが、アプリケーションからはそれらが互いに等価な代替手段であると考えられている場合などがあげられます。) kid 値は大文字小文字を区別する文字列です。 | 例: 'kQhKwf3045TiXEZ1RNFr2R0tv8KNcYHK-NraD2sLzzY' |
データの保護
クロスサイトスクリプティング(XSS)やクロスサイトリクエストフォージェリ(CSRF)を受けて、RPアプリのキャッシュや内部ストレージ等から直接アクセストークンや利用者のプライバシー情報が窃取された場合を想定する必要があります。
アクセストークン・利用者のプライバシー情報をRPアプリで安全に保持するよう暗号化を行い、セキュアなストレージへ保管し、利用する際に復号する等のデータ漏洩対策をしてください。
保護対象のデータ
トークン関連
- private_key_jwt認証方式における秘密鍵
- アクセストークン
- リフレッシュトークン
- IDトークン
認可エンドポイント関連
- 認可コード
署名トランザクション結果取得エンドポイント関連
- 署名用電子証明書情報
UserInfoエンドポイント関連
- 利用者識別子
- 氏名
- 住所
- 生年月日
- 性別
注意事項
大量アクセスの禁止
検証を目的とした大量リクエストは送信しないでください。負荷テストを行う場合等は、デジタル庁とテスト環境の調整を図ったうえで実施を検討してください。
補足資料
エンドポイント毎のエラー時返却ステータスとメッセージ
認可エンドポイント
RPアプリに対しての認可レスポンスは、HTTPステータス:302を返却します。
以下のような場合は、HTTPステータス:400番台、500番台をブラウザへ返却しエラー内容を利用者に表示します。そのため、すべての認可レスポンスがRPアプリへ返却されない場合があることに注意してください。
- redirect_uriが不正な場合
- client_idが不正な場合
- その他システムエラーが発生した場合 等
status | error | error_description | 概要 |
---|---|---|---|
302 | invalid_request | Missing parameter: ○○○○ | ・認可リクエストに必須パラメータのキーが存在 |
302 | unsupported_response_type | - | ・認可リクエストの response_type に値が設定 |
302 | unauthorized_client | Client is not allowed to initiate | ・認可リクエストパラメータの指定誤りです。 |
302 | invalid_scope | Invalid scopes: ○○○○ | ・認可リクエストの scopeに未知の値が設定 |
302 | invalid_request | Invalid parameter: ○○○○ | ・認可リクエストの必須パラメータに値が設定 |
302 | access_denied | Consent rejected by user | ・利用者が連携に同意しませんでした。 |
トークンエンドポイント
status | error | error_description | 概要 |
---|---|---|---|
400 | invalid_client | client_assertion parameter | ・トークンリクエストに必須パラメータ |
400 | invalid_client | Invalid client credentials | ・トークンリクエストに必須パラメータ |
400 | invalid_client | Parameter client_assertion_type | ・トークンリクエストに必須パラメータ |
400 | invalid_grant | Code not valid | ・トークンリクエストのパラメータ |
400 | invalid_grant | Incorrect redirect_uri | ・トークンリクエストのパラメータ |
400 | invalid_grant | Invalid refresh token | ・トークンリクエストの必須パラメータ |
400 | invalid_grant | PKCE invalid code verifier | ・code_challengeに対して |
400 | invalid_grant | Refresh token expired | ・トークンリクエストのパラメータ |
400 | invalid_request | Missing parameter: ○○○○ | ・トークンリクエストに必須パラメータ |
400 | invalid_request | No refresh token | ・トークンリクエストに必須パラメータ |
400 | invalid_scope | Invalid scopes: ○○○○ | ・トークンリクエストの必須パラメータ |
400 | unauthorized_client | Client not allowed for direct | ・トークンリクエストパラメータの指定誤りです。(grant_typeに"password"が設定されています) |
400 | unauthorized_client | Invalid client credentials | ・該当クライアントがシステム側で |
400 | unsupported_grant_type | Unsupported grant_type | ・トークンリクエストの必須パラメータ(grant_type)に値が設定されていません。 |
401 | invalid_client | Invalid client or Invalid | ・トークンリクエストに必須パラメータ |
500 | unknown_error | - | ・その他システムエラー。 |
503 | service_temporarily_unavailable | Service Temporarily Unavailable | ・システムメンテナンス中。 |
UserInfoエンドポイント
status | error | error_description | 概要 |
---|---|---|---|
401 | invalid_token | Token verification failed | ・UserInfoリクエストのアクセストークンが無効です。 |
500 | server_error | Invalid admin console parameter | ・デジタル認証アプリサービスの設定異常が発生しています。 |
500 | server_error | Internal server error | ・デジタル認証アプリサービス内の通信エラーです。 |
500 | unknown_error | - | ・その他システムエラーです。 |
503 | service_temporarily_unavailable | Service Temporarily Unavailable | ・システムメンテナンス中。 |
署名トランザクション開始エンドポイント
本エンドポイントにおいては、レスポンスに"item"が含まれます。
詳細は別紙のAPIリファレンスをご参照ください。
status | error | error_description | item | 概要 |
---|---|---|---|---|
400 | invalid_request | パラメータエラー。 | クライアントIDが設定されていません。 | ・署名トランザクション開始リクエストの |
400 | invalid_request | パラメータエラー。 | クライアントIDの桁数が不正です。 | ・署名トランザクション開始リクエストの |
400 | invalid_request | パラメータエラー。 | 署名対象データ名が設定されていません。 | ・署名トランザクション開始リクエストの |
400 | invalid_request | パラメータエラー。 | 署名対象データ名の桁数が不正です。 | ・署名トランザクション開始リクエストの |
400 | invalid_request | パラメータエラー。 | 署名対象識別コードが設定されていません。 | ・署名トランザクション開始リクエストの |
400 | invalid_request | パラメータエラー。 | 署名対象識別コードの桁数が不正です。 | ・署名トランザクション開始リクエストの |
400 | invalid_request | パラメータエラー。 | 署名対象ハッシュ値が設定されていません。 | ・署名トランザクション開始リクエストの |
400 | invalid_request | パラメータエラー。 | 署名対象ハッシュ値がエンコードされていません。 | ・署名トランザクション開始リクエストの |
400 | invalid_request | クライアントIDが不正です。 | - | ・署名トランザクション開始リクエストの |
500 | system_error | - | - | ・予期せぬエラーが発生しました。 |
503 | service_temporarily_unavailable | Service Temporarily Unavailable | - | ・システムメンテナンス中。 |
署名トランザクション結果取得エンドポイント
status | error | error_description | 概要 |
---|---|---|---|
400 | expired_sign_transaction | - | ・署名トランザクション結果取得リクエストの署名トランザクションが有効期限切れです。 |
400 | invalid_request | - | ・署名トランザクション結果取得リクエストの署名トランザクション状態が不正です。 |
400 | revoked_certificate | - | ・署名用電子証明書が失効しています。 |
401 | invalid_token | Token verification failed | ・署名トランザクション結果取得リクエストのアクセストークンが無効です。 |
500 | system_error | - | ・予期せぬエラーが発生しました。 |
503 | service_temporarily_unavailable | Service Temporarily Unavailable | ・システムメンテナンス中。 |
変更履歴
- 2024-06-21
- 初版公開
- 2024-06-24
- URL記載誤りと文言の修正
- 2024-06-27
- 文言の修正
- 2024-10-31
- Androidアプリの推奨バージョンを11以降に変更
以上