mcpField
O
oauth

oauth

github.com/vercel-labs開発12.8k3.0k 回インストール3 日前に更新
リポジトリ

oauth について

Portless を使う開発者向けの OAuth ガイドです。有効なローカルドメインでリダイレクト URI の検証に対応し、主要プロバイダーや認証ライブラリの設定方法を説明します。

主な機能

  1. 01Portless で有効な TLD を設定
  2. 02プロバイダーのリダイレクト URI 登録
  3. 03認証ライブラリのコールバック URL 設定
  4. 04リダイレクト不一致の調査

活用シーン

  1. 01ローカルアプリでの Google OAuth テスト
  2. 02Apple Sign In のローカル開発
  3. 03チーム環境でのコールバック URL 統一

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/vercel-labs/portless --skill oauth

インストール後、Claude Code で/oauthを入力して読み込まれたか確認します。

詳細

Portless での OAuth

OAuth プロバイダーは、ドメインのルールに基づいてリダイレクト URI を検証します。.localhost サブドメインは、Public Suffix List に含まれていないか、明示的にブロックされているため、ほとんどのプロバイダーで拒否されます。Portless は --tld を使い、実在する有効なドメインでアプリを公開することで、この問題を解決します。

問題

Portless がデフォルトの .localhost TLD を使うと、OAuth プロバイダーは http://myapp.localhost:1355/callback のようなリダイレクト URI を拒否します。

プロバイダーlocalhost.localhost サブドメイン理由
Google許可拒否同梱の PSL に含まれていない
Apple拒否拒否localhost は一切許可されない
Microsoft許可許可localhost の扱いが寛容
Facebook許可場合によるURI をそれぞれ正確に登録する必要がある
GitHub許可許可寛容

Google と Apple が最も厳格です。Microsoft と GitHub は localhost に対してより寛容です。

解決方法

有効な TLD を使うと、リダイレクト URI がプロバイダーの検証を通過します。

portless proxy start --tld dev
portless myapp next dev
# -> https://myapp.dev

Public Suffix List に含まれる TLD であれば、.dev、.app、.com、.io など、どれでも使えます。

所有しているドメインを使う

.dev のような単一の TLD では、myapp.dev が実在するドメインと衝突する可能性があります。管理しているドメイン配下で複数のセグメントからなる TLD を使えば、アプリ名を簡潔に保ちながら、ドメイン構造を TLD 側に持たせられます。

portless proxy start --tld local.yourcompany.dev
portless myapp next dev
# -> https://myapp.local.yourcompany.dev

これにより、所有していない場所へ外向きの通信が送信されなくなります。チームで使う場合は、ワイルドカード DNS レコード（*.local.yourcompany.dev -> 127.0.0.1）を設定すれば、各開発者は /etc/hosts を使わずに名前解決でき、全員がプロバイダーのコンソールで同じリダイレクト URI を使えます。

プロバイダーの設定

Google
  1. Google Cloud Console > Credentials に移動します
  2. OAuth 2.0 クライアント ID（ウェブアプリケーション）を作成するか、編集します
  3. Authorized JavaScript origins に Portless のドメインを追加します：https://myapp.dev
  4. Authorized redirect URIs にコールバックを追加します：https://myapp.dev/api/auth/callback/google

Google は Public Suffix List に基づいてドメインを検証します。ドメインは、認識されている TLD で終わる必要があります。.localhost サブドメインはこの検証に失敗しますが、.dev、.app、.com などはすべて通過します。

.dev と .app では HTTPS が必須です（HSTS が事前設定されています）。Portless は --https によってこれを自動的に処理します。

Apple

Apple の「Sign In with Apple」では、localhost と IP アドレスは一切許可されません。

  1. Apple Developer > Certificates, Identifiers & Profiles に移動します
  2. Services ID を登録します
  3. 「Sign In with Apple」を設定し、Portless のドメインを Return URL として追加します：https://myapp.dev/api/auth/callback/apple

ドメインには、実在し、パブリックに名前解決できるドメイン名を指定する必要があります。Portless はローカルでドメインを 127.0.0.1 に割り当てるため、ブラウザーでは名前解決できますが、Apple 側のサーバーによる検証では、ドメインもパブリックに名前解決できる必要がある場合があります。Apple がドメインを拒否する場合は、開発用サブドメインを 127.0.0.1 に向けるパブリック DNS A レコードを追加してください。

Microsoft（Entra / Azure AD）
  1. Azure Portal > App registrations に移動します
  2. アプリ登録を新規作成するか、既存のものを編集します
  3. Authentication で、Web リダイレクト URI を追加します：https://myapp.dev/api/auth/callback/azure-ad

Microsoft は、開発用途で任意のポートを使う http://localhost を許可しています。また、ほとんどの場合 .localhost サブドメインも受け入れます。プロバイダー間で一貫性を保つため、Portless ではカスタム TLD を使うことを引き続き推奨します。

Facebook（Meta）
  1. Meta for Developers > App Dashboard にアクセスします
  2. Facebook Login > Settings で、ポートレス URL を Valid OAuth Redirect URIs に追加します：https://myapp.dev/api/auth/callback/facebook

Facebook では、リダイレクト URI をそれぞれ正確に登録する必要があります（ワイルドカードは使用できません）。デフォルトで有効になっている Strict Mode により、完全一致が適用されます。

GitHub
  1. GitHub Developer Settings > OAuth Apps にアクセスします
  2. Authorization callback URL を設定します：https://myapp.dev/api/auth/callback/github

GitHub は localhost とサブドメインについては柔軟に対応します。カスタム TLD は必須ではありませんが、設定を統一できます。

認証ライブラリの設定

NextAuth / Auth.js

NEXTAUTH_URL をポートレスドメインに合わせて設定します：

NEXTAUTH_URL=https://myapp.dev

NextAuth はこれを使ってコールバック URL を構築します。設定しないと、コールバックで localhost が使われ、不一致が発生することがあります。

Passport.js

各ストラテジーの callbackURL にポートレスドメインを設定します：

new GoogleStrategy({
  clientID: process.env.GOOGLE_CLIENT_ID,
  clientSecret: process.env.GOOGLE_CLIENT_SECRET,
  callbackURL: process.env.BASE_URL + "/auth/google/callback",
});

環境変数に BASE_URL=https://myapp.dev を設定します。

汎用／手動

portless が子プロセスに挿入する PORTLESS_URL 環境変数を読み取ります：

const baseUrl = process.env.PORTLESS_URL || "http://localhost:3000";
const callbackUrl = `${baseUrl}/auth/callback`;

トラブルシューティング

「redirect_uri_mismatch」または「invalid redirect URI」

OAuth フロー中に送信されたリダイレクト URI が、プロバイダーに登録された URI と一致していません。次を確認してください：

  1. プロバイダーに登録したリダイレクト URI が、ポートレスドメインと完全に一致している（プロトコル、ホスト、パス）
  2. NEXTAUTH_URL または同等の変数が、ポートレス URL（localhost ではなく）に設定されている
  3. プロキシが正しい TLD で実行されている（portless list で確認）
プロバイダーが HTTPS を要求する

.dev と .app の TLD は HSTS プリロード済みのため、ブラウザーは HTTPS を強制します。プロキシを起動します：

portless proxy start --tld dev

Portless はデフォルトでポート 443 の HTTPS を使用します（sudo で自動的に権限を昇格します）。portless trust を実行してローカル CA をシステムの信頼ストアに追加すると、ブラウザーの警告が表示されなくなります。

Apple がドメインを拒否する

Apple は、ドメインがパブリックに名前解決できることを要求する場合があります。開発用サブドメインに対して、127.0.0.1 を指す DNS A レコードを追加します：

myapp.local.yourcompany.dev  A  127.0.0.1

または、ワイルドカードを使用します：*.local.yourcompany.dev A 127.0.0.1。

サインイン後のコールバックが誤った URL に向かう

認証ライブラリがポートレスドメインではなく localhost からコールバック URL を構築しています。適切な環境変数を設定します：

  • NextAuth：NEXTAUTH_URL=https://myapp.dev
  • Auth.js v5：AUTH_URL=https://myapp.dev
  • 手動：PORTLESS_URL は自動的に挿入されます。ベース URL として使用してください

例

--tld dev を使用した Next.js + NextAuth + Google OAuth の完全な動作例については、examples/google-oauth を参照してください。

コメント

Markdown 対応