デジタル認証サービスの「テストカード代替機能」とは。使い方、テストカードとの違い、切り替えの注意点を公式ドキュメントから整理する

TodoONada株式会社の土門です。デジタル庁の「デジタル認証サービス」（2026年8月25日にマイナアプリへ統合される前は「デジタル認証アプリ」）を組み込むとき、テスト環境には2つの試験方法があります。J-LISのテスト用マイナンバーカードとテスト用アプリで試す方法と、カードもアプリも使わずにAPIの応答だけを返してもらう「テストカード代替機能」です。

この記事は、テストカード代替機能について、デジタル庁の開発者サイトの公式ドキュメント、APIリファレンス、実装ガイドライン、サポートサイトの案内をもとに整理したものです。当社が実際に利用申請とテストカードの借用を行った経験も、公式の記述と区別して添えています。

この記事の要点

• テストカード代替機能は、テスト環境でAPIの応答をテストデータから返す機能。J-LISのテストカードが届く前から接続試験を始められる
• 公式に「代替機能とテスト用マイナアプリ（テスト用マイナンバーカード）を使ったテストは両立できない」と明記されている。切り替えは自分ではできず、そのたびにデジタル庁へ設定書で申し出る
• 基本的に認証API向け。署名APIでは署名値と証明書がダミーのため、署名検証とJ-LISでの有効性確認は試験できない
• 設定画面で「正常」「異常」と約20種類のエラーパターンを選べる。メンテナンス中や証明書ロックなど、実機では再現しにくい異常系を試せるのが最大の利点
• 代替機能で試せるのはRP（自社サービス）側のAPI連携まで。アプリの画面遷移、カード読み取り、暗証番号入力はテストカードでしか確認できない

テスト環境での2つの試験方法

デジタル庁のサポートサイトは、テスト環境での試験方法を次の2つと案内しています。

1. テストカード代替機能
2. J-LISから調達するテスト用マイナンバーカードと、テスト用マイナアプリ（旧デジタル認証アプリ）を使う方法

本番環境ではテスト用カードは使えず、本物のマイナンバーカードで確認します。手続き全体の中での位置づけは、デジタル庁のよくある質問に示された次の流れのうち3番目です。

1. 利用の申込
2. 事前準備契約の締結
3. テスト環境の提供・テスト
4. 本契約の締結
5. 本番環境の提供・テスト

事前準備契約の審査に必要な情報が揃ってからテスト環境が提供されるまでは、標準で10開庁日程度とされています。一方、J-LISのテストカードは貸与で1〜2か月程度、購入では約6か月程度かかるとサポートサイトに書かれています。当社の場合、借用だけで約2か月かかりました。テスト環境が先に使えるようになり、カードが後から届くのが普通の順番です。この空白期間を埋めるのが代替機能です。

テストカード代替機能とは

公式ドキュメントの定義は次のとおりです。

デジタル認証アプリおよびテスト用のマイナンバーカードを使用することなくサービスに組み込んだ認証および署名機能をテストすることができる機能です。

仕組みとしては、テスト環境のサーバがいくつかのテストデータを持っており、開発者が選んだデータに従ってAPIレスポンスを返します。通常なら認可リクエストのあとに利用者がマイナアプリでカードを読み取りますが、代替機能ではその部分が「テストレスポンス設定画面」に置き換わります。

提供範囲には条件があります。

• 基本的に認証APIの利用事業者向け。 公式ドキュメントには「認証APIをご利用のサービス事業者のみに提供します」とあります
• 署名APIでの利用は個別調整。 サポートサイトによると、署名APIで使いたい場合は機能の制約があるため、オンラインミーティングで調整します。署名値と署名用電子証明書がダミーデータなので、署名検証とJ-LISとの有効性確認の検証はできません

開発者サイトには署名APIのテストレスポンス設定画面の操作方法も載っていますが、使えるかどうかは契約時にデジタル庁と確認してください。

代替機能とテスト用マイナアプリは同時に使えない

この機能で最も注意すべき点です。公式ドキュメントには次のように書かれています。

テストカード代替機能を使用する場合とテスト用デジタル認証アプリ（テスト用マイナンバーカード）を使ったテストとを両立することはできません。

サポートサイトでは、さらに具体的な手順が示されています。

• まずはテストカード代替機能でAPIの組み込みを行う
• テスト用マイナアプリを使う場合は、「テスト環境・本番環境設定書.xlsx」で申し出る

つまり、どちらのモードで動くかはデジタル庁側の設定で決まります。開発者が画面やパラメータで切り替えることはできません。代替機能からテストカードへ、テストカードから代替機能へ、切り替えるたびにデジタル庁へ申請する必要があります。

設定書の更新方法は、事前準備契約の申込案内に書かれています。

• 各書類の「登録依頼内容」欄で「登録内容変更」を選ぶ
• 変更箇所を朱書きにする
• ファイル名の日付を、更新した連携日の日付に変える

事前準備契約の申請時点でも、代替機能を使う場合は「テスト用アプリの配信先の記入は一旦不要」とされています。テスト用アプリの配信先（テスト端末の情報）は、テストカードへ切り替えるときに設定書へ書き足すことになります。

当社の経験では、切り替えに伴って次の2点に注意が必要でした。

1. 代替機能の利用中はテスト用アプリが配信されない。 アプリを使った試験に移る段階で、設定書の該当シートを記入して改めて申請しました
2. テスト端末にアプリを入れたままにしない。 テスト端末にアプリが入っていると、DeepLinkが代替機能の画面ではなくアプリを起動してしまいます。代替機能で試験する間はアンインストールしておきます

切り替えは申請と反映を待つ手続きなので、何度も往復するとそのたびに待ち時間が発生します。「代替機能で確認すること」と「テストカードで確認すること」を先に分けておき、切り替えは原則1回で済ませる計画にするのが現実的です。後述の比較表を、その仕分けに使ってください。

使う前の準備

公式ドキュメントでは、事前準備として実装ガイドラインを参照し、RPとテスト環境の連携を済ませるよう求めています。RPは「Relying Party」の略で、デジタル認証サービスを組み込む自社サービスのことです。

テスト環境のベースURLは、APIリファレンスで次のように定義されています。

本番環境: https://auth-and-sign.go.jp/api
Sandbox: https://sb-auth-and-sign.go.jp/api

代替機能を使う場合も、RP側の実装は本番と同じOpenID Connectの認可コードフローです。APIリファレンスと実装ガイドラインで必須とされている主な点は次のとおりです。

項目	公式ドキュメントの要件
認可リクエスト	response_type=code 固定。scope に openid 必須。4情報は name address birthdate gender、署名は sign、顔写真は picture
認証要求の acr_values	aal3 crl または aal3 ocsp を指定。ocsp は申込時に相談
CSRF対策	リクエストごとに新しい state を生成し、戻り値と照合する
リプレイ対策	リクエストごとに新しい nonce を生成し、IDトークン内の値と照合する
認可コード横取り対策	PKCE必須。code_challenge_method は S256 固定
使えない文字	state nonce redirect_uri にセミコロンは使えない（2026年8月25日の改訂で明記）
トークンリクエスト	private_key_jwt でクライアント認証。client_assertion のJWTは有効期限を発行から60秒以内にする
IDトークン検証	署名アルゴリズムはES256。JWK Setを検証のたびに取得し、kid iss aud exp iat at_hash を検証する
UserInfo	属性情報は認可レスポンスから60分で破棄される。60分以内に取得する

代替機能は「カードとアプリの部分」を置き換えるだけなので、上の要件はすべて代替機能の段階で実装・確認できます。逆に言えば、代替機能で正常系と異常系が通っていれば、RP側の実装はほぼ固まっている状態です。

認証APIテストレスポンス設定画面の使い方

RPから認可リクエストを送ると、代替機能が有効なテスト環境では「認証APIテストレスポンス設定画面」が表示されます。画面の項目は次の4つです。

項目	内容
証明書タイプ	「マイナンバーカード」か「スマホ用電子証明書」を選ぶ。選んだタイプのテストカード情報だけが一覧に出る
レスポンス	「正常」か「異常」を選ぶ
エラーパターン	「異常」を選んだとき、認可エンドポイントが返すエラーの内容を選ぶ
テストカード情報一覧	試験できるマイナンバーカードとスマホ用電子証明書のテストデータ。試したい内容に合うものを選ぶ

証明書タイプの「スマホ用電子証明書」は、2026年4月24日の改訂で追加されました。デジタル認証サービスは2026年8月25日からスマホ用電子証明書に対応しています。

正常レスポンスを返す手順

1. 証明書タイプで「マイナンバーカード」か「スマホ用電子証明書」を選ぶ
2. レスポンスで「正常」を選ぶ
3. テストカード情報一覧から1件選び、「認証」ボタンを押す
4. RPへ認可レスポンスが返るので内容を確認する。続けてトークンリクエストなどの後続処理を試せる

異常レスポンスを返す手順

1. レスポンスで「異常」を選ぶ
2. エラーパターンを選ぶ
3. テストカード情報を選び、「認証」ボタンを押す
4. 選んだパターンに応じて、RPへエラーの認可レスポンスが返るか、エラー画面が表示される

公式ドキュメントの注意点が2つあります。「異常」を選んでエラーパターンを選ばないと、画面にエラーメッセージが出て先へ進めません。また、specified_certificate_type_not_match は一般利用を想定していないので選ばないよう案内されています。

署名APIテストレスポンス設定画面の使い方

署名APIでは、署名トランザクション開始エンドポイントで署名トランザクションIDを取得してから認可リクエストを送ります。代替機能では、そのあとに「署名APIテストレスポンス設定画面」が表示されます。認証の画面との違いは次の2項目です。

• 署名トランザクションID。 開始エンドポイントで発行されたIDが表示される。編集はできない
• 署名トランザクション結果取得エラーパターン。 署名フローを完了させたあと、結果取得エンドポイントで返すエラーを選ぶ

エラーの試し方は2通りあります。

1. 一般的な異常を試す。 「エラーパターン」を選ぶ。認可エンドポイントでエラーが返る
2. 結果取得時の異常を試す。 「エラーパターン」は未選択のまま、「署名トランザクション結果取得エラーパターン」を選ぶ。署名フロー自体は完了し、結果取得時にエラーが返る

2つ目では、specified_certificate_type_not_match と specified_certificate_type_unavailable は一般利用を想定していないため選ばないよう案内されています。

繰り返しになりますが、代替機能で返る署名値と署名用電子証明書はダミーです。プラットフォーム事業者と連携した署名検証や、J-LISでの有効性確認はテストカードで行う必要があります。

選べるエラーパターン

公式ドキュメントに掲載されているエラーパターンを、RP側で確認すべき挙動ごとにまとめます。

分類	エラーパターン	何が起きるか
リクエスト不備	invalid_request unsupported_response_type unauthorized_client invalid_scope	HTTP 302でRPへエラーの認可レスポンスが返る
利用者側の失敗	access_denied access_denied(Authentication failed)	HTTP 302で返る。後者はカード読み取りエラーを想定
サーバ内部エラー	server_error	HTTP 500でエラーレスポンスが返る
メンテナンス	service_temporarily_unavailable jpki_temporarily_unavailable	HTTP 503のエラー画面が表示される。前者はデジタル認証サービス、後者は公的個人認証サービスのメンテナンス
アクセス制御・負荷	forbidden payload_too_large too_many_requests bad_gateway gateway_timeout request_blocked	HTTP 504のエラー画面が表示される。request_blocked はWAFによる攻撃検知を想定
署名結果取得時	invalid_request-status expired_sign_transaction invalid_request-no_data locked_certificate not_installed_certificate	署名フロー完了後、結果取得時にエラーが返る。証明書ロックや証明書未搭載を再現できる

ここが代替機能のいちばんの価値です。メンテナンス中の応答、証明書のロック、署名用電子証明書が入っていないカードといった状態は、テストカードでは意図して作りにくいものです。RP側で、エラーごとに利用者へ何を表示し、どこへ戻すかを代替機能の段階で一通り確認しておくと、テストカードでの試験は正常系と実機固有の確認に集中できます。

なお、エラーがRPへ返らずデジタル庁側のエラー画面で止まるパターン（HTTP 503・504）もあります。この場合、利用者はRPの画面に戻ってきません。利用者が戻ってこなかった場合のRP側のセッションの扱いも、あわせて決めておく必要があります。

Sandboxでバックチャネルログアウトを試す

利用者がマイナアプリ側で連携解除やアカウント削除をすると、デジタル認証サービスからRPのback-channel logout URLへ、logoutトークン付きのPOSTが送られます。本物のアプリがない代替機能では、このリクエストを発生させるための専用エンドポイントが用意されています。

1. 代替機能で正常レスポンスの操作を行い、リフレッシュトークン、IDトークン、IDトークン内の sub のいずれかを取得する
2. クライアントアサーションを用意し、次のエンドポイントへPOSTする

POST https://sb-auth-and-sign.go.jp/api/realms/main/sandbox/logout
Content-Type: application/x-www-form-urlencoded

client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=（クライアント認証用のJWT）
&refresh_token=（リフレッシュトークン）

refresh_token の代わりに id_token（IDトークン）か subject_id（IDトークンの sub の値）を送ることもできます。成功するとHTTP 200で executed_backchannel_logout: true が返り、RPのback-channel logout URLにlogoutトークンが届きます。RPはこのトークンの正当性を検証してから、利用者のセッションを終了させます。

back-channel logout URLは事前準備契約の申請時に指定したものだけに送られ、指定していなければ送られません。ログアウト連携を実装する場合は、設定書に記入済みかを先に確認してください。

代替機能とテストカードの違い

ここまでの内容を、確認できることの違いとして表にまとめます。

確認したいこと	代替機能	テストカードとテスト用マイナアプリ
認可コードフロー、トークン取得、IDトークン検証、UserInfo取得	できる	できる
state・nonce・PKCEなどのRP側の検証処理	できる	できる
異常系（メンテナンス、証明書ロック、WAF検知など）の意図的な再現	できる。エラーパターンを選ぶだけ	難しい。状態を作れないものが多い
バックチャネルログアウト	専用のSandboxエンドポイントで発生させる	アプリで連携解除などを実際に操作する
マイナアプリの起動、画面遷移、PC・スマホ間の二次元コード連携	できない	できる
NFCでのカード読み取りと暗証番号入力	できない	できる
実際の電子証明書による検証、有効・失効・期限切れのカードでの挙動	できない	できる。J-LISの借用カードは有効・失効・期限切れを選べる
署名値の検証、プラットフォーム事業者との連携	できない。署名値と証明書はダミー	できる
利用できる時期	テスト環境の提供直後から	J-LISからカードが届いてから。貸与で1〜2か月程度
対象API	基本的に認証API。署名APIは要調整	認証API・署名API

テストカードの手配は、代替機能があるから省略できるものではありません。当社の経験では、代替機能での確認だけでは試験完了とは認められず、物理カードとアプリでの動作確認が求められました。J-LISのカードは、デジタル認証サービスで使う場合「全AP搭載」を指定するようサポートサイトで案内されています。手配の実際はJ-LISテスト用マイナンバーカード借用の記録にまとめています。

追記（2026年10月5日）: テストカードが届いたあと、テスト用マイナアプリで実際に通しました。下の2枚はアプリの起動画面とカード読み取り画面で、代替機能ではどちらも表示されません。4情報を要求すると暗証番号の入力が2回になることも、実機で初めて分かりました。全10画面の記録はデジタル認証サービスの認証を実機で通してみたにまとめています。

カードの調達がサービスイン日に間に合わない場合は、デジタル庁が当日限りでテストカードを貸し出す制度もあります。事前準備契約申込書を提出済みで、来庁できる事業者が対象です。API組み込みが終わっていること、テスト用マイナアプリが端末に入っていることが申込の前提で、カードは当日17時に返却します。

おすすめのテスト計画

公式の案内と当社の経験から、切り替えを1回で済ませる進め方を提案します。

段階	モード	やること
1	申請	事前準備契約の申請と同じ日にJ-LISへテストカードを依頼する（全AP搭載を指定）
2	代替機能	認可コードフロー、トークン取得とIDトークン検証、UserInfo取得、エラーパターン全種のRP側表示、バックチャネルログアウトを確認する
3	切り替え申請	テストカードが届く見込みが立ったら、設定書でテスト用マイナアプリへの切り替えを申し出る。テスト端末情報を記入する
4	テストカード	同一端末・別端末（二次元コード）の通し試験、カード読み取り、有効・失効・期限切れカードでの挙動、署名APIなら署名検証を確認する
5	本契約	試験の結果を踏まえて本契約を申し込み、本番環境では本物のマイナンバーカードで確認する

段階2で異常系まで終わらせておくことが重要です。テストカードに切り替えたあとで異常系の確認漏れに気づくと、代替機能へ戻す申請が必要になり、その間テストカードでの試験が止まります。

よくある質問

Q. テストカード代替機能とテスト用マイナアプリを同時に使えますか？

使えません。公式ドキュメントに「両立することはできません」と明記されています。どちらで動くかはデジタル庁側の設定で決まり、切り替えるには「テスト環境・本番環境設定書.xlsx」で申し出る必要があります。

Q. 代替機能は誰でも使えますか？

基本的には認証APIを利用する事業者向けです。署名APIで使いたい場合は、署名値と署名用電子証明書がダミーになる制約があるため、デジタル庁とのオンラインミーティングで調整します。

Q. 代替機能があればJ-LISのテストカードは不要ですか？

不要にはなりません。代替機能で確認できるのはRP側のAPI連携までで、アプリの操作、カードの読み取り、実際の証明書での検証はテストカードでしか確認できません。代替機能はカードが届くまでの期間に実装を進めるための機能です。

Q. 代替機能でスマホ用電子証明書の試験はできますか？

できます。2026年4月24日の改訂で、証明書タイプに「スマホ用電子証明書」が追加されました。

Q. 代替機能でバックチャネルログアウトは試せますか？

試せます。Sandboxの専用エンドポイントにクライアントアサーションとリフレッシュトークン、IDトークン、sub のいずれかをPOSTすると、RPのback-channel logout URLへlogoutトークンが送られます。

まとめ

テストカード代替機能は、J-LISのテストカードが届くまでの1〜2か月を、実装と異常系の確認に使えるようにする機能です。エラーパターンを選ぶだけでメンテナンス中や証明書ロックの応答を再現できるので、実機では作りにくい異常系こそ代替機能の段階で終わらせるべきです。

一方で、代替機能とテスト用マイナアプリは同時に使えず、切り替えのたびにデジタル庁への申請が要ります。代替機能で確認することとテストカードで確認することを最初に分け、切り替えは1回で済ませる計画にしてください。

当社では、デジタル認証サービスの申請対応から、代替機能を使った先行実装、J-LISテストカードの手配、テスト計画、本番接続までをお手伝いしています。デジタル認証アプリ連携の開発実務とあわせて、マイナンバーシステム導入支援をご覧ください。ご相談はお問い合わせからどうぞ。

---

この記事に関連するサービス

TodoONada株式会社では、マイナンバーカード認証を組み込んだシステム開発を行っています。

• マイナンバーシステム導入支援 — JPKI・eKYC対応の本人確認をワンストップで

導入・開発のご相談はお問い合わせからお気軽にどうぞ。検討段階のご相談も歓迎です。