oauth

Bare TLDs like .dev mean myapp.dev could collide with a real domain. Use a multi-segment TLD under a domain you control, so the app name stays clean and the domain structure lives in the TLD:

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

This ensures no outbound traffic reaches something you don't own. For teams, set a wildcard DNS record (*.local.yourcompany.dev -> 127.0.0.1) so every developer gets resolution without /etc/hosts, and every developer shares the same redirect URIs in the provider console.

1. Go to Google Cloud Console > Credentials
2. Create or edit an OAuth 2.0 Client ID (Web application)
3. Add the portless domain to Authorized JavaScript origins: https://myapp.dev
4. Add the callback to Authorized redirect URIs: https://myapp.dev/api/auth/callback/google

Google validates domains against the Public Suffix List. The domain must end with a recognized TLD. .localhost subdomains fail this check; .dev, .app, .com, etc. all pass.

HTTPS is required for .dev and .app (HSTS-preloaded). Portless handles this automatically with --https.

Apple Sign In does not allow localhost or IP addresses at all.

1. Go to Apple Developer > Certificates, Identifiers & Profiles
2. Register a Services ID
3. Configure Sign In with Apple, adding the portless domain as a Return URL: https://myapp.dev/api/auth/callback/apple

The domain must be a real, publicly-resolvable domain name. Since portless maps the domain to 127.0.0.1 locally, the browser resolves it but Apple's server-side validation may require the domain to resolve publicly too. If Apple rejects the domain, add a public DNS A record pointing to 127.0.0.1 for your dev subdomain.

1. Go to Azure Portal > App registrations
2. Create or edit an app registration
3. Under Authentication, add a Web redirect URI: https://myapp.dev/api/auth/callback/azure-ad

Microsoft allows http://localhost with any port for development. It also accepts .localhost subdomains in most cases. Using a custom TLD with portless is still recommended for consistency across providers.

1. Go to Meta for Developers > App Dashboard
2. Under Facebook Login > Settings, add the portless URL to Valid OAuth Redirect URIs: https://myapp.dev/api/auth/callback/facebook

Facebook requires each redirect URI to be registered exactly (no wildcards). Strict Mode (enabled by default) enforces exact matching.

1. Go to GitHub Developer Settings > OAuth Apps
2. Set Authorization callback URL: https://myapp.dev/api/auth/callback/github

GitHub is permissive with localhost and subdomains. A custom TLD is not strictly required but keeps the setup consistent.

Set NEXTAUTH_URL to match the portless domain:

NEXTAUTH_URL=https://myapp.dev

NextAuth uses this to construct callback URLs. Without it, callbacks may use localhost and cause a mismatch.

Set the callbackURL in each strategy to use the portless domain:

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

Set BASE_URL=https://myapp.dev in your environment.

Read the PORTLESS_URL environment variable that portless injects into the child process:

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

The redirect URI sent during the OAuth flow doesn't match what's registered with the provider. Check:

1. The provider's registered redirect URI matches the portless domain exactly (protocol, host, path)
2. NEXTAUTH_URL or equivalent is set to the portless URL (not localhost)
3. The proxy is running with the correct TLD (portless list to verify)

.dev and .app TLDs are HSTS-preloaded, so browsers force HTTPS. Start the proxy:

portless proxy start --tld dev

Portless defaults to HTTPS on port 443 (auto-elevates with sudo). Run portless trust to add the local CA to your system trust store and eliminate browser warnings.

Apple may require the domain to resolve publicly. Add a DNS A record for your dev subdomain pointing to 127.0.0.1:

myapp.local.yourcompany.dev  A  127.0.0.1

Or use a wildcard: *.local.yourcompany.dev A 127.0.0.1.

The auth library is constructing the callback URL from localhost instead of the portless domain. Set the appropriate environment variable:

• NextAuth: NEXTAUTH_URL=https://myapp.dev
• Auth.js v5: AUTH_URL=https://myapp.dev
• Manual: PORTLESS_URL is injected automatically; use it as the base URL