Identity Brokering — Troubleshooting
Identity Brokering has the fewest ways to go wrong, since there's no identity provider or auth endpoints of your own in the path. Problems almost always land in one of four places: domain verification, a user who hasn't signed in yet, tool access that hasn't been granted, or — if this connection's tools call your own API — that API not verifying the forwarded token.
This page applies only to connections using the Identity Brokering identity model.
Provisioning is blocked
"Verify the connection's domain before provisioning"
Step 2 hasn't passed — the only step that can realistically hold up an Identity Brokering connection.
| Method | What to check |
|---|---|
| DNS TXT | Allow time to propagate; confirm with dig TXT yourdomain.com (or nslookup -type=TXT). If your DNS provider auto-appends the domain, entering the full name again creates a doubled record that won't match. |
| Well-known file | Open the exact URL the wizard shows. It must return the raw token with a 200 — a redirect, a 404, or an HTML error page all fail. |
Once verification is green, Step 3 needs nothing and Step 4 should complete without input.
Errors after activation
| Message | What it means | Fix |
|---|---|---|
Authentication failed: user not found — please log in to the Dashboard first | The token verified, but its sub doesn't match a known user. | Expected the first time. Have the user sign in to the LockMCP dashboard once, then retry. If they were never invited, invite them under Members & Access. |
Authentication failed: token has expired | Normal expiry. | The client should re-run the sign-in flow; most do automatically. Persistent expiry on fresh tokens suggests server clock skew. |
Authentication failed: issuer not recognized | The token wasn't issued for this connection. | Confirm the client is pointed at the right connection's MCP endpoint — each connection has its own. |
Authentication failed: identity provider unreachable | LockMCP's 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 stale token from before a re-provision. Sign out in the AI client and reconnect. |
Your API rejects the forwarded token
This is different from the table above: those are LockMCP's own authentication rejecting the token before your API is ever called. If a tool call reaches your API and fails there, authentication at the hub already succeeded — the token forwarded to you is valid, and it's your own verification of it that's failing or missing.
| Symptom | Cause | Fix |
|---|---|---|
| Tool call fails with your API's own generic auth-failure message (e.g. "invalid or expired token") on every call | Your API isn't verifying the forwarded token at all — it's rejecting (or ignoring) it rather than validating it | Add real JWT verification. See Verifying the forwarded token in your own API for the exact contract and working examples. |
| Verification code exists but still rejects valid tokens | Usually an issuer mismatch — a token minted by one LockMCP environment (e.g. local/dev) checked against a different environment's expected issuer | Decode the token (e.g. at jwt.io) and confirm its iss claim matches exactly what your verification code expects. |
| Some tools work, others don't | Verification middleware is only applied to some routes | Confirm every tool-mapped endpoint runs the same verification, not just the first one you wired up. |
Verification passes, but write/action endpoints return your own app's 403 permission-denied message | Your authorization check depends on the token's role claim, which is empty for real users today | See Authorization: don't rely on the token's role claim — trust LockMCP's own access control instead. |
| Writes fail with a foreign-key/constraint error referencing a user/agent/owner column | No local user row exists yet for this LockMCP identity — a fresh sub has no corresponding row in your own user table | See Mapping LockMCP identities to your own users for the find-or-create pattern. |
The AI client won't connect
| Symptom | Cause | Fix |
|---|---|---|
| Client reports the server is unreachable | Connection isn't Active | Complete Step 5 · Activate. The data plane won't serve a connection until then. |
| Browser opens but sign-in fails | The user has no LockMCP account | Invite them under Members & Access. |
| Sign-in completes, client still shows disconnected | Stale cached credentials | Remove the connector in the AI client and re-add it so it runs a fresh OAuth flow. |
| Wrong workspace's tools appear | Wrong endpoint URL | Copy the URL again from the Connect page for this specific connection. |
Because this model uses standard browser OAuth, Claude Desktop, Cursor, Windsurf and ChatGPT connectors should all work by pasting the MCP endpoint URL. If a client asks for an API key or a config file, it's likely pointed at something other than the URL shown on the Connect page.
Connected, but no tools appear
Authentication is fine — this is an authorization or publishing gap. Work down in order:
| Check | Fix |
|---|---|
| Are any tools published? | Draft tools are never served. Publish them in the Tool Catalog. |
| Does the user's role have access to them? | Grant the role access per tool. Published-but-unassigned tools are invisible to non-admin members. |
| Does the user have a role on this connection? | Assign one under Members & Access. |
| Is the connection Active? | Complete Step 5. |
An admin often sees tools that members don't — that asymmetry is almost always role-based tool access, not a bug.
A user sees the wrong tools
Tool visibility is computed from the user's roles at request time, so it changes as soon as their roles do — no re-connection needed. If it looks stale:
- Confirm which roles the user actually holds under Members & Access.
- Check the tool's access settings, not just the role's — access is a matrix of both.
- Have the user re-list tools in their AI client; some clients cache the tool list for the session.
Removing access
Remove the member under Members & Access. Their ability to sign in ends immediately, though an already-issued token remains valid until it expires — so for urgent revocation, remove the member and have them disconnect the client.
Where to go next
- Configuration — provisioning and access setup
- Auth Flow — the full sequence, useful for reasoning about failures