v1.0.0 to v1.1.0

+ description: "Troubleshooting Connected App OAuth flows — IP relaxation vs IP restriction, refresh token policy traps (default kills the connection on first refresh), session-revocation semantics, the OAuth error-code catalog (`invalid_grant`, `invalid_client_id`, `unsupported_grant_type`), per-user vs admin-pre-approved flows, and the user-policy check (Connected App must be assigned to the user via profile / permset). Covers the Login History debug trail. NOT for designing the OAuth flow itself — use integration/oauth-flows-and-connected-apps. NOT for a SAML / SSO login failure — use security/sso-saml-troubleshooting. Trigger keywords: 'invalid_grant', 'OAUTH_APP_BLOCKED', 'redirect_uri_mismatch', 'LoginHistory Status', 'LoginSubType', 'OauthRefreshToken', 'ForwardedForIp', 'SetupAuditTrail connected app', 'refreshTokenPolicy zero', 'isSecretRequiredForRefreshToken', 'works once then fails', 'diagnosis record'."

+ - "integration worked yesterday and now returns invalid_grant"

+ - "which login history status means the connected app blocked the user"

+ - "trace an oauth error string back to the connected app setting that caused it"

+ - "prove which setup change broke the integration authentication"

+ - "reproduce a connected app oauth failure safely in a sandbox"

+ - "client only shows a generic oauth error and I need the salesforce side evidence"

+ version: 1.1.0

+ updated: 2026-09-04

+ `integration/oauth-flows-and-connected-apps`, and authoring the app

+ file itself is `admin/connected-apps-and-auth`. SAML / SSO debugging

+ is `security/sso-saml-troubleshooting`. This skill is for the

+ ## Questions to Ask Before Configuring

+

+ Ask these before changing a single Connected App field. A failing OAuth flow has one true cause and

+ four plausible ones; every question below eliminates a branch of the decision table using evidence

+ that already exists in the org.

+

+ | Ask | Why it matters | What a good answer adds |

+ |---|---|---|

+ | "Paste the response body, not your summary of it." | The token endpoint's `error` string and the HTTP status are different signals. REST API documents 401 as "The session ID or OAuth token used has expired or is invalid", and 403 as a refusal to check permissions against | The row of the runbook table to start on, and whether this is an auth failure or a post-auth authorization failure |

+ | "Which grant is failing — the first authorization, or a later refresh?" | `LoginSubType` separates `OauthWebServer` from `OauthRefreshToken`, so Salesforce already recorded which half broke | Whether to inspect `oauthConfig` (initial exchange) or `oauthPolicy` (renewal) — they are different fields |

+ | "Did this ever work, and when did it last succeed?" | A working-then-broken integration points at a policy change or a token lifetime, not at configuration; a never-worked one points at pre-authorization or callback URL | The `SetupAuditTrail` window to search and whether a `LoginHistory` success row exists to compare against |

+ | "Who is the authenticating user, by Id?" | `UserId` is one of only twelve filterable `LoginHistory` fields, so it is the anchor of every evidence query | A query that compiles, instead of one rejected on `WHERE Application` or `WHERE Status` |

+ | "Can the caller enumerate its egress IPs, and does anything proxy the request?" | `ipRelaxation` `ENFORCE` is evaluated against the org's IP restrictions, and `SourceIp` records the first proxy rather than the origin | Whether the IP branch is even testable from Salesforce-side evidence (gotcha 12) |

+ | "Who will run the verification query, and do they hold Customize Application?" | `OauthToken` shows an under-privileged caller only their own rows, so a clean result can be an artefact of the reviewer's permissions | A named runner for the evidence step, so an empty result means something |

+ | "Is there a sandbox with the same policy values, and has My Domain been deployed in it?" | The reproduction is only valid if the login host and the policy block match; callback URLs are host-specific | A safe place to test the fix before touching the production app |

+

+ What a proper configuration adds over just doing it: the fix is attached to a written diagnosis

+ record — symptom, verbatim error, the evidence rows that ruled the other causes out, and a

+ root-cause category — so the next person who sees `invalid_grant` on this app does not restart the

+ same five-branch search from zero.

+

+ ---

+

+ UNVERIFIED (2026-09-04): the token-endpoint `error` strings below are not

+ documented in this skill's source set — the REST API Developer Guide covers

+ the HTTP layer (401 as an expired or invalid session/OAuth token, 403 as a

+ refusal to check permissions against) but not the OAuth vocabulary. Treat each

+ string as a hint and confirm the diagnosis with the evidence columns in

+ `references/metadata-examples.md` § 1, which are grounded.

+

+ In metadata the field is `refreshTokenPolicy` on

+ `ConnectedAppOauthPolicy`, it is Required, and its documented

+ values are `zero`, `infinite`, `specific_lifetime:number:HOURS|DAYS|MONTHS`

+ and `specific_inactivity:number:HOURS|DAYS|MONTHS`

+ (Metadata API Developer Guide, `ConnectedAppOauthPolicy`).

+ Correction to the row above, grounded: `infinite` is the documented

+ default — "the refresh token is used indefinitely, unless revoked by

+ the user or Salesforce admin. Default setting." The Setup UI in an

+ older org may have presented a different pre-selected option.

+ UNVERIFIED (2026-09-04): the claim that older orgs defaulted to

+ "Immediately expire" is not in the Metadata API guide, which

+ documents `infinite` as the default; treat it as a field observation

+ and read the deployed value rather than assuming either default.

+ `zero` is the value that produces the classic "works once, then

+ dies" report: "The refresh token is invalid immediately. The user

+ can use the current session (access token) already issued, but

+ can't obtain a new session when the access token expires." The

+ failure therefore surfaces one access-token lifetime *after* the

+ change that caused it — which is why the `SetupAuditTrail` search

+ window has to start before the first failure, not at it.

+

+ **Right answer for server-to-server:** an explicit value you chose.

+ `infinite` only when a revocation runbook exists;

+ `specific_inactivity:` when the integration has a predictable

+ cadence. The policy-vs-kill-switch distinction and the revoke

+ procedure belong to `admin/integration-admin-connected-apps`.

+

+ `Status` is the fastest discriminator, because it "[d]isplays the

+ status of the attempted login. Status is either success or a reason

+ for failure" — a sentence the Object Reference does not expand into

+ a value list, so read the strings your org actually emits rather

+ than matching against a remembered catalog.

+

+ `LoginSubType` is the field that names the grant: `OauthWebServer`,

+ `OauthRefreshToken`, `OauthClientCredentials`, `OauthUserAgent`,

+ `OauthTokenExchange`, `OAuthDevice`, `OauthUsernamePassword` and the

+ hybrid variants. It tells you which half of the dance failed before

+ you open a single Setup page.

+

+ Neither is filterable. `LoginHistory` publishes a closed list of

+ twelve filterable fields, and `Status`, `LoginSubType` and

+ `SourceIp` are outside it (gotcha 11). Anchor every evidence query

+ on `UserId` and `LoginTime`, then read the rest off the returned

+ rows. The ready-made queries are in `references/metadata-examples.md`.

+

+ 1. **Open a diagnosis record and paste the raw failure into it.** Copy the YAML skeleton from

+ `templates/connected-app-diagnosis-record.yaml`. Fill `symptom`, `error` (verbatim response body,

+ secrets replaced with `[REDACTED]`), `app`, `user-id` and `first-failure`. An error you have

+ paraphrased is an error you have already started guessing about.

+ 2. **Run the evidence query set in `references/metadata-examples.md` § 2 and record every result.**

+ `LoginHistory` for the user over the failure window, `OauthToken` for the app, `SetupAuditTrail`

+ for recent Setup changes. Each `evidence` entry needs both a `query` and a `result` — including

+ "0 rows", which is itself a finding. Run the `OauthToken` query as a user holding Customize

+ Application, or the empty result proves nothing.

+ 3. **Walk the runbook table in `references/metadata-examples.md` § 1 top to bottom.** It goes

+ symptom → error string → the `LoginHistory` `Status` / `LoginSubType` to look for → the exact

+ `ConnectedApp` XML path to inspect → the fix. Stop at the first row whose evidence column matches

+ what step 2 actually returned; assign the matching `root-cause` category.

+ 4. **Inspect the deployed policy, not the Setup screen.** Retrieve the app and compare its

+ `oauthConfig` / `oauthPolicy` against the annotated excerpt in

+ `references/metadata-examples.md` § 3. `admin/connected-apps-and-auth` owns the full file; this

+ step only reads the four fields the runbook named.

+ 5. **Reproduce in a sandbox before changing production** using the procedure in

+ `references/metadata-examples.md` § 4 — matching policy block, the sandbox login host, and the

+ sandbox-suffixed username. Skip this only when the diagnosis is a user assignment, which is

+ reversible in one click.

+ 6. **Apply the fix, re-authorize from a clean state, and re-run the same queries from step 2.**

+ Paste the post-fix rows into `verified-by`. A refresh-policy fix is not verified until a

+ `LoginSubType = OauthRefreshToken` row returns Success, because the initial authorization would

+ have succeeded either way.

+ 7. **Lint the record and the metadata.**

+ `python3 scripts/check_connected_app_troubleshooting.py --manifest-dir force-app/main/default`

+ fails on an incomplete diagnosis record and on the three policy combinations that produce the

+ classic failures. Commit the record next to the change.

+ 1. **`refreshTokenPolicy` `zero` works for one access-token lifetime, then dies** — and the documented default is `infinite`, not "immediately expire". (See `references/gotchas.md` § 1.)

+ 8. **`LoginSubType` names the failing grant but cannot anchor a `WHERE` clause** — it is outside the twelve filterable fields. (See `references/gotchas.md` § 11.)

+ 9. **`ForwardedForIp` is never populated for an OAuth login**, so the documented way to see past a proxy does not exist for this flow. (See `references/gotchas.md` § 12.)

+ 10. **`SetupAuditTrail.Section` and `Display` are not filterable** — the "who changed the policy" query has to filter on `Action`. (See `references/gotchas.md` § 13.)

+ 11. **Secret-required is two independent switches**, so an app can pass its first token exchange and fail every refresh. (See `references/gotchas.md` § 14.)

+ ## Reference Files

+

+ | File | Read it when |

+ |---|---|

+ | `references/metadata-examples.md` | You are running a live diagnosis — the symptom-to-fix runbook table, the three evidence queries, the `oauthPolicy` excerpt to compare against, the sandbox reproduction procedure, and the diagnosis-record shape all live here |

+ | `references/gotchas.md` | An evidence query returned an answer you don't trust, a fix didn't take, or the failure timestamp doesn't line up with the change that caused it |

+ | `references/examples.md` | You want the worked narratives end to end, including a completed diagnosis record |

+ | `references/well-architected.md` | You need the Security / Reliability framing for a post-incident write-up, or the official source behind a claim here |

+ | `references/llm-anti-patterns.md` | You are reviewing AI-generated OAuth triage advice before acting on it |

+ | `templates/connected-app-troubleshooting-template.md` | At the start of a triage, to capture the symptom, flow, user and evidence in one place |

+ | `templates/connected-app-diagnosis-record.yaml` | The record you fill during the triage and commit alongside the fix — linted by the checker |

+ | `scripts/check_connected_app_troubleshooting.py` | Before deploying a policy fix, and again once the diagnosis record is written |

+

+ ---

+

+ - `integration/oauth-flows-and-connected-apps` — choosing and designing the OAuth grant flow; this skill is the troubleshooting half.

+ - `admin/connected-apps-and-auth` — authoring the full `connectedApp` / External Client App / Named Credential file, and the artefact decision.

+ - `admin/integration-admin-connected-apps` — the operations half: hardening, revocation, key and secret rotation, monitoring, and the periodic review.

+ - `security/oauth-token-management` — token lifecycle and revocation semantics beyond a single failing flow.

+ - `security/login-forensics` — when the question is "who logged in and from where", not "why did this grant fail".

+ - `security/sso-saml-troubleshooting` — SAML-specific debugging (different runtime, different evidence).

+ - `apex/apex-jwt-bearer-flow` — JWT-specific setup including certificate management.

+ - `integration/named-credentials-setup` — External Credentials and Named Credentials, which interact with these OAuth flows.

+ - `admin/org-setup-and-configuration` — My Domain, trusted IP ranges and session settings, which the login host and the IP branch both depend on.