Oauth
Fix OAuth redirect and callback failures when developing locally with Portless instead of broken `.localhost` callback URLs.
Overview
oauth is an agent skill for the Build phase that configures OAuth providers to accept Portless local dev callback URLs and fix redirect_uri_mismatch errors.
Install
npx skills add https://github.com/vercel-labs/portless --skill oauthWhat is this skill?
- Explains why default Portless `.localhost` subdomains fail Google, Apple, and others versus permissive Microsoft handlin
- Recommends Portless `--tld` on real domains so callback URLs pass provider Public Suffix List checks
- Maps provider-by-provider localhost vs subdomain behavior in a comparison table
- Triggers on `redirect_uri_mismatch`, invalid redirect, and Google/Apple/Microsoft sign-in failing locally
- Focused on configuring OAuth redirect URIs for Portless local dev URLs—not production OAuth hardening alone
- Provider comparison table covers Google, Apple, Microsoft, and Facebook localhost/subdomain rules
Adoption & trust: 1.9k installs on skills.sh; 9.7k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
OAuth sign-in works in production but fails locally because Portless `.localhost` callback URLs do not match what Google, Apple, or Facebook allow.
Who is it for?
Indie devs using Portless multi-app local URLs who are wiring social or enterprise OAuth before shipping auth.
Skip if: Production-only OAuth hardening without local Portless, mobile native OAuth flows, or providers already working on plain `http://localhost` without subdomains.
When should I use this skill?
OAuth not working with portless, redirect URI mismatch, or configuring OAuth redirect URIs for Portless local dev URLs.
What do I get? / Deliverables
Redirect URIs and Portless `--tld` settings line up with each provider's rules so local authorization callbacks complete without mismatch errors.
- Provider-specific redirect URI list aligned to Portless hostnames
- Portless `--tld` configuration guidance for valid callback domains
Recommended Skills
Journey fit
OAuth provider setup for sign-in is integration work you do while building auth flows on real local domains before launch traffic. Integrations subphase covers third-party identity providers and dev proxies like Portless that must match provider redirect URI rules.
How it compares
Local-dev OAuth redirect cookbook for Portless—not a full auth library generator or generic SSO compliance checklist.
Common Questions / FAQ
Who is oauth for?
Solo builders running apps through Portless who need Google, Apple, GitHub, or similar OAuth to accept their local callback URLs.
When should I use oauth?
During Build integrations when you see redirect_uri_mismatch, invalid redirect, or provider rejections of `.localhost` subdomains while testing sign-in locally.
Is oauth safe to install?
It guides OAuth console and dev-proxy configuration; review the Security Audits panel on this page and never paste production client secrets into agent chats.
SKILL.md
READMESKILL.md - Oauth
# OAuth with Portless OAuth providers validate redirect URIs against domain rules. `.localhost` subdomains fail on most providers because they are not in the Public Suffix List or are explicitly blocked. Portless fixes this with `--tld` to serve apps on real, valid domains. ## The Problem When portless uses the default `.localhost` TLD, OAuth providers reject redirect URIs like `http://myapp.localhost:1355/callback`: | Provider | `localhost` | `.localhost` subdomains | Reason | | --------- | ----------- | ----------------------- | ------------------------------ | | Google | Allowed | Rejected | Not in their bundled PSL | | Apple | Rejected | Rejected | No localhost at all | | Microsoft | Allowed | Allowed | Permissive localhost handling | | Facebook | Allowed | Varies | Must register each URI exactly | | GitHub | Allowed | Allowed | Permissive | Google and Apple are the strictest. Microsoft and GitHub are more lenient with localhost. ## The Fix Use a valid TLD so the redirect URI passes provider validation: ```bash portless proxy start --tld dev portless myapp next dev # -> https://myapp.dev ``` Any TLD in the Public Suffix List works: `.dev`, `.app`, `.com`, `.io`, etc. ### Use a domain you own Bare TLDs like `.dev` mean `myapp.dev` could collide with a real domain. Use a subdomain of a domain you control: ```bash portless proxy start --tld dev portless myapp.local.yourcompany 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`. ## Provider Setup ### Google 1. Go to [Google Cloud Console > Credentials](https://console.cloud.google.com/apis/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 Apple Sign In does not allow `localhost` or IP addresses at all. 1. Go to [Apple Developer > Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources) 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. ### Microsoft (Entra / Azure AD) 1. Go to [Azure Portal > App registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps) 2. Create or edit an app registration 3. Under **Authentication**, add a **Web** redirect URI: `https://myapp.dev/a