Your relying party's redirect_uri must cover local, preview and production — how do you manage that set, and where does the post-login deep link ride?

## The same code runs in four places and only one of them is production The dashboard's callback is a single route, but the URL that reaches it differs per deployment: a `localhost` address on a laptop, a per-branch preview host, a staging host, and `https://fleet.example.com/auth/callback` in production. The provider compares the `redirect_uri` on an authorization request against what was registered for that client, as a fixed value. Why the comparison is exact is the specification's argument; what it leaves a server author is an operational problem — a registered set that has to cover every place the code runs, and that has to change whenever a deployment target does. ## One registration per environment beats one registration with a long list | Approach | Reach of a leaked client secret | Who changes the list | Fit | |---|---|---|---| | One registration holding every environment's callback | A non-production secret is a production secret | Anyone with provider administration | One environment, or a very small team | | One registration per environment, one or two callbacks each | Contained to that environment | The owner of that environment | The default worth arguing for | The argument that wins the second is not tidiness. With a single registration, a client secret sitting in a developer's `.env` file authenticates as the same client as production, and the registered list has to include a `localhost` callback that production's own registration would never carry. Separate registrations also let the non-production ones point at a non-production tenant of the provider, populated with test staff rather than real depot supervisors. ## Build the value from configuration, not from the inbound request The most common way this fails in production has nothing to do with the provider's rules. A relying party that constructs its own callback URL from the request it is handling — taking scheme, host and port from what arrived — gets the scheme wrong the moment a TLS-terminating reverse proxy sits in front: the proxy speaks HTTPS outward and plain HTTP inward, so the application builds `http://fleet.example.com/auth/callback` and the provider rejects it against the registered `https://` value. It works on a laptop, where nothing terminates TLS, and breaks on the first deployment behind a proxy. Two fixes, and they are not equivalent: 1. **Put the callback URL in configuration** — one value per environment — and use exactly that string in the authorization request and again in the token request. This is the answer. 2. **Teach the application to trust the proxy's forwarded headers** (`X-Forwarded-Proto` and its companions) so the reconstructed URL comes out right. It works, but it makes the callback URL depend on a header, and therefore on whether the proxy in front is one you control. The same value has to be presented at the token request, byte for byte. A trailing slash, a capitalised host, an added default port — each is a different string, and each produces a failed exchange whose error reads like a credential problem, which sends people looking at the client secret instead of at the URL. ## Preview deployments are the case with no clean answer Ephemeral per-branch hosts cannot be pre-registered, because each is a name nobody knew yesterday. Every option is a compromise: - Route every preview build through **one stable preview hostname** that is registered once, and let the parked login record carry which build the user came from. - Give previews **their own long-lived registration** at a non-production tenant, listing a handful of stable hosts that previews share. - Do not federate in previews at all and run a **local stub issuer** instead — a legitimate choice, whose mechanics belong with testing federated integrations rather than here. What does not work is asking for a wildcard host in the registered value. Most providers do not offer one, and a provider that does is offering to weaken the comparison your entire callback path rests on. ## Where the post-login deep link rides A supervisor opens a shared link to one vehicle, is not signed in, and should land on that vehicle after authenticating. That destination is ordinary application state, and the registration deliberately does not carry it: - **Not appended to the `redirect_uri`.** The registered value is compared as a fixed string, so adding a destination parameter either fails that comparison or forces you to register a variant per destination. - **Not carried as the `state` parameter's payload.** `state` is the key to your server-side record. Making it a bag of application data gives you either a parameter the browser can rewrite — so whoever crafts the link decides where your users land once they are authenticated — or a signed blob that has outgrown what a request parameter should hold. - **In the parked login record**, written when the authorization request is built and read at the callback. Validate it on the way out, not only on the way in: accept a path on your own origin, reject anything carrying a scheme, reject a value beginning with a double slash, re-check after decoding, and fall back to a default landing page rather than failing the login. Nothing in the registered callback set says anything about this final redirect, so nothing but your own check governs it.