リダイレクトURLの設定

OAuth リダイレクトURI アプリ登録セキュリティ

この記事の対象
レシートローラーの開発者ポータルでアプリを登録する開発者向けです。OAuth 2.0 認可コードフローで使うリダイレクトURI（コールバックURL）の設定方法と注意点を説明します。

リダイレクトURIは、OAuth 認可フローでユーザーが認可画面で「許可」した後に、認可コードを受け取るためのURLです。アプリ登録時に登録したURIと、実際に /oauth/authorize へリクエストを送るときに指定する redirect_uri が完全一致している必要があります。

リダイレクトURIの役割

OAuth 認可コードフローでは、次の順番で値が受け渡されます。

アプリがユーザーをレシートローラーの認可画面に遷移させる（redirect_uri を含めて）
ユーザーが「許可」を押す
レシートローラーが、登録済みリダイレクトURIに code パラメータ付きでリダイレクトする
アプリは code を使ってアクセストークンを取得する

登録されていないURIや、登録値と1文字でも違うURIを redirect_uri に指定すると、レシートローラーは認可コードを返さず invalid_redirect_uri エラーになります。これは攻撃者がコードを盗むことを防ぐための仕組みです。

登録ルール

項目	ルール
スキーム	`https://` 必須（本番） `http://localhost` および `http://127.0.0.1` は開発時のみ許可
ホスト	完全修飾ドメイン名。ワイルドカード（`*.example.com`）は不可
パス	任意。`/oauth/callback` や `/auth/rr/callback` など慣例的なパスを推奨
クエリ・フラグメント	登録URIには含めない。動的パラメータは `state` で渡してください
登録できる本数	1アプリあたり最大10件
大文字・小文字	区別されます。`/Callback` と `/callback` は別物
末尾スラッシュ	区別されます。`/callback` と `/callback/` は別物

開発・本番環境の使い分け

多くのアプリは「開発」「ステージング」「本番」と複数の環境を持ちます。レシートローラーでは、1つのアプリに複数のリダイレクトURIを登録できるので、環境ごとにURIを追加するのが基本です。

推奨パターン

https://app.example.com/oauth/callback           ← 本番
https://staging.example.com/oauth/callback       ← ステージング
http://localhost:3000/oauth/callback             ← 開発（手元）

環境ごとにアプリを分けることもできますが、本番アプリと開発アプリは必ず分けることを強く推奨します。理由は次のとおりです。

本番のクライアントシークレットを開発者全員に配布する必要がなくなる
開発中の不具合で本番ユーザーのトークンを誤って失効させる事故を防げる
User系スコープの審査が本番アプリだけで済む

注意：本番アプリには http://localhost を登録しないでください。シークレットが漏えいした際、攻撃者が手元の偽サイトに認可コードを誘導できてしまいます。

登録手順

開発者ポータル → アプリ一覧 → 対象アプリを開く
「リダイレクトURI」セクションの「＋追加」ボタンをクリック
URIを入力して「保存」
必要な環境分繰り返す

登録したURIは即時反映されます。アプリの再ビルドや再デプロイは不要です。

state パラメータの活用

動的な情報（遷移元ページのURL、ユーザーID、CSRF対策トークンなど）は、リダイレクトURIに直接埋め込むのではなく state パラメータに渡してください。state はレシートローラーが認可後にそのまま返すので、コールバック側で復元できます。

// 認可リクエスト
https://receiptroller.io/oauth/authorize
  ?client_id=xxx
  &redirect_uri=https://app.example.com/oauth/callback
  &state=eyJjc3JmIjoiYWJjMTIzIiwicmV0dXJuIjoiL2Rhc2hib2FyZCJ9
  &scope=store.read
  &response_type=code

// コールバック
https://app.example.com/oauth/callback
  ?code=...
  &state=eyJjc3JmIjoiYWJjMTIzIiwicmV0dXJuIjoiL2Rhc2hib2FyZCJ9

state は CSRF 対策としても必須です。リクエスト時に生成したランダム値をセッションに保存し、コールバック時に一致を確認してください。

よくあるエラー

エラー	原因	対処
`invalid_redirect_uri`	登録済みURIと一致しない	大文字小文字・末尾スラッシュ・ポート番号まで含めて完全一致しているか確認
`redirect_uri_required`	認可リクエストに `redirect_uri` が含まれていない	クエリパラメータに必ず付与する
`insecure_redirect_uri`	本番アプリに `http://`（localhost以外）を登録しようとした	`https://` に変更する
認可後にコールバックされない	登録URIのホストにDNS/証明書エラー	ブラウザで直接そのURIを開いて到達確認

変更時の注意

稼働中アプリのリダイレクトURIを変更する場合は、次の順序を守ってください。

新URIを追加（旧URIは残したまま）
アプリのコード／環境変数を新URIに切り替えてデプロイ
新URIで動作確認
旧URIを削除

古いURIをいきなり削除すると、デプロイ完了までの間に発生した認可リクエストが全て失敗します。