リダイレクトURLの設定

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

リダイレクトURI（コールバックURL）は、ユーザーが同意画面で「許可する」を押した後に認可コードを受け取る URL です。開発者アプリに1つ登録し、/oauth/authorize に送る redirect_uri とトークン交換時の redirect_uri を、その値と完全に一致させます。この記事では、登録のルール、環境ごとの分け方、変更の手順、よくあるエラーを説明します。

リダイレクトURIの役割

アプリがユーザーを認可URLへ送ります（redirect_uri を含めて）。
レシートローラーは redirect_uri が登録値と一致するか確かめます。一致しなければ認可コードを出さず、400 invalid_redirect_uri を返します。
ユーザーが許可すると、その URI に ?code=…&state=… を付けてリダイレクトします。
アプリは同じ redirect_uri を付けて code をトークンに交換します。違う値だと 401 invalid_grant になります。

登録された URI にしかコードを送らないことで、第三者がコードを横取りするのを防いでいます。

登録のルール

項目	ルール
登録できる数	1アプリにつき1つ
比較の方法	文字列の完全一致。大文字・小文字、末尾のスラッシュ、ポート番号も区別します（`/callback` と `/callback/` は別物）。
ワイルドカード	使えません（完全一致のため）。
クエリ文字列・フラグメント	フラグメント（`#` 以降）は含めないでください。クエリ文字列は使えます。その場合 `code` と `state` は `&` で続けて付きます。リクエストごとに変わる値は、URI ではなく `state` で渡します。
スキーム	本番では `https://` の URL を使ってください。

開発環境と本番環境の分け方

1つのアプリに登録できる URI は1つなので、開発・ステージング・本番で URI が違う場合は環境ごとにアプリを作成します。アプリが分かれていれば、クライアントIDとシークレットも環境ごとに別になり、本番のシークレットを開発者全員に配る必要がなくなります。

マイアプリ (prod)  → https://app.example.com/oauth/callback
マイアプリ (stg)   → https://staging.example.com/oauth/callback
マイアプリ (dev)   → http://localhost:3000/oauth/callback

本番用のアプリに http://localhost の URI を登録しないでください。

登録・変更の手順

ビジネスアカウント詳細のメニューから「開発者アプリ」を開き、対象のアプリを開きます。
「編集」を押し、「リダイレクトURI」を入力して保存します。

変更は次の認可リクエストからすぐに反映されます。編集できるのはビジネスアカウントのオーナーです。すでに発行された認可コードは、認可リクエストで使った redirect_uri で交換します。

稼働中のアプリで URI を変えるとき

URI は1つしか持てないため、保存した瞬間に古い URI での認可は invalid_redirect_uri になります。次のどちらかで進めてください。

新しい URI を使うアプリの設定を用意しておき、URI の保存とアプリのデプロイを続けて行う（利用の少ない時間帯に）。
新しい URI で別のアプリを作成し、動作を確認してから切り替え、古いアプリを削除する。この場合、ユーザーには新しいアプリでもう一度認可してもらう必要があります。

state パラメーターの使い方

遷移元ページなどの動的な値は、リダイレクトURIに埋め込まず state に入れてください。state は認可後にそのまま返ってきます。

// 認可リクエスト
https://receiptroller.io/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
  &scope=store.products.read
  &state=RANDOM_VALUE

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

state は CSRF 対策にもなります。リクエストごとにランダムな値を作ってセッションに保存し、コールバックで一致を確認してください。

よくあるエラー

症状	原因	対処
認可URLで 400 `invalid_redirect_uri`	`redirect_uri` が登録値と一致しない、`redirect_uri` を付けていない、またはアプリに URI が登録されていない	大文字・小文字、末尾のスラッシュ、ポート番号まで登録値と同じにします。
トークン交換で 401 `invalid_grant`（`redirect_uri does not match the authorization request`）	交換時の `redirect_uri` が認可リクエストと違う	認可リクエストと同じ値を送ります。
許可した後、ページが開けない	登録した URI のサーバーに届かない（DNS・証明書・サーバー停止など）	その URI をブラウザで直接開いて確認します。