デジタル認証アプリ
行政機関等・民間事業者向け実装ガイドライン
公開日
更新日
概要
「デジタル認証アプリ」は、マイナンバーカードを使った認証や署名を、安全に・簡単にするための、デジタル庁が提供するアプリです。行政機関や民間事業者は、デジタル認証アプリと連携するAPIを活用することで、マイナンバーカードを使った本人確認・認証や電子申請書類への署名機能を簡単に組み込むことができます。
サービスの概要については、以下の情報をご確認ください。
認証・署名のプロセスはOAuth 2.0 認可コードフロー、およびOpenID Connect 認可コードフローに基づきます。
署名プロセスのみ、認可コードフローにて署名処理を実施するためにクライアントクレデンシャルズフローが扱われます。
必要に応じて、トークンリフレッシュフローにてトークンのリフレッシュを行うことが可能です。
※「リソースオーナーパスワードクレデンシャルズフロー」ならびに「インプリシットフロー」は各プロセスにて採用しておりません。
対応OS
iOS及びAndroidのネイティブアプリとして提供しています。デジタル認証アプリの推奨バージョンは以下の通りです。
| プラットフォーム | バージョン |
|---|---|
| iOS | 16.0以降 （16.0未満の場合は、アプリのダウンロードができません） |
| Android | Android 11以降 （11未満の場合は、アプリのダウンロードができません） |
用語定義
本ガイドラインおいて扱われる用語について、以下のとおり定義します。
| 用語名 | 説明 |
|---|---|
| デジタル認証アプリ | マイナンバーカードの証明書を読込み、デジタル認証アプリサーバと通信してRPの認証、署名を行うクライアントソフトウェア。 |
| デジタル認証アプリサーバ | デジタル認証アプリと共にRPの認証、署名を行うバックエンドサーバ。 OP（OpenID Provider）の役割をもつ。 参考：OpenID Connect Core 1.0 - 1.2 Terminology |
| デジタル認証アプリサービス | デジタル認証アプリのサービス全体を示す。 |
| デジタル認証アプリサービスAPI | デジタル認証アプリサービスが行政機関等及び民間事業者向けに開発するAPI。 |
| 利用者識別子 | デジタル認証アプリサーバがRPへ発行する識別子（PPID）。RP内で利用者を特定することができる。RPごとにユニークな識別子を発行する。 |
| 同一端末 | デジタル認証アプリがインストールされている端末内でRPのアプリケーション、もしくはRPのWebサービスが実行されている状態。 |
| 別端末 | デジタル認証アプリがインストールされている端末とは別の端末でRPのアプリケーション、もしくはRPのWebサービスが実行されている状態。 |
| クライアントID | RPを特定するID。 デジタル認証アプリサービスにRPを登録した時、デジタル庁から発行される。 OAuth 2.0 認可コードフローにおける用語定義「Client Identifier」に基づく。 参考：RFC6749 The OAuth 2.0 Authorization Framework - 2.2 Client Identifier |
| 署名対象データ名 | 署名するデータの名称。 RP側で自由に設定可能。 利用者が署名対象を識別するために、署名時に表示する項目。 ※文字や文字数などの制限はAPIリファレンスを参照のこと。 |
| 署名対象識別コード | 署名するデータを識別するために、RPが発行するコード。 RP側のサイトで表示された署名対象識別コードと、デジタル認証アプリに表示された署名対象識別コードの一致を確認することで、利用者は、RP側で発行された電子署名対象に対して署名することを確認する。 ※文字や文字数などの制限はAPIリファレンスを参照のこと。 |
| 属性情報 | 利用者個人に関わる基本的な情報群を示す。 例えば、基本４情報は属性情報として分類される。 |
| デジタル認証アプリサービスシステムメンテナンス（バックエンド） | デジタル認証アプリサーバのメンテナンスのためにサービスを停止している状態。 |
| デジタル認証アプリサービスシステムメンテナンス（JPKI） | J-LISのJPKIシステムがメンテナンスのためにサービスを停止している状態。 |
| JPKI（公的個人認証サービス） | マイナンバーカードのICチップに搭載された電子証明書を利用（マイナンバーは利用しません）して、オンラインで利用者本人の認証や契約書等の文書が改ざんされていないことの確認を公的に行うための安全・確実な本人確認を行う。 |
| 利用者証明用電子証明書 | インターネットのウェブサイト等にログインする際に利用する（例：マイナポータルへのログイン、コンビニでの住民票の写し等の交付）。「ログインした者が、利用者本人であること」を証明することができる。 |
| 署名用電子証明書 | インターネット等で電子文書を作成・送信する際に利用する（例：e-Tax等の電子申請）。「作成・送信した電子文書が、利用者が作成した真正なものであり、利用者が送信したものであること」を証明することができる。 |
| 基本４情報 | 氏名・住所・生年月日・性別を示す。 |
| 券面事項入力補助AP | マイナンバーカード内に設定されているアプリケーションの一つ。デジタル認証アプリで券面事項入力補助APのPINを入力することで、券面事項入力補助APから基本４情報を取得できる。 |
| RP | 「Relying Party」の略称。 OpenID Connect プロトコルにおける用語定義「Relying Party」に基づく。 行政機関等及び民間事業者が提供するサービスを指す。 参考：OpenID Connect Core 1.0 - 1.2 Terminology |
| 認可コード | OAuth 2.0 認可フレームワークにおける用語定義「Authorization Code」に基づく。 参考：RFC6749 The OAuth 2.0 Authorization Framework - 1.3.1 Authorization Code |
| IDトークン | OpenID Connect プロトコルにおける用語定義「ID Token」に基づく。 参考：OpenID Connect Core 1.0 - 1.2 Terminology |
| アクセストークン | OAuth 2.0 認可フレームワークにおける用語定義「Access Tokens」に基づく。 参考：RFC6749 The OAuth 2.0 Authorization Framework - 1.4 Access Token |
| リフレッシュトークン | OAuth 2.0 認可フレームワークにおける用語定義「Refresh Tokens」に基づく。 参考：RFC6749 The OAuth 2.0 Authorization Framework - 1.5 Refresh Token |
| PPID | 「Pairwise Pseudonymous Identifier」の略称。 OpenID Connect にて定義された用語「Pairwise Pseudonymous Identifier」の定義に基づく。 参考：OpenID Connect Core 1.0 - 1.2 Terminology |
| JWT | コンパクトでURLセーフなクレームの表現手段。 詳細な仕様はRFC7519にて標準化されている。 参考：RFC7519 JSON Web Token（JWT） |
| JWK | 暗号鍵を表すJSONオブジェクト。 詳細な仕様はRFC7517にて標準化されている。 参考：RFC7517 JSON Web Key （JWK） |
| クライアントクレデンシャル | 下記参考リンクにおける「2.3. Client Authentication」内の「client credentials」に基づく。 参考：RFC6749 The OAuth 2.0 Authorization Framework - 2.3 Client Authentication |
| OpenID Providerメタデータ | OpenIDプロパイダを構成するメタデータ。 OpenID Provider Configurationエンドポイントで確認できる。 |
エンドポイント
以下に、デジタル認証アプリサービスがサポートするエンドポイントの概要および使用目的を示します。
| エンドポイント名 | 使用目的 |
|---|---|
| 認可エンドポイント | OpenID Connect に準拠した、RPアプリを認可するための認可コードを取得するエンドポイント。 RPアプリから認可リクエストを送信し、デジタル認証アプリサービスにて本人確認が完了したとき、RPアプリへの認可レスポンスを返却する。 |
| トークンエンドポイント | OpenID Connect に準拠した、トークンを発行するためのエンドポイント。 受信した grant_type(トークン発行フロー)に応じて、以下のトークンを返却する。 ・アクセストークン ・IDトークン ・リフレッシュトークン grant_typeごとに返却されるトークン種別の詳細は、別紙のAPIリファレンスを参照のこと。 |
| UserInfoエンドポイント | OpenID Connect に準拠した、利用者識別子および利用者の属性情報をRPアプリへ提供するためのエンドポイント。 |
| 署名トランザクション開始エンドポイント | デジタル認証アプリサービス独自に実装した、RPアプリから署名対象データを受け取るためのエンドポイント。 デジタル認証アプリサービスにて署名処理を実行するために、署名トランザクションIDが発行される。 |
| 署名トランザクション結果取得エンドポイント | デジタル認証アプリサービス独自に実装した、RPアプリへ署名結果を返却するためのエンドポイント。 署名トランザクションIDをもとに、デジタル認証アプリサービスにて実施した署名処理結果をRPアプリへ返却する。 |
| OpenID Provider Configuration エンドポイント | OpenID Connect に準拠した、RPアプリが各エンドポイントのURIを確認するためのエンドポイント。 |
| JWK Set公開エンドポイント | OpenID Connect に準拠した、公開鍵の一覧を確認するためのエンドポイント。 デジタル認証アプリサービスが有効にした公開鍵を、JWKとしてエンコードし返却する。 |
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 | ・ 認可リクエストを正常に処理できた場合 デジタル認証アプリサービスは認可コードをクエリパラメータに設定し、リダイレクトURIへリダイレクトします。 リダイレクトURIには以下のクエリパラメータが付加されます。 - code - state - session_state ・ 認可リクエストに不正・欠落等の異常があった場合 デジタル認証アプリサービスはエラー内容をクエリパラメータに設定し、リダイレクトURIへリダイレクトします。 リダイレクトURIには以下のクエリパラメータが付加されます。 - error - error_description - state |
アプリへの連携
利用者の認証・署名は、同一端末と別端末のケースに対応でき ます。
シーケンス図のうち、RPが関連するリクエスト、レスポンス、検証処理等は、RPアプリで実装してください。
デジタル認証アプリとRPアプリ（もしくはWEBサイト）が別端末の場合であっても、RPアプリとのAPI連携で特別な処理は必要なく、フローの差異はありません。
RPアプリをPCで開いている場合、デジタル認証アプリサービス側で、スマートフォンとの連携を行う二次元コードが含まれたWEBページを表示します。利用者は、デジタル認証アプリサービスに表示された二次元コードを、スマートフォンのカメラで読み取ることで、PCとスマートフォンの連携を行います。認証・署名が完了するまでの間、PCとスマートフォンは連携しており、スマートフォン側で認証・署名が完了した後、PC側の画面が、redirect_uriで指定した画面に遷移します。
シーケンス図：認証
利用者が、利用者証明用電子証明書を使って認証するシーケンスです。
APIの概要とAPI利用の流れについては、サービスサイトをご確認ください。
上記シーケンス図にて、RPアプリが関連するリクエストとレスポンスについて、詳しく説明します。
| リクエスト・レスポンス | 説明 |
|---|---|
| [02] 認証開始リクエスト | RPアプリは、ブラウザから認証開始リクエストを受け取り、利用者の認証処理を開始してください。 |
| [03] 認可リクエスト [04] リダイレクト | RPアプリは、認可リクエストをデジタル認証アプリサービスへリダイレクトで送信してください。 利用者の属性情報を必要とする場合、取得対象のスコープをここで指定してください。 |
| [05] 利用者の認証・認可 | デジタル認証アプリにて、利用者の認証・認可を行うとともに、電子利用者証明の検証と利用者証明用電子証明書の有効性確認を行います。 |
| [06] 認可レスポンス [07] リダイレクト | デジタル認証アプリサービスは、利用者の認証・利用者の認可処理を行い、認可レスポンスをRPアプリへリダイレクトで送信します。 ・認可レスポンスが正常の場合 レスポンスに認可コードとCSRF対策パラメータ（state）が付加されます。 返却されたCSRF対策パラメータ（state）について検証してください。 ・認可レスポンスが異常の場合 レスポンスにエラー情報とCSRF対策パラメータ（state）が付加されます。 パラメータ誤りの場合は、パラメータを修正のうえ、再度認可リクエストを送信ください。 CSRF対策パラメータ（state）の検証に関しては、以下も併せてご参照ください。 参考：Webアプリケーションの脆弱性悪用への対策 |
| [08] トークンリクエスト [09] トークンレスポンス | RPアプリは、トークンリクエストを送信して以下の各種トークンを取得してください。 ・アクセストークン ・IDトークン ・リフレッシュトークン ・トークンレスポンスが正常の場合 取得した各種トークンは、セキュリティ対策のため適切な保護を行ってください。 参考：データの保護 また、取得したIDトークンは、正当性の検証を行ってください。 参考：IDトークンの検証 ・トークンレスポンスが異常の場合 パラメータ誤りの場合は、パラメータを修正のうえ、再度トークンリクエストを送信ください。 または、認可リクエストからやり直してください。 |
| [10] UserInfoリクエスト [11] UserInfoレスポンス | 利用者の属性情報は、必要に応じて、UserInfoリクエストを用いて取得できます。 属性情報を取得するとき、「[09] トークンレスポンス」で取得したアクセストークンを使用します。 ・UserInfoレスポンスが正常の場合 取得した属性情報は、セキュリティ対策のため適切な保護を行ってください。 参考：データの保護 ・UserInfoレスポンスが異常の場合 アクセストークンの検証に失敗した場合は、 アクセストークンが有効な状態であるかをご確認ください。 ※有効でなかった場合、リフレッシュトークンでトークンリフレッシュを実施し、アクセストークンを発行したうえでもう一度UserInfoリクエストを試行してください。 または、認可リクエストからやり直してください。 ※データは1時間以内に削除されます。 |
| [12] レスポンス | フロー完了時にRPコンテンツのログイン済画面へ遷移します。 |
シーケンス図：署名
利用者が、署名用電子証明書を使って、文書に対して電子署名するシーケンスです。
APIの概要とAPI利用の流れについては、サービスサイトをご確認ください。
上記シーケンス図にて、RPアプリが関連するリクエストとレスポンスについて、詳しく説明します。
| リクエスト・レスポンス | 説明 |
|---|---|
| [02] 署名開始リクエスト | RPアプリは、ブラウザから署名開始リクエストを受け取り、利用者の署名処理を開始してください。 |
| [03] 署名対象ハッシュ値生成 | RPアプリは、署名対象データをもとに署名対象ハッシュ値をbase64エンコードにて生成してください。 |
| [04] トークンリクエスト（client_credentials） [05] トークンレスポンス（client_credentials） | RPアプリは、署名トランザクションを開始する為、アクセストークンを取得してください。 アクセストークンの有効期限内であれば利用者を跨いで利用可能です。 |
| [06] 署名トランザクション 開始リクエスト | RPアプリは、「[05]トークンレスポンス（client_credentials）」で取得したアクセストークンをもとに、 デジタル認証アプリサービスから署名トランザクションIDを取得してください。 |
| [08] 認可リクエスト [09] リダイレクト | RPアプリは、認可リクエストをデジタル認証アプリサービスへリダイレクトで送信してください。 |
| [10] 利用者が 署名対象ハッシュ値に署名 | デジタル認証アプリにて、利用者が署名対象ハッシュ値に署名します。 行政機関向けには、署名値の作成、署名用電子証明書の認証パスの検証、署名用電子証明書の有効期間の検証、署名用電子証明書の有効性確認を行います。 民間事業者向けには、署名値の作成、署名用電子証明書の認証パスの検証、署名用電子証明書の有効期間の検証を行います。 行政機関向け、民間事業者向けどちらも、署名検証（署名対象データ、署名対象ハッシュ値、署名値の確認）は行いません。署名トランザクション結果受け取り後、署名検証をお願い致します。 |
| [11] 認可レスポンス [12] リダイレクト | デジタル認証アプリサービスは、利用者の認証と、RPアプリが利用者の属性情報を利用することの認可を行い、認可レスポンスをRPアプリへリダイレクトで送信します。 ・認可レスポンスが正常の場合 レスポンスに認可コードとCSRF対策パラメータ（state）が付加されます。 返却されたCSRF対策パラメータ（state）について検証してください。 ・認可レスポンスが異常の場合 レスポンスにエラー情報とCSRF対策パラメータ（state）が付加されます。 パラメータ誤りの場合は、パラメータを修正のうえ、再度認可リクエストを送信ください。 CSRF対策パラメータ（state）の検証に関しては、以下も併せてご参照ください。 参考：Webアプリケーションの脆弱性悪用への対策 |
| [13] トークンリクエスト [14] トークンレスポンス [15]IDトークン検証 | RPアプリは、トークンリクエストを送信して以下の各種トークンを取得してください。 ・アクセストークン ・IDトークン ・リフレッシュトークン ・トークンレスポンスが正常の場合 取得した各種トークンは、セキュリティ対策のため適切な保護を行ってください。 参考：データの保護 RPアプリは、取得したIDトークンの正当性を検証してください。 参考：IDトークンの検証 ・トークンレスポンスが異常の場合 パラメータ誤りの場合は、パラメータを修正のうえ、再度トークンリクエストを送信ください。 または、認可リクエストからやり直してください。 |
| [16] 署名トランザクション 結果取得リクエスト [17] 署名トランザクション 結果取得レスポンス | 民間事業者のRPアプリは、署名トランザクションの結果を取得し、プラットフォーム事業者へ取得結果を連携して署名検証を行なってください。 行政機関のRPアプリは、署名トランザクションの結果を取得し、署名用電子証明書の署名を検証してください。 署名トランザクション結果を取得するとき、「[14] トークンレスポンス」で取得したアクセストークン を使用します。 ・署名トランザクション結果取得レスポンスが異常の場合 アクセストークンの検証に失敗した場合は、 アクセストークンが有効な状態であるかをご確認ください。 ※有効でなかった場合、リフレッシュトークンでトークンリフレッシュを実施し、アクセストークンを発行したうえでもう一度署名トランザクション結果取得リクエストを試行してください。 または、認可リクエストからやり直してください。 RPアプリは、署名トランザクションの結果を取得し、署名検証（署名対象データ、署名対象ハッシュ値、署名値の確認）してください。 |
| [18] UserInfoリクエスト [19] UserInfoレスポンス | 利用者の属性情報は、必要に応じて、UserInfoリクエストを用いて取得できます。 属性情報を取得するとき、「[14] トークンレスポンス」で取得したアクセストークンを使用します。 ・UserInfoレスポンスが正常の場合 取得した属性情報は、セキュリティ対策のため適切な保護を行ってください。 参考：デー タの保護 ・UserInfoレスポンスが異常の場合 アクセストークンの検証に失敗した場合は、 アクセストークンが有効な状態であるかをご確認ください。 ※有効でなかった場合、リフレッシュトークンでトークンリフレッシュを実施し、アクセストークンを発行したうえでもう一度UserInfoリクエストを試行してください。 または、認可リクエストからやり直してください。 ※UserInfoリクエストで取得できる属性情報は、券面入力補助APのものです。署名用電子証明書に付属する4情報が必要な場合は、署名用電子証明書から取得をお願いします。 ※データは1時間以内に削除されます。 |
| [20] レスポンス | フロー完了時にRPコンテンツの署名完了画面へ遷移します。 |
シーケンス図：デジタル認証アプリホーム画面・RPアプリとの接続解除
デジタル認証アプリサービスのホーム画面に関する機能及びRPとの接続解除に関連するシーケンスです。
上記シーケンス図にて、RPアプリが関連するリクエストとレスポンスについて、詳しく説明します。
| リクエスト・レスポンス | 説明 |
|---|---|
| [04] RP一覧画面 RP解除 [12] 端末一覧画面 RPログアウト [18] アカウント削除 | 利用者がRPの解除・ログアウト・アカウントの削除を行う際、デジタル認証アプリサービスは、RPアプリに対して back-channel logout リクエストをします。 リクエストは、RP事業者申請の際に指定された back-channel logout URL へ以下の形式で行います。 RP事業者申請の際に指定されなかった場合は、リクエストしません。 ・メソッド：POST ・Content-Type：application/x-www-form-urlencoded ・パラメータ：logoutトークン RPアプリは、デジタル認証アプリサービスとの認証状態が不整合とならないよう、ログアウトできます。 logout トークンを検証し、必要に応じて利用者のセッション無効化処理を実装してください。 ログアウトするべき利用者・セッションは、logoutトークンペイロード部の、以下のクレーム値で判別できます。 ・認証後の sub 値と logout トークンの sub 値で利用者を紐付け RPアプリのログアウト処理後は、以下のHTTPステータスコードをレスポンスしてください。 ・成功時：200 ・失敗時：400 参考：back-channel logoutの詳細は以下をご参照ください。 OpenID Connect Back-Channel Logout 1.0 |
署名方式について
概要
署名対象データと署名値をJ-LIS等に提出することにより申請する場合の署名方式をサポートしました。
署名対象データと署名値をJ-LIS等に提出する場合の署名方式について
デジタル認証アプリ側では署名対象データの本文を受け取らないため、事業者サーバ（RP)にて、署名対象データをハッシュ化（SHA256）します。
このとき、ハッシュ化したデータにDigestInfoを付加し、そのデータをbase64でエンコードしたデータを、署名対象ハッシュ値として、デジタル認証アプリに対して署名トランザクション開始リクエストを行います。
デジタル認証アプリはリクエストを受け取るとデータをbase64でデコードし、（再度ハッシュ化を行わず）マイナンバーカードのカードAPライブラリ（電子証明書取得機能）によって署名します。カードAPライブラリ（電子証明書取得機能）が署名した署名値をデジタル認証アプリサーバからはRPへ返却します。
※この方式では、ハッシュ値の欠損確認等を行うことができません。必ず署名対象データのハッシュ値が存在するようにRP側で保証できる状態にしてください。
署名対象ハッシュ値の作成方法
署名トランザクション開始APIのdataの項目に、以下で生成したものを設定しリクエストしてください。
- 署名対象データをハッシュ化（SHA256)する
- ハッシュ値にSHA256を示すDigestInfoを付加する
- DigestInfo+ハッシュ値（SHA256)をbase64エンコードする
参考：ハッシュ値の作成方法の例
以下の「xx市ZZ申請」データを署名するケースにおいて説明します。
- 以下の<申請書>タグを対象としてダイジェスト値を生成し、Base64形式に変換する
- <SignedInfo>の<DigestValue>タグに1.のBase64形式のメッセージダイジェスト値を設定する
- <SignedInfo>タグが構成するXMLを対象にカードAPライブラリ（電子証明書取得 機能）によって署名する。
- 3.の署名情報をBase64形式に変換して、<SignatureValue>タグに設定する
- 3.の署名用電子証明書をBase64形式に変換して、<X509Certificate>タグに設定する。
【xx市ZZ申請】
<?xml version="1.0" encoding="UTF-8"?>
<ZZ申請情報>
<申請書>
<申請日>2025/02/04</申請日>
<申請時間>13:46:00</申請時間>
<申請ID>XXXX</申請ID>
<サービスID>000001</サービスID>
<利用者情報>
<住所>神奈川県横浜市</住所>
<氏名>住民太郎</氏名>
<生年月日>19980720</生年月日>
<性別>1</性別>
</利用者情報>
</申請書>
<Signature>
<SignedInfo>
<CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"></CanonicalizationMethod>
<SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"></SignatureMethod>
<Reference>
<Transforms>
<Transform Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"></Transform>
<Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"></Transform>
</Transforms>
<DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"></DigestMethod>
<DigestValue>**メッセージダイジェスト値（base64)**</DigestValue>
</Reference>
</SignedInfo>
<SignatureValue>**署名値(base64)**</SignatureValue>
<KeyInfo>
<X509Data>
<X509Certificate>**電子証明書(base64)**</X509Certificate>
</X509Data>
</KeyInfo>
</Signature>
</利用者同意申請情報>
上記の処理のシーケンスを示します。
既存の署名機能について
署名トランザクション開始リクエストのdataにDigestInfoが含まれていない場合、データの安全性の担保のため、デジタル認証アプリ側で再度ハッシュ化を行います。
デジタル認証アプリが提供する既存の署名APIは、事業者サーバ（RP）にて、署名対象データをハッシュ化（SHA256）およびbase64でエンコードしたデータを用意し、デジタル認証アプリに対して署名トランザクション開始リクエストを行います。デジタル認証アプリはリクエストを受け取るとデータをbase64でデコードし、再度ハッシュ化（SHA256）します。次にマイナンバーカードのカードAPライブラリ（電子証明書取得機能）によって署名します。カードAPライブラリ（電子証明書取得機能）が署名した署名値をデジタル認証アプリはRPへ返します。
アプリが表示するエラーについて
マイナンバーカードの操作でエラーが発生した際、デジタル認証アプリにてエラー画面を表示します。エラー内容は以下の通りです。
| 事象 | エラー内容 |
|---|---|
| カードの読み取りが中断された場合 | もう一度カードを読み取ってください |
| マイナンバーカード以外を読み取った場合 | 正しいカードを読み取ってください |
| 暗証番号が正しくない場合 | 暗証番号が正しくありません |
| 署名用電子証明書がロックされている場合 | 署名用電子証明書がロックされています |
| 署名用電子証明書がない場合 | 署名用電子証明書がありません |
| 署名用電子証明書の有効期限が切れている場合 | 署名用電子証明書の有効期限が切れています |
| 署名用電子証明書が失効している場合 | 署名用電子証明書が失効しています |
| 署名用電子証明書が正しくない場合 | 署名用電子証明書が正しくありません |
| 利用者証明用電子証明書がロックされている場合 | 利用者証明用電子証明書がロックされています |
| 利用者証明用電子証明書がない場合 | 利用者証明用電子証明書がありません |
| 利用者証明用電子証明書の有効期限が切れている場合 | 利用者証明用電子証明書の有効期限が切れています |
| 利用者証明用電子証明書が失効している場合 | 利用者証明用電子証明書が失効しています |
| 利用者証明用電子証明書が正しくない場合 | 利用者証明用電子証明書が正しくありません |
実装にあたっての必須対応事項
デジタル認証アプリサーバへの接続に関する補足事項
通信プロトコルは、HTTPS（TLS1.2、TLS1.3）です。また、以下のSSLサーバー証明書の検証が可能なルート証明書が必要となります。
| 証明書 | 内容 |
|---|---|
| SSLサーバー証明書 | セコムパスポート for Web EV2.0 |
| ルート証明機関 | Security Communication RootCA2 |
リダイレクト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:// で始まる URL） | https://auth-and-sign.go.jp/realms/main/ |
| aud | RPアプリのクライアントID | 501b35d6-bb32-462e-b84c-0fd2bb0574d8 |
| sub | 認証された利用者の識別子 （PPID（Pairwise Pseudonymous Identifier）） | 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 | アクセストークンのハッシュ値。 access_token 値の ASCII 表現における オクテットの、ハッシュ左半分を Base64URL エンコードした値 | 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:// で始まる URL） | https://auth-and-sign.go.jp/realms/auth-and-sign |
| aud | RPアプリのクライアントID | d579245d-2673-49e4-a6ab-22a17c2caacb |
| sub | 認証された利用者の識別子 （PPID （Pairwise Pseudonymous Identifier）） | 4d75797d-9546-3792-a9cd-95e644f91072 |
| exp | JWT の有効期限 | 1711990838 |
| sid | セッションID | 653a7ccb-3646-4c94-ac5e-8c5342f12f32 |
| events | JWT がlogoutトークンであることを宣言する値 ※JSONオブジェクトで右記の値が固定値となる | {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 | invalid_request | Client disabled | ・クライアントが停止された。 |
| 302 | unsupported_response_type | - | ・認可リクエストの response_type に値が設定 されていません。 ・認可リクエストの response_type に未知の値 が設定されています。 ※デジタル認証アプリサービスにおいては、「code」のみをサポートします。 |
| 302 | unauthorized_client | Client is not allowed to initiate browser login with given response_type. Implicit flow is disabled for the client. | ・認可リクエストパラメータの指定誤りです。 ※response_typeに"token"が設定されています。 |
| 302 | invalid_scope | Invalid scopes: ○○○○ | ・認可リクエストの scopeに未知の値が設定 されています。 ※「○○○○」にはscopeの値が設定されます。 |
| 302 | invalid_request | Invalid parameter: ○○○○ | ・認可リクエストの必須パラメータに値が設定 されていません。 ・認可リクエストのパラメータに未知の値が設定 されています。 ※「○○○○」には必須パラメータ名が設定されます。 |
| 302 | access_denied | Consent rejected by user | ・利用者が連携に同意しませんでした。 |
| 302 | access_denied | Authentication failed | ・マイナンバーカードによる認証手続に失敗しました。 |
トークンエンドポイント
| status | error | error_description | 概要 |
|---|---|---|---|
| 400 | invalid_client | client_assertion parameter missing | ・トークンリ クエストに必須パラメータ (client_assertion)が存在しません。 ※署名プロセスにおけるクライアントクレデンシャルズフローの場合に返却されます。 |
| 400 | invalid_client | Invalid client credentials | ・トークンリクエストに必須パラメータ （client_id）が存在しません。 ・トークンリクエストのパラメータ （client_id）に未知の値が設定されています。 ・トークンリクエストのパラメータ （client_id）に値が設定されていません。 |
| 400 | invalid_client | Parameter client_assertion_type is missing | ・トークンリクエストに必須パラメータ （client_assertion_type）が存在しません。 ※署名プロセスにおけるクライアントクレデンシャルズフローの場合に返却されます。 |
| 400 | invalid_grant | Code not valid | ・トークンリクエストのパラメータ （code）に値が設定されていません。 ・トークンリクエストのパラメータ（code）に無効な値が設定されています。 ※認可コード（code）の利用は1回きりのため、認可コードの再利用を試みた場合も本エラーが発生します。 |
| 400 | invalid_grant | Incorrect redirect_uri | ・トークンリクエストのパラメータ （redirect_uri）が認可リ クエスト時の リダイレクトURIと異なっています。 ・トークンリクエストのパラメータ（redirect_uri）が存在しません。 |
| 400 | invalid_grant | Invalid refresh token | ・トークンリクエストの必須パラメータ （refresh_token）に値が設定されていません。 ・トークンリクエストのパラメータ（refresh_token）に未知の値が設定されています。 |
| 400 | invalid_grant | PKCE invalid code verifier | ・code_challengeに対して code_verifierの値が誤っています。 |
| 400 | invalid_grant | Refresh token expired | ・トークンリクエストのパラメータ （refresh_token）のリフレッシュ トークンが有効期限切れで失効しています。 |
| 400 | invalid_request | Missing parameter: ○○○○ | ・トークンリクエストに必須パラメータ のキーが存在しません。 ・トークンリクエストパラメータの指定誤りです。 ※「○○○○」には必須パラメータ名が設定されます。 |
| 400 | invalid_request | No refresh token | ・トークンリクエストに必須パラメータ （refresh_token）が存在しません。 |
| 400 | invalid_scope | Invalid scopes: ○○○○ | ・トークンリクエストの必須パラメータ （scope）に値が設定されていません。 ・トークンリクエストのパラメータ（scope）に未知の値が設定されています。 ※「○○○○」にはscopeの値が設定されます。 ※クライアントクレデンシャルズフローの場合に返却されます。 |
| 400 | unauthorized_client | Client not allowed for direct access grants | ・トークンリクエストパラメータの指定誤りです。（grant_typeに"password"が設定されています） |
| 400 | unauthorized_client | Invalid client credentials | ・該当クライアントがシステム側で 停止されています。 |
| 400 | unsupported_grant_type | Unsupported grant_type | ・トークンリクエストの必須パラメータ（grant_type）に値が設定されていません。 ・トークンリクエストのパラメータ（grant_type）に未知の値が設定されています。 |
| 401 | invalid_client | Invalid client or Invalid client credentials | ・トークンリクエストに必須パラメータ （client_assertionまたはclient_assertion_type） が存在しません。 ※認可コードフローまたはリフレッシュトークン発行時の場合に返却されます。 |
| 500 | unknown_error | - | ・その他システムエラー。 |
| 503 | service_temporarily_unavailable | Service Temporarily Unavailable | ・システムメンテナンス中。 |
UserInfoエンドポイント
| status | error | error_description | 概要 |
|---|---|---|---|
| 400 | expired_pf_provider_public_key | Pf provider public key is expired | ・PF事業者公開鍵が有効期限切れています。 |
| 400 | invalid_pf_provider_public_key | Pf provider public key is not registered | ・PF事業者公開鍵が登録されていません. |
| 401 | invalid_token | Token verification failed | ・UserInfoリクエストのアクセストークンが無効です。 |
| 500 | server_error | Invalid admin console parameter | ・デジタル認証アプリサービスの設定異常が発生しています。 |
| 500 | server_error | Internal server error | ・デジタル認証アプリサービス内の通信エラーです。 |
| 500 | unknown_error | - | ・その他システムエラーです。 |
| 500 | encryption_error | Certificate encryption error | ・証明書の暗号化でエラーが発生しました。 |
| 503 | service_temporarily_unavailable | Service Temporarily Unavailable | ・システムメンテナンス中。 |
署名トランザクション開始エンドポイント
本エンドポイントにおいては、レスポンスに"item"が含まれます。
詳細は別紙のAPIリファレンスをご参照ください。
| status | error | error_description | item | 概要 |
|---|---|---|---|---|
| 400 | invalid_request | パラメータエラー。 | クライアントIDが設定されていません。 | ・署名トランザクション開始リクエストの クライアントIDが設定されていません。 |
| 400 | invalid_request | パラメータエラー。 | クライアントIDの桁数が不正です。 | ・署名トランザクション開始リクエストの クライアントIDの桁数が不正です。 |
| 400 | invalid_request | パラメータエラー。 | 署名対象データ名が設定されていません。 | ・署名トランザクション開始リクエストの 署名対象データ名が設定されていません。 |
| 400 | invalid_request | パラメータエラー。 | 署名対象データ名の桁数が不正です。 | ・署名トランザクション開始リクエストの 署名対象データ名の桁数が不正です。 |
| 400 | invalid_request | パラメータエラー。 | 署名対象識別コードが設定されていません。 | ・署名トランザクション開始リクエストの 署名対象識別コードが設定されていません。 |
| 400 | invalid_request | パラメータエラー。 | 署名対象識別コードの桁数が不正です。 | ・署名トランザクション開始リクエストの 署名対象識別コードの桁数が不正です。 |
| 400 | invalid_request | パラメータエラー。 | 署名対象ハッシュ値が設定されていません。 | ・署名トランザクション開始リクエストの 署名対象ハッシュ値が設定されていません。 |
| 400 | invalid_request | パラメータエラー。 | 署名対象ハッシュ値がエンコードされていません。 | ・署名トランザクション開始リクエストの 署名対象ハッシュ値がエンコードされていません。 |
| 400 | invalid_request | クライアントIDが不正です。 | - | ・署名トランザクション開始リクエストの クライアントIDが不正です。 |
| 401 | invalid_grant | - | 権限がありません。 | ・署名トランザクション開始リクエストを実行するためのスコープがアクセストークンに含まれていません。 |
| 401 | invalid_token | Token verification failed | - | ・署名トランザクション開始リクエストのアクセストークンが無効です。 |
| 500 | system_error | - | - | ・予期せぬエラーが発生しました。 |
| 503 | service_temporarily_unavailable | Service Temporarily Unavailable | - | ・システムメンテナンス中。 |
署名トランザクション結果取得エンドポイント
| status | error | error_description | 概要 |
|---|---|---|---|
| 400 | expired_sign_transaction | - | ・署名トランザクション結果取得リクエストの署名トランザクションが有効期限切れです。 |
| 400 | invalid_request | - | ・署名トランザクション結果取得リクエストの署名トランザクション状態が不正です。 ・データが存在しません。 |
| 400 | invalid_certificat | - | ・署名用電子証明書の形式が不正です。 |
| 400 | expired_certificate | - | ・署名用電子証明書が有効期限切れです。 |
| 400 | revoked_certificate | - | ・署名用電子証明書が失効しています。 |
| 400 | certificate_not_match | - | ・利用者と異なるマイナンバーカードで署名を行っています。 |
| 400 | locked_certificate | - | ・署名用電子証明書がロックされています。 |
| 400 | not_installed_certificate | - | ・署名用電子証明書が未搭載です。 |
| 400 | expired_pf_provider_public_key | - | ・PF事業者公開鍵が有効期限切れです。 |
| 400 | invalid_pf_provider_public_key | - | ・PF事業者公開鍵が未登録です。 |
| 401 | invalid_grant | - | ・署名トランザクション結果取得リクエストを実行するためのスコープがアクセストークンに含まれていません。 |
| 401 | invalid_token | Token verification failed | ・署名トランザクション結果取得リクエストのアクセストークンが無効です。 |
| 500 | system_error | - | ・予期せぬエラーが発生しました。 |
| 500 | encryption_error | Certificate encryption error | ・証明書の暗号化でエラーが発生しました。 |
| 503 | service_temporarily_unavailable | Service Temporarily Unavailable | ・システムメンテナンス中。 |
変更履歴
- 2024-06-21
- 初版公開
- 2024-06-24
- URL記載誤りと文言の修正
- 2024-06-27
- 文言の修正
- 2024-10-31
- Androidアプリの推奨バージョンを11以降に変更
- 2025-03-27
- 署名方式についての説明の追加およびエラーレスポンスの修正、追加
以上
