Token Exchange — Auth Flow

This page traces what actually happens between your identity provider and a tool call. The short version: your IdP proves who the user is, LockMCP issues the token that gets used, and every tool call is verified against LockMCP's own issuer.

This page applies only to connections using the Token Exchange identity model.

The two phases

It helps to separate setup from runtime, because they use your IdP very differently.

Phase	Runs	Uses your JWKS URI?
Registration	Once, at Step 4 · Provision	Yes — your IdP is registered as a federated identity provider
Runtime	Every sign-in and tool call	No — tokens are verified against LockMCP's own issuer

This is the detail most worth internalising: LockMCP does not fetch your JWKS on each tool call. Your keys are used to establish the federation relationship. Once a user has signed in through it, the token in play is one LockMCP minted.

Sequence

┌──────────┐   ┌─────────────┐   ┌──────────────┐   ┌────────────┐
│  User /  │   │   Your      │   │   LockMCP    │   │  LockMCP   │
│  Client  │   │   IdP       │   │   Identity   │   │ Data Plane │
└──────────┘   └─────────────┘   └──────────────┘   └────────────┘
     │                │                  │                 │
     │  1. Sign in    │                  │                 │
     │ ──────────────►│                  │                 │
     │                │                  │                 │
     │  2. Your IdP authenticates the user                 │
     │     (your MFA, your session rules, your directory)  │
     │                │                  │                 │
     │                │  3. Federated    │                 │
     │                │     assertion    │                 │
     │                │ ────────────────►│                 │
     │                │                  │                 │
     │                │  4. LockMCP issues its own         │
     │                │     RS256 token for this session   │
     │  ◄─────────────────────────────── │                 │
     │                │                  │                 │
     │  5. Tool call, Bearer <LockMCP token>                │
     │ ───────────────────────────────────────────────────►│
     │                │                  │                 │
     │                │      6. Verify signature against   │
     │                │         LockMCP's issuer (RS256)   │
     │                │      7. Resolve user from `sub`    │
     │                │      8. Load that user's roles     │
     │                │         and permitted tools        │
     │                │                  │                 │
     │  9. Tool result (or 403 if not permitted)           │
     │  ◄──────────────────────────────────────────────────│

Step by step

1–2 · Your IdP authenticates the user. Entirely your territory — your login UI, your MFA policy, your session lifetime, your user directory. LockMCP is not involved and never sees credentials.

3 · Federation. Your IdP returns its assertion to LockMCP's identity layer, which trusts it because you registered the IdP during provisioning.

4 · LockMCP issues its own token. An RS256 JWT scoped to this session, carrying the claims added by the connection's claims scope: the user's roles, their tenant, and their permissions.

5–6 · The tool call. The AI client presents that token as a Bearer credential. The data plane verifies the signature and checks the issuer matches LockMCP's own — a single, fixed issuer, not a per-tenant one. Tokens are also required to carry exp, iss and sub.

7 · User resolution. The verified sub claim is looked up against LockMCP's user records to resolve the tenant and user identity. If there's no matching record:

Authentication failed: user not found — please log in to the Dashboard first

This is expected the very first time — a user must have signed in to the dashboard at least once before their identity exists to resolve. See Troubleshooting.

8 · Authorization. The user's roles determine which published tools they can see and call. Role-based tool access is enforced in the query itself, so a user never receives a tool they aren't permitted to call.

9 · Execution. LockMCP proxies the call to your upstream API using the connection's stored credentials, and returns the result.

What this means in practice

Question	Answer
Does LockMCP see my users' passwords?	No. Authentication happens entirely at your IdP.
If my IdP goes down, do existing sessions break?	Existing LockMCP tokens keep working until they expire — they're verified against LockMCP's issuer, not yours. New sign-ins will fail until your IdP is back.
If I disable a user in my IdP, are they cut off immediately?	Not instantly. They can't sign in again, but an already-issued token remains valid until it expires. For immediate cutoff, remove the user's access in LockMCP too.
Can I rotate my signing keys?	Yes — standard overlapping rotation at the same JWKS URI needs no action. Changing the JWKS URI itself requires re-running provisioning.
Does every tool call hit my IdP?	No. Verification is local to LockMCP's issuer, so tool calls don't add load to your IdP.

Contrast with the other models

	Token Exchange	Identity Brokering	Tenant Delegated
Who authenticates the user	Your IdP	LockMCP	Your app's login page
Token the client presents	LockMCP RS256	LockMCP RS256	LockMCP ES256
Verified against	LockMCP's issuer	LockMCP's issuer	Your connection's signing key
Your backend called per tool call	No	No	Yes — validate endpoint

Because Token Exchange and Identity Brokering share the same runtime verification path, the practical difference between them is where sign-in happens, not how tool calls are authenticated.

Where to go next

Configuration — the two fields and what provisioning creates
Troubleshooting — when sign-in or tool calls fail