Token Exchange
Token Exchange is for teams that already run an identity provider. You register your IdP with LockMCP once, and LockMCP federates it into its own login — so your users sign in with the accounts they already have, and you don't build or host any auth endpoints.
Setup is two fields. There's no login page to write, no contract to implement, and no HMAC signing.
This page and everything under Token Exchange in the sidebar apply only to connections whose identity model is Token Exchange. Using a different model? See Identity Brokering or Tenant Delegated.
When to choose it
| Choose Token Exchange when | Choose something else when |
|---|---|
| You already run an OIDC identity provider (Okta, Auth0, Entra ID, Keycloak, your own) | You have no identity provider and don't want one → Identity Brokering |
| Your users should keep signing in with their existing corporate accounts | You need the login page to be your own branded UI → Tenant Delegated |
What "federation" means here
This is the part worth being precise about, because the name can mislead.
You give LockMCP two things: your IdP's JWKS URI and its Issuer URI. LockMCP uses them to register your IdP as an OIDC identity provider inside its own identity layer. From then on:
- Your users sign in through your IdP, as they always have.
- LockMCP's identity layer trusts that sign-in and issues its own token for the session.
- Tool calls carry that token, and LockMCP verifies it against its own issuer.
So your IdP is the source of truth for who the user is, but the token an AI client actually presents is one LockMCP minted. Your JWKS URI is read during setup, not on every tool call.
The full sequence is on the Auth Flow page. The name comes from RFC 8693, the OAuth token-exchange standard this pattern is modelled on.
Setting it up
Connections go through a five-step wizard that's the same for every identity model. Only Step 3 · Identity setup differs — for Token Exchange it asks for two things:
- Your JWKS URI — e.g.
https://auth.acme.com/.well-known/jwks.json - Your Issuer URI — e.g.
https://auth.acme.com
Both come from your provider's OIDC discovery document. See Configuration for where to find them and what provisioning does with them.
Connecting from Claude Desktop or ChatGPT
Token Exchange connections work with interactive browser-OAuth AI clients the same way Identity Brokering connections do. When someone opens the login popup, LockMCP redirects it straight to your IdP's own sign-in page (via Keycloak's kc_idp_hint), then brings them back authenticated once they've signed in there — no hub username or password is ever shown.
The Connect page shows the same Claude Desktop/Cursor/ChatGPT setup tabs as any other identity model. See the Auth Flow page for the full sequence.
Where to go next
| Page | What it's for |
|---|---|
| Configuration | The two fields, where to find them in your IdP, and what provisioning creates |
| Auth Flow | The full sequence, from your IdP to a verified tool call |
| Troubleshooting | JWKS problems, issuer mismatches, and provisioning failures |