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 |
references/examples.md
View on GitHub# Examples — Connected App Troubleshooting
## Example 1 — Server-to-server integration dies on day 2
**Symptom.** Heroku worker authenticates Monday via Web Server
flow; success. Tuesday morning, every API call fails with
`invalid_grant`.
**Diagnosis.** Login History (Setup → Login History, filter by the
integration user) shows Monday's logins as Success. Tuesday's
shows "Failed: invalid_grant". The Connected App's Refresh Token
Policy is "Immediately expire refresh token after first use" —
default in older orgs.
**Fix.** Setup → Apps → Connected Apps → edit the app → OAuth
Policies → Refresh Token Policy = "Refresh token is valid until
revoked." Re-authorize the integration user (initial consent
flow). The new refresh token is captured under the new policy.
**The evidence, as it actually came back.** The client-side error
and the org-side rows, side by side — this is what gets pasted into
the diagnosis record's `error` and `evidence` fields:
```text
# 1. Client side, verbatim from the worker's log
POST https://acme.my.salesforce.com/services/oauth2/token
grant_type=refresh_token&client_id=[REDACTED]&refresh_token=[REDACTED]
HTTP/1.1 400
{"error":"invalid_grant","error_description":"expired access/refresh token"}
# 2. Org side. LoginHistory, WHERE UserId + LoginTime only.
LoginTime Status LoginSubType SourceIp
2026-09-01T08:02:11Z Success OauthWebServer 52.14.x.x
2026-09-02T09:14:03Z Failed: invalid_grant OauthRefreshToken 52.14.x.x
2026-09-02T09:19:07Z Failed: invalid_grant OauthRefreshToken 52.14.x.x
... 8 more identical rows through 2026-09-02T13:40Z
# 3. OauthToken, run as a user holding Customize Application.
AppName UserId LastUsedDate UseCount
Billing Sync JWT 005XXXXXXXXXXXXXXX 2026-09-01T08:02:11Z 1
```
Three things fall out of that block before any Setup page is
opened. The `OauthWebServer` row is Success, so pre-authorization,
the callback URL and the consumer key are all fine. Every failure
carries `LoginSubType` = `OauthRefreshToken`, so the broken half is
the renewal. And `UseCount` is 1 against a `LastUsedDate` that
matches the one Success — the grant existed and was exchanged
exactly once, which is the signature of a refresh policy that
invalidates the token at issue.
`Status` strings are whatever the org emits; the Object Reference
says only that `Status` "is either success or a reason for
failure". Read the values, do not predict them.
**Verification.** Re-run the same query after the fix and require a
Success row whose `LoginSubType` is `OauthRefreshToken`. A Success
on `OauthWebServer` alone proves nothing — that half was never
broken.
---
## Example 2 — `invalid_client_id` on a freshly-deployed app
**Symptom.** New Connected App deployed via metadata to
production. Integration starts; first call returns
`invalid_client_id`.
**Diagnosis.** Consumer Key in the integration config doesn't
match the new Connected App's actual key. Metadata deploy creates
a new Connected App record with a new key; the integration was
configured with the sandbox's key.
**Fix.** Setup → Apps → Connected Apps → click the app → click
Manage Consumer Details → copy the Consumer Key. Update the
integration's config. Restart.
---
## Example 3 — Cloud Lambda hits IP restriction
**Symptom.** AWS Lambda calling Salesforce REST API gets
`IP_RESTRICTED`. Each invocation comes from a different AWS IP.
**Diagnosis.** Connected App IP Relaxation = "Enforce IP
restrictions". Integration user's profile has a tight IP range
that doesn't include AWS's IP pool.
**Fix.** Two reasonable approaches:
- **Connected App level:** IP Relaxation = "Relax IP restrictions".
Compensate by tightening the integration user's permissions
(only what's needed) and rotating the credential.
- **Profile level:** Add AWS Lambda's IP ranges to the user's
Login IP Range. Practical only for Lambdas in fixed VPCs with
known NAT IPs; Lambda's default outbound IPs are too dynamic.
For most cloud integrations, "Relax IP restrictions" + tight user
permissions is the right trade.
---
## Example 4 — JWT Bearer first-call success, all subsequent fail
**Symptom.** JWT Bearer flow integration works for one call;
subsequent calls (with regenerated JWTs) fail with `invalid_grant`.
**Diagnosis.** Refresh tokens aren't part of JWT Bearer flow —
each call signs a fresh JWT. The "subsequent calls fail" pattern
points at:
- **Certificate expired** — check expiry date.
- **Wrong certificate** — Connected App keyed to certA, client
signing with certB.
- **`sub` claim mismatch** — must be the user's Username, not
Email.
- **`aud` claim wrong** — must be `https://login.salesforce.com`
(or test login URL for sandbox).
Test with a fresh JWT generated manually using a known-good cert
to isolate variables.
---
## Example 5 — User can't approve a Connected App
**Symptom.** User tries to authorize a Connected App via Web
Server flow; gets a Salesforce login screen, signs in, and
returns to the integration with a "OAUTH_APP_BLOCKED" error.
**Diagnosis.** Connected App's Permitted Users = "Admin approved
users are pre-authorized" + the user is not assigned via profile
or permission set.
**Fix.** Setup → Permission Sets (or Profiles) → edit the user's
permset → "Connected App Access" → check the Connected App.
Re-attempt the OAuth flow.
---
## Anti-Pattern: Hardcoding credentials in the integration
**What it looks like.** Integration code with
`consumer_key`/`consumer_secret`/`refresh_token` hardcoded.
**What goes wrong.** Credentials in source control. Rotation
requires code change + deploy. If the secret leaks, you can't
rotate it without immediate redeploy.
**Correct.** Named Credentials (Salesforce-side) or environment
variables / secret store (client-side). Rotation is a config
change.
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: 194k | Updated | Claude CodeCodex | Verified | Install |