Proposal: allow localhost redirect URIs in the localhost dev exception in the OAuth spec

[axfelix]

This is a proposal carrying on discussion from this closed PR: bluesky-social/atproto-website#709. There is also a corresponding open issue, bluesky-social/atproto-website#699.

Currently, http://127.0.0.1 is treated differently from http://localhost for client development, per the OAuth spec in https://atproto.com/specs/oauth#localhost-client-development.

This proposal is an opportunity to provide feedback on this change before the team considers implementing it upstream.

What is being proposed

Relax the "Localhost Client Development" exception in the OAuth spec so that redirect_uri values may use the hostname localhost in addition to the loopback IP literals 127.0.0.1 and [::1], and add http://localhost/ to the default redirect_uri values. The client_id rules are unchanged (origin remains exactly http://localhost), as are all production redirect URI rules.

Why

Requiring the app under development to be served from http://127.0.0.1:PORT instead of http://localhost:PORT is a recurring developer-experience trap:

• Every mainstream dev server (Next.js, Vite, etc.) advertises http://localhost:PORT, so that is what developers open.
• OAuth session state (DPoP private key, PKCE verifier, state) is kept in origin-scoped browser storage. When the callback lands on 127.0.0.1 — a different origin — that state is invisible, and login fails in a way that is hard to diagnose. Both addresses serve the app fine until the login step, which makes the failure look like an SDK bug.
• The official web OAuth tutorial currently has to document a workaround for exactly this ("This avoids cookie issues that arise from localhost vs 127.0.0.1 mismatches").

Security rationale

The loopback-literal preference comes from RFC 8252 §8.3, which is guidance (NOT RECOMMENDED, not prohibited) aimed at native apps binding a local port listener, out of concern that localhost could resolve to a non-loopback address on misconfigured systems. That concern does not carry marginal weight in this flow:

• The application under development is already served from and browsed at the localhost origin, so the OAuth callback depends on localhost name resolution no more than the application itself does. The IP-literal rule only relocates the callback; it cannot protect an app the developer is browsing at localhost. This argument requires no assumptions about browser behavior.
• Browsers that treat http://localhost as a secure context do so on the condition that localhost names are guaranteed to resolve to the loopback interface (the Secure Contexts spec makes trust conditional on exactly this guarantee; current Chrome, Firefox ≥84, and Safari all provide it).
• The interception threat RFC 8252 worries about is neutralized by this profile: PAR binds both the PKCE code_verifier and the DPoP key to the session at flow start, and the token endpoint requires both — so an intercepted authorization code cannot be redeemed (verified against the reference @atproto/oauth-provider implementation, which rejects token requests whose DPoP key does not match the JKT captured at PAR). An attacker who can exfiltrate those secrets from the app has already won regardless of redirect hostname.
• The other RFC 8252 concern — accidentally listening on non-loopback interfaces — is a property of what the dev server binds to, not of the hostname in the redirect URI, so the current rule does not mitigate it.
• This exception is development-only by construction, and remains optional for Authorization Servers.

Most major OAuth providers (GitHub, Google, Auth0, Okta) accept http://localhost redirect URIs for development.

Implementation

• Reference implementation (@atproto/oauth-provider) would need to accept localhost redirect URIs for the exception.

[fatfingers23]

I'm all for it! It's a small thing that comes up a lot in development experience, and since the whole 127.0.0.1 thing is for dev experience I say make it easier.

[WaveringAna]

can i chime into bring up something semi unrelated yet makes the dev experience around oauth painful? oauth scope cache and the did cache for atproto services on the reference pds only bust cache every 30 minutes, and theres no manual way to bust the cache. what this means is that unless if you edit the db, you are stuck with scopes/a did for 30 minutes you are unable to change if you misconfigured it/want to change it/want to add more scopes which is really frustrating unless you use an account on an entirely separate pds.

[matthieusieben]

Feel free to open dedicated issues for these.

[WaveringAna]

i have played these games before..

[mackuba]

Yup, makes perfect sense! I was just very confused about this 2 days ago :)

Not sure if that makes sense, but as I understand the client_id has to be localhost without port, right? Could that one be relaxed too so they can be the same?

[matthieusieben]

The localhost in there has nothing to do with the redirect uris. It is merely a special token that allows the AS to detect that the CIMD should not be fetched, while ensuring that the format of the client_id is a URL (as for non local client ids).

Some have been arguing that this should be avoided altogether, and that devs should use actually published documents in dev. For example, @ThisIsMissEm developped a small service that allows devs to easily setup metadata documents for dev purposes.

For these reasons, I don't think we should allow other values in there too.

[ThisIsMissEm]

Yeah, that's https://cimd-service.fly.dev — I'm deploying a more stable one soon.

[alyraffauf]

seems like a lot of people are running into this lately, sounds like a good idea!