PranavNagrecha/AwesomeSalesforceSkills / skills/admin/connected-app-troubleshooting
connected-app-troubleshooting
VerifiedTroubleshooting 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'.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 24.3 KB |
| references/examples.md | markdown | 5.8 KB |
| references/gotchas.md | markdown | 13.2 KB |
| references/llm-anti-patterns.md | markdown | 6.6 KB |
| references/metadata-examples.md | markdown | 19.8 KB |
| references/well-architected.md | markdown | 5.5 KB |
| scripts/check_connected_app_troubleshooting.pyexecutable | script | 20.3 KB |
| templates/connected-app-diagnosis-record.yaml | config | 4.1 KB |
| templates/connected-app-troubleshooting-template.md | markdown | 3.6 KB |
templates/connected-app-troubleshooting-template.md
View on GitHub# Connected App Troubleshooting — Triage Worksheet
Fill this at the start of a triage, before opening Setup. It captures the answers to
`SKILL.md` § Questions to Ask, so the runbook in `references/metadata-examples.md` § 1
can be walked with evidence instead of guesses. The machine-readable output of the same
triage is `templates/connected-app-diagnosis-record.yaml`.
## Scope
**Skill:** `connected-app-troubleshooting`
| Field | Value |
|---|---|
| Connected app label | |
| Org (production / sandbox name) | |
| Authenticating user Id (`005…`) | |
| Reported by / when | |
| Is this app still in production use? | |
## 1. The raw failure
Paste the response body verbatim. Replace consumer keys, secrets and tokens with `[REDACTED]`.
Do not paraphrase — the `error` string and the HTTP status are two different signals.
```text
```
| Field | Value |
|---|---|
| HTTP status | |
| Token-endpoint `error` value | |
| First observed failure (UTC) | |
| Last known success (UTC), if any | |
## 2. Which half of the dance
| Ask | Answer |
|---|---|
| Grant flow the client is using | |
| Initial authorization or renewal? (`LoginSubType` from § 2a) | |
| Did it ever work? | |
| Does it fail for all users or one? | |
If the answer to "did it ever work" is no, start at runbook rows 1–3.
If yes, start at rows 4–8.
If `LoginHistory` shows Success while the integration fails, go straight to row 11.
## 3. Evidence gathered
| Query | Run by | Holds Customize Application? | Rows returned | What it rules out |
|---|---|---|---|---|
| § 2a `LoginHistory` | | n/a | | |
| § 2b `OauthToken` | | | | |
| § 2c `SetupAuditTrail` | | n/a | | |
A zero-row result is a finding, not a blank. Record it.
An empty `OauthToken` result from a runner without Customize Application rules nothing out.
## 4. Policy fields inspected
Retrieved from the failing org, not read off the Setup screen.
| Field | Deployed value | Expected value | Matches? |
|---|---|---|---|
| `oauthConfig/isAdminApproved` | | | |
| `permissionSetName` / `profileName` | | | |
| `oauthConfig/callbackUrl` | | | |
| `oauthConfig/isSecretRequiredForRefreshToken` | | | |
| `oauthConfig/isConsumerSecretOptional` | | | |
| `oauthConfig/isRefreshTokenRotationEnabled` | | | |
| `oauthPolicy/refreshTokenPolicy` | | | |
| `oauthPolicy/ipRelaxation` | | | |
## 5. Diagnosis
| Field | Value |
|---|---|
| Runbook row matched | |
| `root-cause` category | |
| Causes explicitly ruled out, and by which evidence | |
| Confidence, and what would raise it | |
## 6. Fix and verification
| Field | Value |
|---|---|
| Change applied | |
| Reproduced in sandbox first? (yes / no / not applicable, with reason) | |
| Re-authorization performed? | |
| Verification query result (must include the previously failing `LoginSubType`) | |
| Follow-up owner, if the fix is a workaround | |
## 7. Checklist
- [ ] Error captured verbatim, secrets redacted.
- [ ] All three evidence queries run and results recorded, including zero-row results.
- [ ] `OauthToken` query run by someone holding Customize Application.
- [ ] `SetupAuditTrail` window starts before the first observed failure.
- [ ] Deployed policy read from a retrieve, not from Setup.
- [ ] Runbook row matched to evidence, not to the error string alone.
- [ ] Sandbox reproduction done, or its omission justified above.
- [ ] Verification shows Success on the grant type that was failing.
- [ ] `connected-app-diagnosis-record.yaml` filled and linted by the checker.
## 8. Notes
Record anything that did not fit a runbook row, and anything that would have shortened the
triage. A symptom the table cannot express is the strongest signal that the table needs a row.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |