OAuth with Portless

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が実際のドメインと衝突する可能性があります。自身が管理するドメインのサブドメインを使用してください：

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

これにより、所有していないサーバーへのアウトバウンドトラフィックがないことが確実になります。チームの場合は、ワイルドカードDNSレコード（*.local.yourcompany.dev -> 127.0.0.1）を設定して、すべての開発者が/etc/hosts変更なしで解決できるようにします。

プロバイダー設定

Google

1. Google Cloud Console > Credentialsに移動
2. OAuth 2.0 クライアントID（Webアプリケーション）を作成または編集
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は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の下にValid OAuth Redirect URIsにPortless URLを追加：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をPortlessドメインと一致するように設定：

NEXTAUTH_URL=https://myapp.dev

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

Passport.js

各ストラテジーのcallbackURLをPortlessドメインを使用するように設定：

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がプロバイダーに登録されているものと一致しません。次を確認してください：

1. プロバイダーの登録済みリダイレクトURIがPortlessドメインと正確に一致している（プロトコル、ホスト、パス）
2. NEXTAUTH_URLまたはそれに相当するものがPortless 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に移動

認証ライブラリがPortlessドメインの代わりに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を参照してください。