OAuth リダイレクトでよくある URL Encoding のバグ

OAuth リダイレクトの問題は、認証バッジを付けた URL encoding の問題であることがよくあります。identity provider が redirect_uri が一致しないと言ったり、callback で parameter が落ちたり、ネストした return URL がログイン後に壊れたりします。

これらのバグの多くは、エンコード漏れ、二重エンコード、間違った境界のエンコードの 3 つのどれかから生じます。

ローカルワークフロー全体は API デバッグの pillar ガイド を参照してください。query 構造が不明な場合は、エンコードを変更する前に URL query string の分解と再構築 を読んでください。

redirect URI は完全一致が必要

identity provider は通常 redirect URI を厳密に比較します。次は異なる値になり得ます。

• https://app.example.com/callback
• https://app.example.com/callback/
• https://app.example.com/callback?source=login
• https%3A%2F%2Fapp.example.com%2Fcallback

登録値、authorization リクエスト、アプリケーションの callback ルートは一致している必要があります。

ネスト URL には特別な注意が必要

よくあるパターンは return target 付きの login URL です。

/login?return_to=/billing?tab=invoices&page=2

ネストした ? と & は外側の login query ではなく return URL に属します。エンコードしないと、外側の parser が誤って分割します。

より安全な形式はネスト値をエンコードします。

/login?return_to=%2Fbilling%3Ftab%3Dinvoices%26page%3D2

URL Encoder / Decoder で各境界を個別に確認します。authorize URL が 1 本の長い文字列の場合は、まず URL Parser で key と value を分割し、コンポーネントを 1 つずつ encode または decode します。

二重エンコードに注意

二重エンコードは、コードで 1 回エンコードした値を、フレームワークや HTTP クライアントがさらに 1 回エンコードするときに起こります。

兆候には次が含まれます。

• %3A を期待したのに %253A がある。
• %2F を期待したのに %252F がある。
• provider が表示する redirect URI に、1 回 decode しても percent sign が残っている。

1 レイヤーずつ decode します。2 回 decode して初めて読めるなら、2 回目の encode がどこで起きているかを特定します。

スペースと plus sign は常に同じではない

application/x-www-form-urlencoded では、+ がスペースを表すことが多いです。一般的な URL percent encoding では、スペースは %20 で plus sign はリテラルの plus sign です。

OAuth parameter は form post、URL、ログ、SDK ヘルパーを経由することが多いです。どの encoding モードを使っているか明示してください。

デバッグチェックリスト

callback が失敗するとき:

• 登録済み redirect URI とリクエスト値を比較する。
• リクエスト値を正確に 1 回 decode する。
• ネスト URL が単一 parameter value としてエンコードされているか確認する。
• %25 を探す（% 自体がエンコードされたサイン）。
• state と nonce の値が往復を生き延びるか確認する。

OAuth は複雑になり得ますが、各 URL レイヤーを分離すれば、多くのリダイレクトバグはシンプルになります。

ツールチェーン全体が必要な場合は API デバッグワークフロー概要 に戻ってください。