OAuthコールバックをローカルでテストするには、ローカルアプリを指す公開HTTPS URLが必要です。OAuthプロバイダーは認証後、登録済みのコールバックURLへユーザーをリダイレクトします。多くのプロバイダーはHTTPSを要求しますが、素のlocalhostは追加設定なしにはそれを提供できません。
なぜOAuthのリダイレクトURIはlocalhostを弾くのか
OAuth 2.0プロバイダーはredirect_uriパラメータを登録済みURLのホワイトリストと照合します。開発中、コールバックは次のような形になります。
https://your-app.portpreview.dev/auth/callbackトンネルがなければ、http://localhost:3000/auth/callbackを登録する(一部のプロバイダーは許可するが全部ではない)か、認証を変えるたびにステージングへデプロイするかになります。localhostトンネルは、あなたのマシン上に本物のHTTPSエンドポイントを与えます。
ローカルでOAuthをテストするために必要なもの
- プロバイダーから取得したOAuthアプリの認証情報(クライアントIDとシークレット)。
- ログイン開始とコールバック処理のための認証ルートを持つローカルアプリ。
- プロバイダーのダッシュボードで許可リダイレクトURIとして登録したトンネルURL。
- 開発中にトンネルURLを指す環境変数。
手順: PortPreviewでOAuthをローカルテスト
- OAuthルートを有効にしてアプリをローカル起動します。
npx portpreview 3000を実行して公開HTTPS URLを取得します。- コールバックURL(例:
https://your-app.portpreview.dev/auth/callback)をOAuthプロバイダーの許可リダイレクトURIに追加します。 - ローカル環境を更新し、トンネルURLをベースURLとして使うようにします。
- ブラウザでOAuthフローを開始し、リダイレクトの一連の流れを完了させます。
- トークン交換、セッション作成、エラー処理を確認します。
プロバイダー別のヒント
Google OAuth
Googleは開発用にhttp://localhostを許可しますが、HTTPSトンネルでのテストはセキュアCookieフラグやmixed-contentポリシーを含む本番に近い挙動を検証します。
GitHub OAuth
GitHubはリダイレクトURIの完全一致を要求します。トンネルURLをOAuthアプリ設定に登録し、トンネルセッションが変わったら更新するか、プロバイダーが対応していれば安定したサブドメインを使いましょう。
Auth0とエンタープライズIdP
エンタープライズのID プロバイダーはHTTPSコールバックを必須とすることが多く、localhostを完全に制限する場合もあります。トンネルはローカルのSAML/OIDC統合テストの標準的な回避策です。
OAuthローカルテストでよくあるミス
- リダイレクトURIの不一致: コールバックURLは末尾スラッシュやパスの大文字小文字まで完全に一致する必要があります。
- 古いトンネルURL: セッション間でトンネルURLが変わる場合は、プロバイダーのホワイトリストを更新します。
- stateパラメータ未検証: CSRF攻撃を防ぐため、開発中でも必ず
stateパラメータを検証します。 - Cookieドメインの問題: ドメイン設定がトンネルのホスト名と衝突すると、セッションCookieが保持されないことがあります。
セキュリティ上の考慮点
OAuthコールバックは、サーバー側で交換すべき認可コードを運びます。クライアントシークレットをフロントエンドコードに露出させず、トンネルURLは本番ドメインではなく一時的な開発用エンドポイントとして扱いましょう。ベストプラクティスはlocalhostトンネルのセキュリティガイドを参照してください。
OAuthフローをチームと共有する
プロダクトやQAがソーシャルログインをテストする必要があるときは、ステージングへデプロイする代わりにトンネルURLを共有しましょう。コラボレーションのワークフローはローカル開発サーバーの共有方法を参照してください。
1つのトンネルからOAuthとWebhookのテストを効率化するには、PortPreviewのウェイトリストに登録してください。