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/llm-anti-patterns.md
View on GitHub# LLM Anti-Patterns — Connected App Troubleshooting
Mistakes AI assistants make when triaging Connected App OAuth
issues.
---
## Anti-Pattern 1: "Just retry" advice for `invalid_grant`
**What the LLM generates.** "Refresh tokens sometimes fail; add a
retry loop."
**Why it happens.** Generic API-error advice.
**Correct pattern.** `invalid_grant` after a previous success
points at refresh token policy. Diagnose via Login History and
fix the policy, not the client retry logic.
**Detection hint.** Any OAuth-error advice with "add retry"
without checking Login History first is missing the diagnosis.
---
## Anti-Pattern 2: Recommending Username-Password OAuth flow for new code
**What the LLM generates.** "Use the username-password OAuth
flow with the user's credentials and your Consumer Key/Secret."
**Why it happens.** Older training data; flow is heavily
documented historically.
**Correct pattern.** Username-Password is deprecated for new
integrations. Use JWT Bearer (server-to-server) or Web Server
flow (interactive).
**Detection hint.** Any new-integration recipe using
`grant_type=password` is dated.
---
## Anti-Pattern 3: Hardcoding credentials in the integration
**What the LLM generates.**
```python
CONSUMER_KEY = "3MV..."
CONSUMER_SECRET = "1234..."
REFRESH_TOKEN = "5Aep..."
```
**Why it happens.** Config-management is implicit.
**Correct pattern.** Environment variables / secret store
(client-side) or Named Credentials (Salesforce-side). Rotation
becomes a config change, not a code change.
**Detection hint.** Any integration recipe with literal
credentials is a security smell.
---
## Anti-Pattern 4: Not checking Login History before guessing
**What the LLM generates.** "Try regenerating the Consumer
Secret" or "Check your refresh token" without Login History
investigation.
**Why it happens.** Assumes the client error is the only
signal.
**Correct pattern.** Login History (Setup → Login History or
SOQL on `LoginHistory`) often shows clearer cause: "User not
assigned to app", "Restricted IP", "Inactive user", etc.
**Detection hint.** Any OAuth diagnosis that doesn't reference
Login History is starting from incomplete information.
---
## Anti-Pattern 5: JWT `sub` = User.Email
**What the LLM generates.**
```python
jwt_payload = {"sub": "user@example.com", ...}
```
**Why it happens.** Email is the human-recognizable identifier;
LLM picks it as the natural "subject".
**Correct pattern.** `sub` must be the User.Username, exactly as
in Setup → Users. Often differs from Email by an org-suffix
(`user@example.com.acmesandbox`).
**Detection hint.** Any JWT Bearer recipe using Email for `sub`
is going to fail with `invalid_grant`.
---
## Anti-Pattern 6: Default Refresh Token Policy for server-to-server
**What the LLM generates.** Setup steps for a server-to-server
integration that don't mention Refresh Token Policy.
**Why it happens.** The default looks like a normal value; the
silent-killer behavior isn't part of the LLM's salient knowledge.
**Correct pattern.** Always specify "Refresh token is valid
until revoked" for server-to-server in Connected App setup.
**Detection hint.** Any server-to-server Connected App setup
recipe that doesn't mention Refresh Token Policy is going to
produce day-2 failures.
---
## Anti-Pattern 7: IP enforcement on cloud-hosted integrations
**What the LLM generates.** "Add the integration's IP to the
user's profile Login IP Range."
**Why it happens.** "Tighter is more secure" instinct.
**Correct pattern.** Cloud IPs (AWS Lambda, etc.) are too
dynamic for IP-range pinning. Connected App IP Relaxation =
"Relax IP restrictions" + tight user permissions is the
standard pattern.
**Detection hint.** Any "add cloud IP to profile range"
recommendation for AWS Lambda / Azure Functions / similar is
not going to work reliably; the IP set rotates.
---
## Anti-Pattern 8: Not noting per-environment Consumer Key after deploy
**What the LLM generates.** "Deploy the Connected App via
metadata to production; integration will work."
**Why it happens.** "Deploy" feels complete.
**Correct pattern.** After Connected App metadata deploy,
fetch the new Consumer Key from production Setup and update the
integration's config. Keys are environment-specific.
**Detection hint.** Any Connected App deployment recipe that
doesn't include "fetch the new Consumer Key from the target
org" is going to fail with `invalid_client_id`.
---
## Anti-Pattern 9: Quoting a canonical list of `LoginHistory.Status` values
**What the LLM generates.** "Look for `Status` = 'Invalid Password', 'Login
Rate Exceeded', 'User is Frozen', or 'Restricted IP'" — presented as the
platform's enumerated value set, often as a lookup table mapping each string to
a fix.
**Why it happens.** Every other picklist on the object publishes its values —
`LoginType`, `LoginSubType`, `TlsProtocol` are all documented lists — so the
shape of the answer is familiar and the model fills it in.
**Correct pattern.** `Status` is typed `string`, not picklist, and the Object
Reference says only that it "[d]isplays the status of the attempted login.
Status is either success or a reason for failure." There is no published value
set to match against. Query the rows, read the strings the org actually emitted,
and quote those. Use `LoginSubType`, which *is* a restricted picklist with a
documented OAuth value list, as the structured discriminator instead.
**Detection hint.** Any triage advice that pattern-matches `Status` against a
remembered catalog, or that filters on it, is wrong twice over — the values are
not published and the field is outside the twelve filterable ones (gotcha 11).
---
## Anti-Pattern 10: Delivering a diagnosis with no recorded evidence
**What the LLM generates.** "The refresh token policy is almost certainly set to
expire immediately — change it to valid until revoked." One cause, high
confidence, no queries run, no alternatives ruled out.
**Why it happens.** The most-documented cause is also the most probable one in
training data, and it is often right. Being often right is what makes the habit
survive.
**Correct pattern.** `invalid_grant` has at least five causes and the runbook has
eleven rows. Run the three evidence queries first, record what each returned
including zero-row results, and name which rows the evidence eliminated. The
diagnosis record in `templates/connected-app-diagnosis-record.yaml` exists for
this; the checker fails a record whose evidence entries lack a `result`.
**Detection hint.** A proposed fix that arrives before any query result, or a
write-up whose "root cause" section has no "ruled out" section, has skipped the
diagnosis and gone straight to the most familiar answer.
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 |