OAuth Redirect And Domain Strategy
Every OAuth failure in Salesforce that is not a permission problem is a string
matching problem. Three strings have to line up, and they are owned by three
different parties:
| String |
Owned by |
Where it lives |
| Login host |
The org |
https://<mydomain>.my.salesforce.com, or https://<mydomain>--<sandbox>.sandbox.my.salesforce.com |
redirect_uri |
The client |
Sent on the authorize request and again on the token request |
| Callback URL |
The connected app |
ConnectedAppOauthConfig.callbackUrl — "It's the OAuth redirect_uri" |
The failure mode is binary and leaves almost no Salesforce-side evidence: a browser
redirect carrying an error parameter, no debug log, and often nothing in Login
History because no login occurred. Client-side logging is the primary diagnostic and
has to exist before you need it.
Before Starting
Enumerate the applications, not the orgs. One logical application deployed to
four environments is one connected app with four callback lines — not four
connected apps.
Know that the consumer key is immutable. "In API version 32.0 and later, you
can set this field's value only during creation. After you define and save the
value, it can't be edited." It must also be globally unique.
Establish whether clients can send PKCE before requiring it. Turning it on is
a hard cut: "any authorization code flow variations that don't implement it fail."
Inventory what lives outside the org if a domain change is coming — IdP
configuration, webhook registrations, partner allow-lists. Their owners' lead time
is the cutover's real critical path.
Core Concepts
callbackUrl is a newline-separated list
A Connected App accepts multiple callback URLs, newline-separated (\r
programmatically), and matches the app's requested URL against the list at run time —
quoted in full in references/gotchas.md.
<callbackUrl>https://orders.example.com/oauth/callback
https://uat.orders.example.com/oauth/callback
https://dev1.orders.example.com/oauth/callback</callbackUrl>
A comma makes the whole field one malformed string and breaks every environment
on the app at once.
Matching is exact
There is no documented wildcard, prefix, or normalisation behaviour. Treat the match
as byte-identical. All of these are different strings from
https://orders.example.com/oauth/callback:
https://orders.example.com/oauth/callback/ trailing slash
https://Orders.example.com/oauth/callback host or path case
http://orders.example.com/oauth/callback scheme
https://orders.example.com:443/oauth/callback explicit default port
https://orders.example.com/oauth/callback?src=a library-appended query parameter
Use the protocol's state parameter for anything that needs round-tripping — it is
carried separately and is not part of the redirect URI.
PKCE defaults are opposites
| Type |
isPkceRequired default |
ConnectedApp |
false — "The default value is false." (API 59.0 and later) |
ExternalClientApplication |
true — "If set to true (default) Proof Key for Code for Exchange (PKCE) is required for OAuth integration." |
A client that worked against a connected app can fail immediately against an
External Client App, having changed nothing. Write the field explicitly on both.
Platform guidance: "we always recommend implementing PKCE for public clients. We
also strongly recommend that you implement PKCE for private clients."
Login host formats
| Environment |
Host |
| Production |
https://<mydomain>.my.salesforce.com |
| Sandbox |
https://<mydomain>--<sandboxname>.sandbox.my.salesforce.com |
login.salesforce.com and test.salesforce.com still work but redirect to My
Domain, and client libraries differ in how cleanly they follow that redirect. Point
clients directly at My Domain, from an environment variable — never a build-time
constant, because the sandbox name is part of the host.
Common Patterns
Pattern A — one app, every environment
One connected app definition deployed to every org, with every environment's
callback as a line in callbackUrl. One consumer key, one rotation, and the client
varies only SF_LOGIN_URL. Full metadata in
references/examples.md, Example 1.
Pattern B — separate apps where token isolation matters
Where production and sandbox tokens must be non-interchangeable, keep separate apps
— and write down the extra cost: N immutable keys, N rotations, N reconfigurations
after every sandbox refresh. Make it a decision, not an accident of the Setup UI.
Pattern C — the redirect matrix
One row per connected app per environment: login host, redirect_uri the client
sends, the stored callback line it matches, the owner, and the date it was last
verified. This is the artifact that turns a domain change from discovery into
review.
Pattern D — PKCE rollout in the safe order
Verify on the wire that the client sends code_challenge on authorize and
code_verifier on token exchange, then set isPkceRequired to true. Never the
reverse — there is no warning period.
Decision Guidance
| Situation |
Approach |
| One application, several environments |
One connected app, several callbackUrl lines |
| Production and sandbox tokens must not be interchangeable |
Separate apps, with the rotation cost documented |
| Client is a mobile or single-page app |
isPkceRequired true; the client cannot hold a secret |
| Client library is old and unverified |
Verify PKCE on the wire before requiring it |
| Redirect mismatch, configuration looks correct |
Log the client's redirect_uri on both requests and diff against the stored line |
| Several callback paths needed |
One line each — no wildcard, no prefix |
| Developers need local flow |
localhost in non-production apps only; if production, record why and a removal date |
| Enhanced domains cutover |
Redirect matrix + repo sweep + external-system owner list |
| Sandbox refresh scheduled |
Redeploy connected apps from source; reissue secrets; confirm SF_LOGIN_URL |
Recommended Workflow
- Build the redirect matrix: one row per connected app per environment, with
login host, client
redirect_uri, stored callback line, owner, and verification
date. Include integrations with no redirect (client credentials) so the inventory
is complete.
- Consolidate to one connected app per application where token isolation is not
required, moving every environment's callback into
callbackUrl as its own line.
- Set
isPkceRequired explicitly on every app of both types, after verifying
on the wire that clients send code_challenge and code_verifier.
- Move the login host into an environment variable in every client, pointing at
the org's My Domain rather than
login.salesforce.com.
- Sweep for hardcoded hosts across Apex, LWC, metadata, email templates, and
then across systems outside the org — IdP configuration, webhook registrations,
partner allow-lists — assigning an owner and a confirmation date to each external
item.
- Rehearse any domain change in a full sandbox, exercising every row of the
matrix rather than one representative flow.
- Add connected app redeployment and secret reissue to the sandbox post-refresh
runbook, and add "no
localhost callbacks in production" to the release
checklist.
Review Checklist
Salesforce-Specific Gotchas
Full detail with quotes in references/gotchas.md.
- The consumer key is immutable after save and must be globally unique.
- Callback matching is exact, and the near-misses are invisible on screen.
- Multiple callbacks are newline-separated, not comma-separated — a comma
breaks every environment at once.
isPkceRequired defaults are opposites between ConnectedApp (false) and
ExternalClientApplication (true).
login.salesforce.com works, then redirects, and libraries differ in how they
handle it.
- A sandbox refresh changes the host and can destroy the app.
localhost callbacks outlive development and nothing ever fails to flag them.
- The domain change is only partly inside Salesforce.
- The failure leaves no Salesforce-side evidence.
- One app per environment multiplies rotation and breaks on refresh.
Output Artifacts
| Artifact |
Description |
| Redirect matrix |
App × environment, with login host, client redirect_uri, stored callback line, owner, and verification date |
| Consolidated connected app metadata |
One definition per application with newline-separated callbacks and explicit isPkceRequired |
| Client configuration standard |
SF_LOGIN_URL as an environment variable, with the per-environment values and who sets them |
| Hardcoded-host sweep results |
Repo grep output plus the external-system inventory with owners and confirmation dates |
| Cutover rehearsal record |
Which matrix rows were exercised in the sandbox, and the result of each |
Related Skills
security/connected-app-security-policies — the session, refresh token, and IP
policies that sit alongside the OAuth configuration on the same app
security/oauth-token-management — token lifetime, refresh rotation, and
revocation once the flow works
security/api-only-user-hardening — the identity a client-credentials app binds
to, which has no redirect at all
devops/sandbox-refresh-and-templates — the refresh event that invalidates
connected apps and login hosts
1---2name: oauth-redirect-and-domain-strategy3description: "Design Connected App OAuth callback URLs, My Domain naming, Enhanced Domains cutover, and cross-environment redirect handling. Trigger keywords: oauth redirect uri, connected app callback, my domain, enhanced domains, sandbox url change. NOT for end-user login flow UX, Experience Cloud branding, or SAML-only SSO configuration — use admin/connected-app-troubleshooting."4category: security5salesforce-version: "Spring '25+"6well-architected-pillars:7 - Security8 - Reliability9 - Operational Excellence10triggers:11 - "configure oauth callback url"12 - "connected app redirect uri"13 - "enhanced domains cutover"14 - "my domain strategy"15 - "sandbox oauth endpoint"16tags:17 - security18 - oauth19 - my-domain20 - connected-app21inputs:22 - List of Connected Apps and their client redirect URIs23 - Environment inventory (prod, UAT, dev sandboxes)24 - Current My Domain / Enhanced Domains state25outputs:26 - Redirect URI matrix per Connected App per environment27 - Enhanced Domains cutover plan28 - Login host strategy (login.salesforce.com vs My Domain)29dependencies: []30version: 1.0.131author: Pranav Nagrecha32updated: 2026-08-1433metadata:34 source: https://skillmd.com/skills/pranavnagrecha/oauth-redirect-and-domain-strategy35---3637# OAuth Redirect And Domain Strategy3839Every OAuth failure in Salesforce that is not a permission problem is a **string40matching** problem. Three strings have to line up, and they are owned by three41different parties:4243| String | Owned by | Where it lives |44|---|---|---|45| **Login host** | The org | `https://<mydomain>.my.salesforce.com`, or `https://<mydomain>--<sandbox>.sandbox.my.salesforce.com` |46| **`redirect_uri`** | The client | Sent on the authorize request and again on the token request |47| **Callback URL** | The connected app | `ConnectedAppOauthConfig.callbackUrl` — "It's the OAuth `redirect_uri`" |4849The failure mode is binary and leaves almost no Salesforce-side evidence: a browser50redirect carrying an error parameter, no debug log, and often nothing in Login51History because no login occurred. Client-side logging is the primary diagnostic and52has to exist before you need it.5354---5556## Before Starting57581. **Enumerate the applications, not the orgs.** One logical application deployed to59 four environments is one connected app with four callback lines — not four60 connected apps.61622. **Know that the consumer key is immutable.** "In API version 32.0 and later, you63 can set this field's value only during creation. After you define and save the64 value, it can't be edited." It must also be globally unique.65663. **Establish whether clients can send PKCE** before requiring it. Turning it on is67 a hard cut: "any authorization code flow variations that don't implement it fail."68694. **Inventory what lives outside the org** if a domain change is coming — IdP70 configuration, webhook registrations, partner allow-lists. Their owners' lead time71 is the cutover's real critical path.7273---7475## Core Concepts7677### `callbackUrl` is a newline-separated list7879A Connected App accepts multiple callback URLs, newline-separated (`\r`80programmatically), and matches the app's requested URL against the list at run time —81quoted in full in [`references/gotchas.md`](references/gotchas.md).8283```xml84<callbackUrl>https://orders.example.com/oauth/callback85https://uat.orders.example.com/oauth/callback86https://dev1.orders.example.com/oauth/callback</callbackUrl>87```8889A comma makes the whole field one malformed string and breaks **every** environment90on the app at once.9192### Matching is exact9394There is no documented wildcard, prefix, or normalisation behaviour. Treat the match95as byte-identical. All of these are different strings from96`https://orders.example.com/oauth/callback`:9798```text99https://orders.example.com/oauth/callback/ trailing slash100https://Orders.example.com/oauth/callback host or path case101http://orders.example.com/oauth/callback scheme102https://orders.example.com:443/oauth/callback explicit default port103https://orders.example.com/oauth/callback?src=a library-appended query parameter104```105106Use the protocol's `state` parameter for anything that needs round-tripping — it is107carried separately and is not part of the redirect URI.108109### PKCE defaults are opposites110111| Type | `isPkceRequired` default |112|---|---|113| `ConnectedApp` | **`false`** — "The default value is `false`." (API 59.0 and later) |114| `ExternalClientApplication` | **`true`** — "If set to `true` (default) Proof Key for Code for Exchange (PKCE) is required for OAuth integration." |115116A client that worked against a connected app can fail immediately against an117External Client App, having changed nothing. Write the field explicitly on both.118119Platform guidance: "we always recommend implementing PKCE for public clients. We120also strongly recommend that you implement PKCE for private clients."121122### Login host formats123124| Environment | Host |125|---|---|126| Production | `https://<mydomain>.my.salesforce.com` |127| Sandbox | `https://<mydomain>--<sandboxname>.sandbox.my.salesforce.com` |128129`login.salesforce.com` and `test.salesforce.com` still work but redirect to My130Domain, and client libraries differ in how cleanly they follow that redirect. Point131clients directly at My Domain, from an environment variable — never a build-time132constant, because the sandbox name is part of the host.133134---135136## Common Patterns137138### Pattern A — one app, every environment139140One connected app definition deployed to every org, with every environment's141callback as a line in `callbackUrl`. One consumer key, one rotation, and the client142varies only `SF_LOGIN_URL`. Full metadata in143[`references/examples.md`](references/examples.md), Example 1.144145### Pattern B — separate apps where token isolation matters146147Where production and sandbox tokens must be non-interchangeable, keep separate apps148— and write down the extra cost: N immutable keys, N rotations, N reconfigurations149after every sandbox refresh. Make it a decision, not an accident of the Setup UI.150151### Pattern C — the redirect matrix152153One row per connected app per environment: login host, `redirect_uri` the client154sends, the stored callback line it matches, the owner, and the date it was last155verified. This is the artifact that turns a domain change from discovery into156review.157158### Pattern D — PKCE rollout in the safe order159160Verify on the wire that the client sends `code_challenge` on authorize and161`code_verifier` on token exchange, *then* set `isPkceRequired` to `true`. Never the162reverse — there is no warning period.163164---165166## Decision Guidance167168| Situation | Approach |169|---|---|170| One application, several environments | One connected app, several `callbackUrl` lines |171| Production and sandbox tokens must not be interchangeable | Separate apps, with the rotation cost documented |172| Client is a mobile or single-page app | `isPkceRequired` `true`; the client cannot hold a secret |173| Client library is old and unverified | Verify PKCE on the wire before requiring it |174| Redirect mismatch, configuration looks correct | Log the client's `redirect_uri` on both requests and diff against the stored line |175| Several callback paths needed | One line each — no wildcard, no prefix |176| Developers need local flow | `localhost` in non-production apps only; if production, record why and a removal date |177| Enhanced domains cutover | Redirect matrix + repo sweep + external-system owner list |178| Sandbox refresh scheduled | Redeploy connected apps from source; reissue secrets; confirm `SF_LOGIN_URL` |179180---181182## Recommended Workflow1831841. **Build the redirect matrix**: one row per connected app per environment, with185 login host, client `redirect_uri`, stored callback line, owner, and verification186 date. Include integrations with no redirect (client credentials) so the inventory187 is complete.1882. **Consolidate to one connected app per application** where token isolation is not189 required, moving every environment's callback into `callbackUrl` as its own line.1903. **Set `isPkceRequired` explicitly** on every app of both types, after verifying191 on the wire that clients send `code_challenge` and `code_verifier`.1924. **Move the login host into an environment variable** in every client, pointing at193 the org's My Domain rather than `login.salesforce.com`.1945. **Sweep for hardcoded hosts** across Apex, LWC, metadata, email templates, and195 then across systems outside the org — IdP configuration, webhook registrations,196 partner allow-lists — assigning an owner and a confirmation date to each external197 item.1986. **Rehearse any domain change in a full sandbox**, exercising every row of the199 matrix rather than one representative flow.2007. **Add connected app redeployment and secret reissue** to the sandbox post-refresh201 runbook, and add "no `localhost` callbacks in production" to the release202 checklist.203204---205206## Review Checklist207208- [ ] One connected app per application, unless token isolation is a written decision209- [ ] Every environment's callback present as its own newline-separated line210- [ ] No commas, no wildcards, no prefixes in `callbackUrl`211- [ ] No trailing whitespace on any stored callback value212- [ ] `isPkceRequired` written explicitly on every connected app and External Client App213- [ ] PKCE verified on the wire before being required214- [ ] Client login host is an environment variable pointing at My Domain215- [ ] No `salesforce.com` string literals in client code216- [ ] No `localhost` callbacks in production apps, or a recorded reason and removal date217- [ ] Client-side logging of the authorize and token requests exists before it is needed218- [ ] Redirect matrix has an owner and a verification date for every row219- [ ] External systems (IdP, webhooks, partner allow-lists) enumerated with owners220- [ ] Sandbox post-refresh runbook includes connected app redeploy and secret reissue221222---223224## Salesforce-Specific Gotchas225226Full detail with quotes in [`references/gotchas.md`](references/gotchas.md).2272281. **The consumer key is immutable after save** and must be globally unique.2292. **Callback matching is exact**, and the near-misses are invisible on screen.2303. **Multiple callbacks are newline-separated**, not comma-separated — a comma231 breaks every environment at once.2324. **`isPkceRequired` defaults are opposites** between `ConnectedApp` (`false`) and233 `ExternalClientApplication` (`true`).2345. **`login.salesforce.com` works, then redirects**, and libraries differ in how they235 handle it.2366. **A sandbox refresh changes the host and can destroy the app.**2377. **`localhost` callbacks outlive development** and nothing ever fails to flag them.2388. **The domain change is only partly inside Salesforce.**2399. **The failure leaves no Salesforce-side evidence.**24010. **One app per environment multiplies rotation and breaks on refresh.**241242---243244## Output Artifacts245246| Artifact | Description |247|---|---|248| Redirect matrix | App × environment, with login host, client `redirect_uri`, stored callback line, owner, and verification date |249| Consolidated connected app metadata | One definition per application with newline-separated callbacks and explicit `isPkceRequired` |250| Client configuration standard | `SF_LOGIN_URL` as an environment variable, with the per-environment values and who sets them |251| Hardcoded-host sweep results | Repo grep output plus the external-system inventory with owners and confirmation dates |252| Cutover rehearsal record | Which matrix rows were exercised in the sandbox, and the result of each |253254---255256## Related Skills257258- `security/connected-app-security-policies` — the session, refresh token, and IP259 policies that sit alongside the OAuth configuration on the same app260- `security/oauth-token-management` — token lifetime, refresh rotation, and261 revocation once the flow works262- `security/api-only-user-hardening` — the identity a client-credentials app binds263 to, which has no redirect at all264- `devops/sandbox-refresh-and-templates` — the refresh event that invalidates265 connected apps and login hosts