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-diagnosis-record.yaml
View on GitHub# Connected App OAuth Diagnosis Record
#
# One record per investigated failure. Commit it alongside the fix.
# Linted by:
# python3 scripts/check_connected_app_troubleshooting.py --manifest-dir <dir holding this file>
#
# The checker requires, under `diagnosis:`
# symptom, error, app, user-id, first-failure, root-cause, fix-applied, verified-by
# plus at least one `evidence:` entry, and every evidence entry must carry both a
# `query` and a `result`. `root-cause` must be one of the categories below, which are
# the ones in references/metadata-examples.md § 1:
#
# callback-url the redirect_uri the client sends is not in callbackUrl
# pre-authorization isAdminApproved with no matching permissionSetName / profileName
# flow-not-enabled the grant type is not switched on for this app
# refresh-token-policy refreshTokenPolicy invalidates the token before the client renews
# secret-required-asymmetry isConsumerSecretOptional and isSecretRequiredForRefreshToken disagree
# refresh-token-rotation an invalidated refresh token was replayed and deleted the grant
# ip-restriction ipRelaxation ENFORCE against an address the caller cannot control
# policy-change a Setup change corroborated by SetupAuditTrail
# user-state the authenticating user is inactive, frozen, or unassigned
# app-blocked the app is blocked in Connected Apps OAuth Usage
# post-auth-authorization authentication succeeded; the API call was refused (scope / CRUD)
#
# Redact every consumer key, consumer secret and token as [REDACTED] before committing.
diagnosis:
symptom: >
One-line description of what the caller sees, with the timeline.
Example: worked from 2026-08-14, every call since 2026-09-02T09:14Z returns 400.
error: |
Paste the response body verbatim, with the request line and HTTP status.
Replace credentials with [REDACTED].
app: Connected app label, exactly as it appears in Setup
user-id: 005XXXXXXXXXXXXXXX
first-failure: 2026-09-02T09:14:00Z
flow: >
The grant flow the client uses, and which half failed
(initial authorization or renewal) per LoginSubType.
root-cause: refresh-token-policy
fix-applied: |
What changed, in which org, and whether a re-authorization was required.
verified-by: |
The post-fix evidence. For a renewal failure this must name a Success row
whose LoginSubType is the one that was failing.
evidence:
# Every entry needs both `query` and `result`. A zero-row result is a finding:
# write "0 rows" and say what it rules out.
- step: LoginHistory for the authenticating user over the failure window
query: >
SELECT LoginTime, Status, LoginSubType, Application, SourceIp
FROM LoginHistory WHERE UserId = '005XXXXXXXXXXXXXXX'
AND LoginTime = LAST_N_DAYS:1 ORDER BY LoginTime DESC
result: >
Row count, the Status and LoginSubType values seen, and which runbook
rows this rules out.
- step: OauthToken rows for the app
query: >
SELECT AppName, UserId, LastUsedDate, UseCount FROM OauthToken
WHERE AppName = 'Connected app label' ORDER BY LastUsedDate DESC
result: >
Row count, UseCount and LastUsedDate, AND the runner's username plus
confirmation they hold Customize Application. Without that, an empty
result rules nothing out.
- step: SetupAuditTrail from before the first failure
query: >
SELECT CreatedDate, CreatedBy.Name, DelegateUser, Action, Section, Display
FROM SetupAuditTrail WHERE CreatedDate >= 2026-08-25T00:00:00Z
ORDER BY CreatedDate DESC LIMIT 500
result: >
Any row naming this app, with its timestamp relative to first-failure.
Say "0 rows naming the app" explicitly if that is the answer.
# Optional. Fill when the fix touched oauthPolicy or ipRelaxation.
sandbox-reproduction:
org: sandbox name
reproduced: true
notes: >
Whether the sandbox reproduced the symptom before the fix. A sandbox that
did not reproduce it has validated nothing — diff the two oauthPolicy blocks.
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 |