• ノウハウ
  • |Remogu(リモグ)" />

    API連携の案件はどこまでが自分の実装?相手の仕様との境目の見極め方

    監修・編集責任者:牛尾 昭昌(株式会社LASSIC 執行役員)

    「API連携の案件で担う範囲」を示す図です。相手の仕様/自分の実装を並べています。強調しているのは自分の実装です。ここから自分が書くと添えています。

    📘 この記事でわかること

    • 使えるフローだけでなく使われないフローまで先に決まっていることと、クライアントIDやPPIDの発行元と受け手
    • シーケンス図の上でRPアプリの実装範囲が引かれていることと、署名検証やエラー処理で自分が担う部分
    • 行政機関向けと民間事業者向けで返り方が変わる場面と、つないだあとに足される仕様の変更への備え方

    仕様書を開くと、使うフローも、エラーの分け方も、返ってくる形も、すでに書かれていました。公開されているAPIにつなぐ案件で、最初に戸惑うのはここではないでしょうか。どこまでが相手の決めた範囲で、どこからが自分の実装なのか。その線が見えないまま見積もると、作るものが膨らむか、足りなくなるかのどちらかです。この記事では、デジタル庁の実装ガイドラインを読みながら、相互運用性が「自分の設計の外側」で決まる様子を確かめます。

    リモートワーク案件特化のエージェント|Remogu(株式会社LASSIC運営) API連携・バックエンドのリモート案件を、条件から探す フルリモートの案件を見る

    1. 使えるフローと使われないフローが先に決まる

    認可コードフローが土台

    デジタル庁の『デジタル認証サービス 行政機関等・民間事業者向け実装ガイドライン』は、認証と署名のプロセスを、OAuth 2.0の認可コードフローとOpenID Connectの認可コードフローに基づくものとしています。署名のプロセスだけは、クライアントクレデンシャルズフローも扱われます1。

    文中に出てくる「RP」は、Relying Partyの略です。このガイドラインでは、行政機関等や民間事業者が提供するサービスを指します1。この記事も、そのサービスの側からAPIにつなぐ立場で読んでいきます。

    そのため、フローの土台が文書の冒頭で示されているので、設計の最初の選択肢は、案件に入る前から絞られています。自分で一から組み立てる部分は、思っているより小さいかもしれません。

    使われないフローまで書かれている

    同じガイドラインは、リソースオーナーパスワードクレデンシャルズフローとインプリシットフローを、各プロセスで使わないと明記しています1。使えるものを並べるだけでなく、使われないものにも触れている点が目を引きます。

    たとえば、既存の自社システムが別のフローで動いていたとします。その場合、つなぐ前に自分の側の認証の持たせ方を見直す話になります。仕様書を読む段階で、自分のフローが対象に入るかを先に確かめたいところです。

    クライアントIDは登録時に発行される

    さらに、RPを特定するクライアントIDは、デジタル認証サービスにRPを登録したときに、デジタル庁から発行されます1。自分で決めて名乗る値ではありません。

    コードを書く前に、登録という手続きが先にあります。見積もりやスケジュールを組むときは、実装の工数とは別に、この登録を済ませるまでの段取りを数えておくと安心です。

    図1:使えるフローと使われないフロー
    使えるフローと使われないフロー 使えるもの 使われないもの OAuth 2.0 認可コードフロー OpenID Connect 認可コードフロー 署名のみ クライアント クレデンシャルズ リソースオーナー パスワード クレデンシャルズ フロー インプリシット フロー

    出典:デジタル庁『デジタル認証サービス 行政機関等・民間事業者向け実装ガイドライン』(2026年8月25日更新)をもとに作成

    では、実装の持ち場は、仕様書のどこに書かれているのでしょうか。

    2. 持ち場の線はシーケンス図の上にある

    RPアプリで実装する範囲

    ガイドラインは、シーケンス図のうち、RPが関連するリクエスト、レスポンス、検証処理等をRPアプリで実装するよう求めています1。持ち場の線は、文章の注意書きではなく、図の上に引かれています。

    具体的な場面も挙がっています。認可レスポンスが正常のときは、返却されたCSRF対策パラメータ(state)をRP側で検証するよう求められています1。state を送って終わりではなく、戻ってきた値を確かめるところまでが持ち場です。

    同じように、トークンレスポンスが正常のときは、取得した各種トークンを適切に保護し、取得したIDトークンは正当性を検証するよう求められています1。トークンを受け取る処理と、受け取ったあとの扱いが、同じ範囲に入っています。

    端末が別でも実装は増えない

    マイナアプリとRPアプリが別の端末にある場合でも、RPアプリとのAPI連携で特別な処理は必要なく、フローに差異はありません1。端末の組み合わせごとに分岐を書く必要はなさそうです。

    また、署名を始めるためのアクセストークンも、持ち場の線を引く材料になります。クライアントクレデンシャルズフローで取得するこのトークンは、有効期限内であれば利用者を跨いで利用できます1。利用者ごとに発行されるトークンとは別物なので、扱いを混ぜない設計にします。

    識別子ごとの発行元と受け手

    つなぐ側が扱う識別子は、発行する側と受け取る側が決まっています。クライアントIDはデジタル庁から発行され、PPIDはデジタル認証サービスサーバがRPへ発行し、署名対象識別コードはRPが発行して利用者が一致を確かめます。誰が出して誰が受けるのかを表に置くと、実装の責任の向きが読み取れます。

    識別子発行する側受け取る・確かめる側資料の記述
    クライアントIDデジタル庁RPRPを登録した時に発行される1
    利用者識別子(PPID)デジタル認証サービスサーバRPRPごとにユニークな識別子が発行される1
    署名対象識別コードRP利用者RP側のサイトに表示されたコードとマイナアプリのコードの一致を確認する1

    PPIDは、RPごとにユニークな識別子として発行されます。RPの側から見ると、RPの中で利用者を見分けるための値です。資料に書かれているのはここまでなので、他のRPとの関係までは決めつけずに設計します。

    署名対象識別コードを一致させる確認は、利用者の操作として書かれています。次の節では、署名の確認のうち、どこが行われてどこが行われないのかを見ていきます。

    3. 行われる検証と行われない検証の書き分け

    署名検証は結果を受け取ったあとの仕事

    署名の処理では、署名値の作成、認証パスの検証、有効期間の検証が行われます。いっぽう、署名対象データ、署名対象ハッシュ値、署名値の確認という署名検証は、行政機関向けにも民間事業者向けにも行われません1。署名トランザクションの結果を受け取ったあとに、RP側で署名検証をするよう求められています1。

    「行われること」と「行われないこと」が、同じ文書の中で並べて書かれています。署名の結果が返ってきた時点で、確認がすべて済んでいるわけではありません。返ってきた結果をどう検証するかは、つないだ側の実装に入ってきます。

    署名値の作成や認証パスの検証を誰が行うのかは、取り上げた記述には明示がありません。そのため、ここでは「行われる」「行われない」の書き分けだけを手がかりにします。実装前の打ち合わせでは、この主語をどこまで仕様書で確認できるかを、相手の窓口に尋ねておくと話が早く進みます。

    図2:署名の処理で行われることと行われないこと
    署名の処理で行われることと行われないこと 結果が返るまでに済む 受け取ってからが仕事 有効性確認 行政機関向けのみ 署名値の作成 認証パスの検証 有効期間の検証 署名検証 署名対象データ 署名対象ハッシュ値 署名値の確認

    出典:デジタル庁『デジタル認証サービス 行政機関等・民間事業者向け実装ガイドライン』(2026年8月25日更新)をもとに作成

    行政機関向けと民間事業者向けで範囲が違う

    そのうえ、署名の処理で行われる範囲は、行政機関向けと民間事業者向けとで違います。行政機関向けには署名値の作成、認証パスの検証、有効期間の検証に加えて有効性確認があり、民間事業者向けには前の3つがあります1。図の黄色い面が、行政機関向けだけの部分です。

    そして、署名検証の経路も同じではありません。民間事業者のRPアプリは、署名トランザクションの結果をプラットフォーム事業者へ連携して署名検証をします。行政機関のRPアプリは、署名用電子証明書の署名を検証します1。同じ「署名検証」という言葉でも、たどる経路が違います。

    署名対象データと署名値をJ-LIS等に提出する方式では、ハッシュ値の欠損確認等ができません。そのため、署名対象データのハッシュ値が存在することを、RP側で保証できる状態にするよう求められています1。確認できない部分の保証が、つないだ側に回ってくる例です。

    このように、案件で自分がどの区分のRPなのかによって、検証の範囲と経路が変わります。次の節では、エラーの扱いが相手の側でどう分けられているかを見ます。

    4. エラーの分け方も相手側にある

    3つのカテゴリに分類されている

    ガイドラインは、APIリクエストのあとに返却されるHTTPステータスコードを、正常ケース、異常ケース、リダイレクトケースの3つに分類しています1。エラーの分け方は、自分で考える前に、相手の側で定義されています。

    扱い方も書かれています。異常ケースに分類されるステータスコードが返却されたときは、RPアプリがエラーを制御します。リダイレクトケースのときは、レスポンスを確認し、クエリパラメータの内容に応じてエラーを制御するよう求められています1。

    302では成否が分からない

    認可エンドポイントのHTTPステータスコードは、常に302で返却されます1。302だから成功、と読むことはできません。成功か失敗かは、リダイレクト先に付く値で分かれます。

    たとえば、認可リクエストが正常に処理されたときは、認可コードをクエリパラメータに設定してリダイレクトURIへリダイレクトします。code、state、session_stateが付加されます1。

    不正や欠落などの異常があったときは、エラー内容をクエリパラメータに設定して同じくリダイレクトURIへリダイレクトします。こちらはerror、error_description、stateが付加されます1。ステータスコードだけで分岐を書くと、この2つを取り違えます。

    400・401・500・503の読み方

    ステータスコードの意味も書かれています。400はリクエストが不正の場合に返却されます。401は、一例として、アクセストークンによる認証が失敗した場合に返却されます1。401は一例として挙げられているので、ほかの原因もあり得ると考えて処理を組みます。

    一方、500はデジタル認証サービスサーバ内でエラーが発生した場合、503はデジタル認証サービスサーバがシステムメンテナンス実施中の場合に返却されます1。メンテナンス中の503は、つないだ側のエラー処理に関わります。サーバ側で異常が発生したことが分かるように、エラーを制御する側に立ちます。

    図3:ステータスコードの3つのカテゴリ
    ステータスコードの3つのカテゴリ 正常ケース ログアウト成功 200 異常ケース 400・401 500・503 リダイレクト 認可エンドポイント 302

    出典:デジタル庁『デジタル認証サービス 行政機関等・民間事業者向け実装ガイドライン』(2026年8月25日更新)をもとに作成

    相手の仕様に合わせて、エラーの分岐を切り分けた経験は、職務経歴書に書きづらい仕事です。どの線までが自分の実装だったのかは、経歴の言葉にしにくいからです。Remoguでは、経験豊富なエージェントが、これまでの経験の棚卸しからお手伝いします。

    5. 区分によって返り方が変わる

    複数署名の結果取得

    まず、複数署名の署名トランザクション開始エンドポイントでは、1回のリクエストで最大5件の署名対象データを送信できます1。上限が仕様として決まっている例です。この5件は、このエンドポイントの話であり、ほかのエンドポイントの上限ではありません。

    結果を受け取る側にも違いがあります。複数署名の署名トランザクション結果取得エンドポイントでは、民間事業者向けはJWE暗号化があり、行政機関向けは平文です1。この違いは、このエンドポイントに限った記述です。

    署名検証の範囲や経路の違いは、別の箇所に書かれています。それぞれ独立した記述なので、「民間はこう、行政はこう」と1つの法則にまとめず、個別に確かめるのが安全です。

    属性情報の取得元は2つ

    UserInfoリクエストで取得できる属性情報は、券面入力補助APのものです。署名用電子証明書に付属する4情報が必要な場合は、署名用電子証明書から取得するよう求められています1。取得元が2つあるので、どちらから何を取るのかを、実装の前に整理しておきたいところです。

    ただし、UserInfoが具体的にどの項目を返すのかは、取り上げた記述には書かれていません。項目を決め打ちせず、仕様書のレスポンスの定義を読んでから、受け取る側の設計に入ります。

    区分ごとの違いを並べる

    行政機関向けと民間事業者向けの違いは、複数署名の結果取得、署名の処理で行われる範囲、署名検証の経路の3か所で確認できます。3つは別々の箇所に書かれた記述なので、表では限定を付けて並べます。

    項目行政機関向け民間事業者向け
    複数署名の署名トランザクション結果取得エンドポイント平文1JWE暗号化あり1
    署名の処理で行われる範囲署名値の作成、認証パスの検証、有効期間の検証、有効性確認1署名値の作成、認証パスの検証、有効期間の検証1
    署名検証の経路署名用電子証明書の署名を検証1署名トランザクションの結果をプラットフォーム事業者へ連携して署名検証1

    同じAPIにつなぐ案件でも、区分が違えば返り方が変わります。案件に入る前に、自分が行政機関向けか民間事業者向けかを確認しておくと、実装の範囲を見誤りにくくなります。

    6. つないだあとも仕様は動く

    変更履歴に残る足し算

    このガイドラインは、2024年6月21日に初版が公開され、2026年8月25日までに更新が重ねられています1。つないだあとも、つなぐ先の仕様は動きます。更新の回数までは数えられませんが、初版から2年あまりで何度も更新されていることは確かです。

    2025年9月25日の更新では、認可リクエストと署名トランザクション開始リクエストのエラーに、流量制限のエラーが追加されました1。書かれているのはエラーが追加されたところまでで、制限の値や条件は取り上げた記述にありません。値を決め打ちせず、仕様書の記述が増えるたびに確認します。

    その後、2026年4月24日の更新では、複数署名(V2)エンドポイントの説明が追加されました1。版が増える形でエンドポイントが足されています。旧版がどうなるのかは、取り上げた記述には書かれていません。

    セミコロンの明記と名称の統一

    2026年8月25日の更新では、認可リクエストのstate/nonceパラメータについて、サーバ側仕様の制約によりセミコロンを含む値が利用できない旨が明記されました1。同じ更新で、認可エンドポイントとトークンエンドポイントのredirect_uriパラメータにも、同じ旨が明記されています1。

    書かれたのは「明記された」ところまでです。制約が新しくできたとまでは読み取れません。ただ、実装している側から見ると、値の作り方を見直すきっかけになります。state や nonce を生成する処理に、セミコロンが混ざらないかを確かめたい場面です。

    同じ更新では、サービス名称が「デジタル認証アプリサービス」から「デジタル認証サービス」に統一されました1。手元の設計書やログ、画面の文言に旧名称が残っていれば、直す対象です。直すかどうかは資料の指示ではなく、読み手の判断です。

    図4:初版から2026年8月までの更新
    初版から2026年8月までの更新 2024年6月 初版公開 2025年9月 流量制限の エラーを追加 2026年4月 複数署名(V2) を追加 2026年8月 セミコロンを 明記

    出典:デジタル庁『デジタル認証サービス 行政機関等・民間事業者向け実装ガイドライン』(2026年8月25日更新)をもとに作成

    更新日ごとの内容

    変更履歴に書かれた主な内容を、日付順に並べます。軽微な修正も1行として並ぶ履歴なので、ここでは本文で取り上げた更新だけを載せています。

    更新日内容
    2024年6月21日初版公開1
    2025年9月25日認可リクエストと署名トランザクション開始リクエストのエラーに流量制限のエラーを追加1
    2026年4月24日複数署名(V2)エンドポイントの説明を追加1
    2026年8月25日state/nonceとredirect_uriについて、セミコロンを含む値が利用できない旨を明記。サービス名称を「デジタル認証サービス」に統一1

    公的な機関や金融に近い領域の連携案件には、サイトに載っていないものもあります。Remoguでは、サイトに載っていない案件もあり、登録後にエージェントから希望に合うものを紹介します。仕様が動く案件でも、自分の経験が合う案件かどうかを、先に相談できます。

    設計の外側を読む力

    冒頭の問いに戻ります。どこまでが相手の決めた範囲で、どこからが自分の実装なのか。使うフローも、エラーの分け方も、署名の返り方も、自分の設計の外側にすでに書かれています。持ち場の線は、シーケンス図と変更履歴を読めば引けます。

    案件に入るときは、仕様書の更新日付と、自分の区分に当たる記述から確かめます。聞くことは一つです。どこまでが相手の仕様で、どこからが自分の実装ですか。線が引けていれば、見積りも、テストの範囲も、引き継ぎの書き方も変わります。

    7. よくある質問

    署名対象識別コードの一致は誰が確認しますか

    確認するのは利用者です。署名対象識別コードは、署名するデータを識別するためにRPが発行するコードで、RP側のサイトに表示されたコードとマイナアプリに表示されたコードが一致するかを、利用者が確かめます1。

    マイナアプリが別端末でも、実装は増えますか

    RPアプリとのAPI連携では、特別な処理は必要なく、フローに差異はありません1。端末の組み合わせで実装が分かれる形にはなっていません。

    back-channel logoutは何で決まりますか

    RP事業者申請の際に、back-channel logout URLを指定したかどうかで決まります。利用者がRPの解除、ログアウト、アカウント削除をするとき、マイナアプリは指定されたURLへリクエストを送り、指定されなかった場合はリクエストしません1。申請の内容で後の挙動が変わるので、設計だけでなく手続きの段階から確かめます。

    リクエストを受けたRPアプリは、ログアウト処理のあと、成功時に200、失敗時に400のHTTPステータスコードを返すよう求められています1。

    リモートワーク案件をお探しの方へ

    Remoguは、株式会社LASSICが運営するITエンジニア・デザイナー専門のリモートワーク案件紹介サービスです。フルリモート・ハイブリッドの案件から、スキルに合うものを探せます。

    担当する範囲は案件ごとに違います。まずは条件を見比べるところから確かめられます。

    フルリモートの案件を見る30秒で無料登録

    会員登録無料 / 案件閲覧・相談は無料

    ※公開中の案件数は時期によって変わります。記事中の案件の傾向は執筆時点のものです。

    出典・参考情報

    *1 デジタル庁「行政機関等・民間事業者向け実装ガイドライン」(2026年8月25日・2026年11月確認)