OAuthリダイレクトURIの棚卸し・変更手順｜不要なコールバックを残さない運用
OAuth連携でドメイン移転、認証基盤の統合、アプリの再構築を行うとき、リダイレクトURIの変更は「新しいURLを管理画面へ追加するだけ」に見えます。しかし、同じクライアントIDを開発・検証・本番で共用していたり、古いサブドメインや一時的なプレビューURLが残っていたりすると、ログイン停止だけでなく、認可コードやトークンを不要な接続先へ送る余地を残します。
安全な変更は、クライアントIDごとに登録URI・実装・所有者・環境・実利用を棚卸しし、新旧URIを一時的に併用して認可開始からコールバック処理まで検証し、旧URIへの正規通信がなくなった証拠を確認してから削除する流れです。URIの一致条件は認可サーバーごとに細部が異なるため、管理画面の表示だけでなく、実際の認可リクエストとアプリのルーティング、プロキシやロードバランサーの挙動まで同じ変更単位で確認します。
本記事のポイント
- クライアントIDごとに登録URI、実装上のcallback、環境、所有者、実利用を照合し、管理画面だけで必要性を判断しません。
- 新URIを先に登録して認可開始からcallback、state・PKCE検証、コード交換、セッション確立まで完走してから主経路を切り替えます。
- 旧URIは正規通信ゼロと低頻度フローの移行を確認して削除し、削除後の再認証と旧hostへの残存通信まで確認します。
リダイレクトURIは認可結果の戻り先を固定する境界
リダイレクトURIは、利用者が認可を終えたあと、認可サーバーがブラウザをアプリへ戻す宛先です。OAuth 2.0の仕様であるRFC 6749は、リダイレクト先を絶対URIとし、フラグメントを含めないこと、完全なURIが登録されている場合は単純な文字列比較で照合することを定めています。OAuth 2.0 Security Best Current PracticeのRFC 9700は、ネイティブアプリのlocalhostポート番号を除き、事前登録URIとの完全一致を求めています。
この境界が曖昧だと、認可コードやアクセストークンが意図しない場所へ送られる危険があります。ワイルドカードや前方一致、転送先をクエリで自由に指定できるオープンリダイレクトは、運用を楽に見せても、認可結果の行き先を広げます。登録URIは「アプリが動くURL一覧」ではなく、「認可結果を返してよい接続先の許可リスト」として扱います。
GoogleのWebサーバー向けOAuth資料では、認可リクエストのredirect_uriは登録済みURIと正確に一致する必要があり、スキーム、文字の大文字・小文字、末尾スラッシュも一致しなければredirect_uri_mismatchになります。Microsoft Entraも、本番WebアプリではHTTPSを原則とし、不要な開発環境のURIを本番アプリ登録へ残さず、開発と本番でアプリ登録を分けることを案内しています。
クライアントID単位で登録・実装・実利用を棚卸しする
最初に作るべきものはURLの羅列ではなく、OAuthクライアントの台帳です。認可サーバー、テナントやプロジェクト、クライアントID、アプリ名、所有部門、技術責任者、環境、登録URI、実装上のコールバック、利用者範囲、最終利用、変更期限、廃止条件を結び付けます。クライアントシークレットの値そのものは台帳へ集めず、保管場所とローテーション責任だけを記録します。
管理画面の登録値だけでは不十分です。アプリの環境変数、ルーティング設定、OAuthライブラリ、API Gateway、リバースプロキシ、ロードバランサー、CDN、認証ミドルウェア、モバイル用ディープリンクを確認し、実際に認可リクエストへ入るURIと照合します。URL生成をフレームワークへ任せている場合は、X-Forwarded-Protoやhostの解釈によってhttp、内部ホスト名、別ポートが生成されないかも確認します。
| 棚卸し項目 | 確認する内容 | 根拠 | 見落としやすい例 |
|---|---|---|---|
| クライアント | 認可サーバー、テナント、クライアントID、アプリ種別 | 管理画面、構成管理、契約台帳 | 同名アプリの検証用登録、別テナント |
| 登録URI | スキーム、host、port、path、query、末尾スラッシュ | 認可サーバーの登録値 | 大文字小文字、古いサブドメイン、localhost |
| 実装 | 認可リクエスト生成、callback route、プロキシ転送 | 設定、コード、デプロイ値 | 内部URL、Preview URL、旧ルーティング |
| 実利用 | 最終認可、成功・失敗、利用者、発生環境 | 認可ログ、アプリログ、アクセスログ | 月次処理、管理者だけの連携、休眠顧客 |
| 所有と期限 | 責任者、利用目的、廃止日、次回確認日 | 申請、チケット、サービス台帳 | 退職者所有、委託先の一時環境 |
登録URIと実装が一致していても、そのURIが今も必要とは限りません。削除した環境、解約した顧客専用ドメイン、統合前のブランドドメイン、デモ用サブドメイン、短期の開発トンネルが残ることがあります。所有者が不明なURIは正規利用と推定せず、アクセスログ、DNS、証明書、デプロイ履歴、アプリ設定をたどって「継続」「期限付き保留」「削除候補」に分類します。
OAuth連携で扱うスコープや同意画面も見直す場合は、Google Workspace連携のOAuth審査とスコープ設計を確認し、URI変更と審査・スコープ変更を一度に重ねないようにします。複数の変更を同じ認可エラーとして受けると、原因の切り分けが難しくなります。
新旧URIの併用期間と切り戻し条件を先に決める
変更計画では、新しいURIをいつ追加し、アプリの送信値をいつ切り替え、旧URIをいつ削除するかを分けます。認可サーバーが複数URIを登録できるなら、原則として新URIを先に追加し、反映後にアプリを切り替えます。旧URIを編集で上書きすると、保存直後に現在のログインが止まり、独立した切り戻し経路を失うことがあります。
併用期間は一律の日数ではなく、対象となる全クライアント、利用者群、認可フロー、ブラウザ、環境が新URIを少なくとも一度通過できる期間で決めます。日常的に使うログインは当日確認できますが、管理者だけが使う再認可、月次バッチの同意更新、特定顧客のテナント、長いrefresh token寿命を持つ連携は通常ログだけでは表れません。意図的に再認証を行うか、次の利用機会まで旧URI削除を保留します。
切り戻し条件には、redirect_uri_mismatchの発生率、認可開始数に対するcallback到達数、state検証失敗、認可コード交換失敗、ログイン完了率、対象顧客への影響を含めます。新URIへのDNS・TLS・WAF・ルーティングが正常でも、callback処理でcookieやセッションが失われれば利用者は完了できません。誰がどのログで中止を決め、旧URIを送るアプリ版へ戻すかを作業前に固定します。
| 判断項目 | 合格条件 | 切り戻しの例 | 記録する証拠 |
|---|---|---|---|
| 登録反映 | 新URIが正しいクライアントIDへ完全一致で登録 | 旧URIを残したまま追加値を修正 | 登録値、変更者、時刻 |
| callback到達 | 新URIがHTTPSで応答し、正しいrouteへ届く | ルーティングを旧hostへ戻す | アクセスログ、TLS、WAFログ |
| 認可完了 | state・PKCE・コード交換・セッション確立が成功 | アプリ設定を旧URIへ戻す | 認証ログ、アプリログ、利用者結果 |
| 利用者影響 | 対象テナント・役割・ブラウザで完了 | 段階対象を縮小し旧版へ戻す | 対象表、テスト結果、問い合わせ |
| 旧URI削除 | 正規通信ゼロ、所有者承認、再認証成功 | 削除を延期し依存を追加調査 | 利用ログ、承認、削除後再試験 |
クライアントシークレットやAPIキーも同時に交換すると、コード交換の失敗がURI不一致なのか秘密情報の不一致なのか判別しにくくなります。秘密情報の更新はAPIキーの棚卸し・ローテーション手順として分離し、URI切替では現行の認証情報を固定します。SSO側の証明書更新も伴う場合は、SAML署名証明書の更新と切り戻しを別の変更窓で行います。
7ステップでリダイレクトURIを安全に切り替える
- 対象クライアントと変更範囲を確定する。認可サーバー、テナント、クライアントID、環境、利用者、所有者、現行URI、新URIを一つの変更番号へまとめます。同じ時間帯にスコープ、秘密情報、同意画面を変更しないよう凍結範囲を決めます。
- 現在値と実利用を保存する。管理画面の登録URI、アプリ設定、認可リクエスト、callback route、アクセスログ、最終成功時刻を保存します。スクリーンショットだけでなく、文字列としてスキーム・host・port・path・query・末尾スラッシュを比較できる形にします。
- 新URIの受け口を先に準備する。DNS、TLS証明書、CDN・WAF、ロードバランサー、route、cookie、CORSではなくcallback処理に必要なsame-site設定を確認します。新URIは任意URLへ再転送せず、許可したアプリ内の完了先だけへ遷移させます。
- 新URIを追加登録する。正しいクライアントIDとアプリ種別を確認し、完全なURIを追加します。本番クライアントへlocalhost、開発トンネル、共有Previewを登録しません。複数リージョンでも共通の安定したcallback入口を使えるかを検討します。
- 小さい対象から認可を完走する。新URIを送るアプリ版を限定公開し、認可開始、同意、callback到達、stateとPKCE検証、認可コード交換、セッション確立、業務画面への復帰まで確認します。既存セッションを開くだけでなく、新規ログインと再認可を行います。
- ログを監視しながら主経路を切り替える。認可サーバーのエラー、アプリのcallback到達、コード交換、WAF、プロキシ、利用者問い合わせを同じ時刻で追います。旧URIへの正規通信、未知のhost、URI不一致が残る間は削除へ進みません。
- 旧URIを削除して再試験する。全対象の新URI成功と旧URI利用ゼロを確認し、承認後に旧URIを削除します。削除後に新規ログイン、再認可、代表的なテナント、エラー時の復帰をもう一度確認し、台帳、構成図、監視、障害手順を更新します。
テストでは「認可サーバーから302が返った」だけで合格にしません。ブラウザが新URIへ到達し、アプリがstateを検証し、必要な場合はPKCEのcode verifierを使い、認可コードを正しいclient・redirect URIで交換し、利用者のセッションを確立して業務画面へ戻るまでを一つの取引として確認します。エラー時にログへ認可コード、アクセストークン、client secretを残さないことも確認します。
ドメイン変更を伴う場合は、アクセス経路の制御を一度に広げないよう注意します。IP許可範囲や条件付きアクセスも変える必要があるなら、SaaSのIP許可リスト変更管理を別の計画にし、URI切替中の接続条件を固定します。
redirect_uri_mismatchを構成要素ごとに切り分ける
URI不一致が出たら、文字列全体を見比べます。スキームがhttpかhttpsか、hostの新旧、portの有無、pathの大文字小文字、末尾スラッシュ、URLエンコード、queryの順序や有無を分解します。ブラウザの表示URLではなく、認可リクエストへ実際に入ったredirect_uriと、該当client IDに登録された値を比較します。
環境変数を直しても改善しない場合は、設定の読み込み元、デプロイ対象、キャッシュ、複数インスタンス、プロキシheaderを確認します。旧コンテナが残っている、別リージョンだけ古い値を送る、アプリがrequest hostからURIを自動生成する、認可開始とコード交換で別のURIを使うといった原因があります。エラー発生時刻、client ID、利用環境、生成URI、アプリ版を相関できるログを残します。
| 症状 | 優先して確認する点 | よくある原因 | 安全な対処 |
|---|---|---|---|
| 全利用者が即時失敗 | client ID、登録URI、送信URI | 別環境へ登録、スキーム・path不一致 | 旧URIを維持し新登録値を修正 |
| 一部環境だけ失敗 | デプロイ版、region、proxy header | 古い設定、host自動生成、port差 | 対象を縮小し設定を統一 |
| callback後に失敗 | state、PKCE、cookie、コード交換 | session喪失、交換時URI差、秘密情報差 | 認可取引全体のログを照合 |
| 旧URIに戻る | アプリ版、キャッシュ、認可開始URL | 古いフロント、ブックマーク、別client | 発生元を特定し旧URI削除を延期 |
| 未知のURIが送られる | 入力値、オープンリダイレクト、動的生成 | return URLの無制限利用 | 許可先を固定し任意転送を止める |
エラー回避のためにワイルドカードへ広げる、サブドメイン全体を許可する、任意のreturn URLへ転送する対応は避けます。RFC 9700は完全一致とオープンリダイレクトの排除を推奨しています。必要なURIを個別に登録し、環境数が多すぎる場合は、安定したcallback gatewayを設計してアプリ内の状態で復帰先を管理します。
旧URI削除後までログ・DNS・所有権を閉じる
旧URIの利用ゼロは、短時間のログ欠落だけでは証明できません。対象テナント、管理者用フロー、再認可、低頻度の利用、休眠顧客を一覧にし、テスト結果または廃止の証拠を持たせます。所有者不明のURIは無期限で残さず、調査担当、期限、補完監視、削除判定を設定します。
リダイレクトURIの変更が完了したと言えるのは、新しいURIでログインできた時ではなく、旧URIへの正規通信がゼロだと確認してから削除し、再認証まで成功した時です。
削除後は、旧hostのDNSと証明書、リバースプロキシ、アプリrouteをすぐに無条件で消すのではなく、必要な観測期間だけ到達を監視します。ただし、旧hostを新hostへ無制限に転送して認可フローを延命しないでください。認可サーバーから旧URIへの通信が残っていれば、発生したclient IDとアプリ版を特定し、正規経路を新URIへ修正します。
OAuthクライアント自体の所有者、スコープ、利用者、最終利用、秘密情報の期限も定期的に棚卸しします。Google Workspaceで外部アプリのアクセスを管理する場合は、コンテキストアウェアアクセスの段階適用と混同せず、認可クライアントの登録と利用者アクセスの制御を別々に記録します。
よくある質問
OAuthリダイレクトURIの棚卸しでは何を確認しますか？
認可サーバー、テナント、クライアントID、環境、登録URI、実装上のcallback、利用ログ、所有者、最終利用、廃止条件を確認します。管理画面だけでなく、認可リクエストへ実際に入るURIとアプリ・プロキシの設定を照合します。
ドメイン変更時に新旧リダイレクトURIをどう併用して移行しますか？
新URIのDNS・TLS・routeを先に準備し、認可サーバーへ追加登録してから、小さい対象でアプリの送信値を切り替えます。認可取引全体を検証し、旧URIへの正規通信がなくなったあとで旧登録を削除します。
redirect_uri_mismatchをどう切り分けますか？
認可リクエストのURIと登録値を、スキーム、host、port、pathの大文字小文字、末尾スラッシュ、query、エンコードに分けて比較します。該当client ID、アプリ版、region、proxy header、コード交換時のURIも確認します。
不要なコールバックURIをいつ削除しますか？
全対象が新URIで成功し、旧URIへの正規通信がゼロで、低頻度利用や管理者フローも廃止または移行済みと確認したあとです。削除後に新規ログインと再認可を再試験し、旧hostへの残存通信を監視します。
開発環境と本番環境で同じOAuthクライアントを使ってよいですか？
分けるのが安全です。Microsoft Entraの公式資料も、不要な開発環境のURIを本番アプリ登録へ露出させないため、開発と本番でアプリ登録を分ける方法を案内しています。所有者、秘密情報、スコープ、利用者範囲も環境ごとに分離しやすくなります。
旧URIを新URIへ転送すれば登録を残せますか？
恒久策にはしません。任意の転送先を受け入れる実装はオープンリダイレクトにつながり、認可コードやトークンの流出経路になり得ます。認可サーバーには新URIを正規登録し、アプリが最初から新URIを送る状態へ移行します。
仕様と製品要件を確認できる公式資料
リダイレクトURIを、認証設定の末尾にあるURL欄ではなく、認可結果の送り先を制限する境界として管理できれば、ドメイン移転やアプリ再構築でもログイン停止と不要な戻り先の残存を同時に防ぎやすくなります。登録値、実装、実利用、所有者を同じ台帳で照合し、追加・検証・削除を一つの変更として完了させてください。
