本文へ移動

デジタル認証アプリ

行政機関等・民間事業者向け実装ガイドライン

公開日

更新日

概要

「デジタル認証アプリ」は、マイナンバーカードを使った認証や署名を、安全に・簡単にするための、デジタル庁が提供するアプリです。行政機関や民間事業者は、デジタル認証アプリと連携するAPIを活用することで、マイナンバーカードを使った本人確認・認証や電子申請書類への署名機能を簡単に組み込むことができます。
サービスの概要については、以下の情報をご確認ください。

認証・署名のプロセスはOAuth 2.0 認可コードフロー、およびOpenID Connect 認可コードフローに基づきます。
署名プロセスのみ、認可コードフローにて署名処理を実施するためにクライアントクレデンシャルズフローが扱われます。
必要に応じて、トークンリフレッシュフローにてトークンのリフレッシュを行うことが可能です。
※「リソースオーナーパスワードクレデンシャルズフロー」ならびに「インプリシットフロー」は各プロセスにて採用しておりません。

対応OS

iOS及びAndroidのネイティブアプリとして提供します。デジタル認証アプリの推奨バージョンは以下の通りです。

プラットフォーム

バージョン

iOS

16.0以降
(16.0未満の場合は、アプリのダウンロードができません)

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リファレンスを参照のこと。

属性情報

利用者個人に関わる基本的な情報群を示す。
例えば、基本4情報は属性情報として分類される。

デジタル認証アプリサービスシステムメンテナンス(バックエンド)

デジタル認証アプリサーバのメンテナンスのためにサービスを停止している状態。

デジタル認証アプリサービスシステムメンテナンス(JPKI)

J-LISのJPKIシステムがメンテナンスのためにサービスを停止している状態。

JPKI(公的個人認証サービス)

マイナンバーカードのICチップに搭載された電子証明書を利用(マイナンバーは利用しません)して、オンラインで利用者本人の認証や契約書等の文書が改ざんされていないことの確認を公的に行うための安全・確実な本人確認を行う。

利用者証明用電子証明書

インターネットのウェブサイト等にログインする際に利用する(例:マイナポータルへのログイン、コンビニでの住民票の写し等の交付)。「ログインした者が、利用者本人であること」を証明することができる。

署名用電子証明書

インターネット等で電子文書を作成・送信する際に利用する(例:e-Tax等の電子申請)。「作成・送信した電子文書が、利用者が作成した真正なものであり、利用者が送信したものであること」を証明することができる。

基本4情報

氏名・住所・生年月日・性別を示す。

券面事項入力補助AP

マイナンバーカード内に設定されているアプリケーションの一つ。デジタル認証アプリで券面事項入力補助APのPINを入力することで、券面事項入力補助APから基本4情報を取得できる。

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アプリは、署名トランザクションの結果を取得し、署名用電子証明書の署名を検証してください。
署名トランザクション結果を取得するとき、「[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


アプリが表示するエラーについて

マイナンバーカードの操作でエラーが発生した際、デジタル認証アプリにてエラー画面を表示します。エラー内容は以下の通りです。

事象

エラー内容

カードの読み取りが中断された場合

もう一度カードを読み取ってください

マイナンバーカード以外を読み取った場合

正しいカードを読み取ってください

暗証番号が正しくない場合

暗証番号が正しくありません

署名用電子証明書がロックされている場合

署名用電子証明書がロックされています

署名用電子証明書がない場合

署名用電子証明書がありません

署名用電子証明書の有効期限が切れている場合

署名用電子証明書の有効期限が切れています

署名用電子証明書が失効している場合

署名用電子証明書が失効しています

署名用電子証明書が正しくない場合

署名用電子証明書が正しくありません

利用者証明用電子証明書がロックされている場合

利用者証明用電子証明書がロックされています

利用者証明用電子証明書がない場合

利用者証明用電子証明書がありません

利用者証明用電子証明書の有効期限が切れている場合

利用者証明用電子証明書の有効期限が切れています

利用者証明用電子証明書が失効している場合

利用者証明用電子証明書が失効しています

利用者証明用電子証明書が正しくない場合

利用者証明用電子証明書が正しくありません

実装にあたっての必須対応事項

デジタル認証アプリサーバへの接続に関する補足事項

通信プロトコルは、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トークンが改ざんされている可能性があるため、認証処理を中断し、エラー処理等を行ってください。

参考


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_method のほかに、code_verifier を用いて検証を行い、正規のリクエストに対してのみアクセストークンを発行します。

アクセストークン置き換え攻撃への対策

攻撃者がアクセストークンを置き換えて利用者になりすます攻撃の対策をしてください。
IDトークンのペイロードに含まれる at_hash を用いて、アクセストークンの置き換え対策のための検証を行ってください。
詳細な検証方法については以下をご参照ください。
参考:ペイロード部の検証

ログの保持

デジタル認証アプリサービスでは、API実行ログの提供は行いません。
問題が発生した際の原因や影響範囲の調査を行えるよう、API実行ログはRPアプリ内で一定期間保存してください。
内部ストレージからの漏洩対策のため、後述の保護対象のデータに記載されている情報は、ログの保存対象にしないでください。

プラットフォーム事業者に必要とされる証明書暗号対応

民間事業者が、デジタル認証アプリの署名APIを利用する場合、公的個人認証法に基づく大臣認定事業者(プラットフォーム事業者)と連携して電子署名の検証及び電子証明書の有効性確認を行う必要があります。
電子証明書の保持及び電子証明書の発行番号の取得・保持は、プラットフォーム事業者には認められていますが、プラットフォーム事業者に電子署名の検証等を委託する事業者(サービス提供事業者:SP事業者)には認められていないため、署名APIの利用申込みを行うSP事業者、連携するプラットフォーム事業者に以下の対応をお願い申し上げます。
民間事業者が署名APIを利用する場合、この対応は必須となります。

利用までの流れ

  1. SP事業者は、事前準備契約の申込書に対象となるサービスと連携するプラットフォーム事業者を記入します。(自社がプラットフォーム事業者であり、連携する事業者の役割を兼ねる場合は自社名を記入してください。プラットフォーム事業者に電子署名の検証等を委託する場合は委託先のプラットフォーム事業者名を記入してください。)
    ※暗号化用公開鍵の登録はサービス単位で行います。テスト環境と本番環境は別の鍵をご用意ください。
  2. テスト環境・本番環境の設定にあたり、デジタル庁から対象のプラットフォーム事業者に対して暗号化に用いる公開鍵の登録を依頼します。
  3. プラットフォーム事業者はサービスごとに鍵を生成しサービス名と公開鍵をデジタル庁に登録します。
  4. デジタル庁はSP事業者に対象となるサービスにおける公開鍵登録完了を連絡します。

署名用電子証明書と署名値の暗号化について

ECDH-ESの暗号化方式で署名用電子証明書と署名値を暗号化してデジタル認証サーバからプラットフォーム事業者側へ返却します。以下にデジタル認証サーバでの暗号化処理の概要を示します。

  1. 署名用電子証明書と署名値を暗号化するための鍵ペア(秘密鍵、公開鍵)を生成します。
  2. 生成した秘密鍵と取得したプラットフォーム事業者公開鍵で共有鍵を生成します。
  3. 署名用電子証明書と署名値をBase64エンコードします。
  4. 署名用電子証明書と署名値を共有鍵により暗号化し、JWE Compact Serialization 形式にシリアライズします。
  5. 生成した公開鍵、暗号化した署名用電子証明書および署名値を返却します。

公開鍵について

公開鍵は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 に値が設定
されていません。
・認可リクエストの 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

・利用者が連携に同意しませんでした。

トークンエンドポイント

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

概要

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が設定されていません。

・署名トランザクション開始リクエストの
クライアント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が不正です。

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以降に変更

以上

loading icon読み込み中