Token Exchange — Troubleshooting
Token Exchange has few moving parts, so problems cluster tightly: a URL that's slightly off, an IdP LockMCP can't reach, or a user who hasn't signed in to the dashboard yet. This page maps each symptom to its cause.
This page applies only to connections using the Token Exchange identity model.
Provisioning is blocked
"Verify the connection's domain before provisioning"
Step 2 hasn't passed. Domain verification gates provisioning for every identity model.
- DNS TXT: allow time to propagate; confirm with
dig TXT yourdomain.com. If your provider auto-appends the domain, adding the full name again creates a doubled record that won't match. - Well-known file: open the URL the wizard shows in a browser. It must return the raw token with a
200— not a redirect, not an HTML page.
"Configure the JWKS URI and Issuer URI before provisioning"
One or both Step 3 fields are empty. Fill in both and click Save before running Provision — entering values without saving leaves them unset.
Provisioning succeeded but users can't sign in
This is the most confusing failure mode, and it has a specific explanation.
The identity-provider registration step is non-fatal. If LockMCP can't register your IdP — unreachable JWKS URI, malformed issuer, transient network fault — provisioning still reports success and moves the connection to Provisioned, logging a warning instead of failing.
So a green Step 4 confirms the connection's own resources were created; it does not prove your IdP registered. Work through this list:
| Check | How |
|---|---|
| Is the JWKS URI publicly reachable? | Open it from outside your network — not from your office VPN. It must return JSON with a keys array. |
| Is it HTTPS? | Plain HTTP is rejected. |
| Does the issuer match exactly? | Compare against issuer in your /.well-known/openid-configuration. A trailing slash makes it a different value. |
| Is your IdP behind an IP allowlist? | LockMCP fetches from its own servers. Allowlist-restricted IdPs won't be reachable. |
Fix whatever's off, then re-run Provision — it's idempotent, so repeating it is safe.
Errors after activation
| Message | What it means | Fix |
|---|---|---|
Authentication failed: user not found — please log in to the Dashboard first | The token verified fine, but its sub doesn't match a known user. | Expected on a user's very first connection. Have them sign in to the LockMCP dashboard once so their identity is established, then retry. |
Authentication failed: identity provider unreachable | LockMCP's own identity layer didn't respond in time. | Usually transient — retry. If it persists, check the status page. |
Authentication failed: unable to resolve signing key | The token's signing key couldn't be resolved. | Almost always a token from the wrong issuer — e.g. your IdP's raw token sent directly instead of the LockMCP-issued one. See below. |
Authentication failed: token has expired | Normal expiry. | The client should re-authenticate. Persistent expiry on fresh tokens points to server clock skew. |
Authentication failed: issuer not recognized | The token wasn't issued for this connection. | Confirm you're calling the right connection's MCP endpoint. Each connection has its own. |
Sending your IdP's token directly
Worth calling out because it's a natural assumption: you cannot present your IdP's own JWT to the MCP endpoint. Tool calls must carry the token LockMCP issued after federated sign-in. Your IdP's token establishes the session; it isn't the credential for tool calls. See the Auth Flow.
Claude Desktop / ChatGPT / Cursor won't connect
This is expected, not a bug. Token Exchange connections have the interactive browser sign-in flow disabled by design — those clients need to pop open a browser and complete a login, which is exactly what Token Exchange replaces.
Integrate a Token Exchange connection programmatically instead — see Programmatic Integration. The Connect page's MCP URL is still the endpoint to use.
If you need desktop AI clients, use Identity Brokering — either switch this connection's model in Step 1 and re-provision, or create a second connection alongside it, since identity model is per connection.
Connected, but no tools appear
Authentication is working; this is an authorization or publishing gap.
| Cause | Fix |
|---|---|
| Tools exist but aren't published | Publish them in the Tool Catalog. Draft tools are never served. |
| The user's role has no tool access | Grant the role access to the tools it should see. |
| Connection isn't Active | Complete Step 5. The data plane only serves Active connections. |
| Calling the tenant-wide endpoint | A connection's tools are served at its own endpoint. Confirm the URL on the Connect page. |
Key rotation broke sign-in
Standard overlapping rotation at the same JWKS URI requires no action — publish the new key before retiring the old one and sign-in continues uninterrupted.
If you changed the JWKS URI, changed issuer, or moved to a different IdP, update Step 3 and re-run provisioning. The old registration points at values that no longer resolve.
Where to go next
- Configuration — the two fields and where to find them
- Auth Flow — the full sequence, useful for reasoning about failures