Token Exchange — Configuration

Step 3 of the connection wizard asks for exactly two things: your identity provider's JWKS URI and its Issuer URI. Both come straight from your IdP's OIDC discovery document, so in most cases this is a copy-paste job.

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

Before you start

Complete Step 2 — Domain verification first. Provisioning refuses to run until it passes:

Verify the connection's domain before provisioning

The two fields

Go to Dashboard → Connections → your connection → Onboarding → Step 3 · Identity setup.

Field	What it is	Example
JWKS URI	Where your IdP publishes the public keys used to verify its tokens	`https://auth.acme.com/.well-known/jwks.json`
Issuer URI	The `iss` value your IdP stamps into tokens it issues	`https://auth.acme.com`

Click Save when both are filled in.

Finding these values

Nearly every OIDC provider serves a discovery document at:

https://<your-idp-domain>/.well-known/openid-configuration

Open it and read two fields:

json

{
  "issuer": "https://auth.acme.com",
  "jwks_uri": "https://auth.acme.com/.well-known/jwks.json"
}

Copy issuer into Issuer URI and jwks_uri into JWKS URI.

Common provider paths, if you'd rather go straight there:

Provider	Discovery document
Okta	`https://<org>.okta.com/oauth2/default/.well-known/openid-configuration`
Auth0	`https://<tenant>.auth0.com/.well-known/openid-configuration`
Microsoft Entra ID	`https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration`
Keycloak	`https://<host>/realms/<realm>/.well-known/openid-configuration`

Requirements

Requirement	Why
Both URLs must be HTTPS	Keys fetched over plain HTTP can be tampered with in transit.
The JWKS URI must be publicly reachable	LockMCP fetches it from its own servers, not from your users' browsers. An IdP behind a VPN or IP allowlist won't work unless LockMCP's egress is permitted.
The Issuer URI must match your tokens exactly	Issuer comparison is an exact string match. `https://auth.acme.com` and `https://auth.acme.com/` are different values — copy it verbatim from the discovery document rather than typing it.

Trailing slashes are the single most common configuration mistake here. Copy the issuer value exactly as your discovery document reports it.

Step 4 — Provision

With both fields saved and the domain verified, run Provision. If either field is missing you'll get:

Configure the JWKS URI and Issuer URI before provisioning

Provisioning creates the identity resources this connection needs. Each is namespaced to your tenant and connection, so connections never share identity configuration:

Resource	Purpose
Connection application client	Represents this connection. Browser sign-in flow is disabled — see the caveat on the overview.
Gateway client	The internal service identity LockMCP uses when brokering tokens for this connection.
Roles	The standard `mcp-admin` and `mcp-user` roles, used by Roles and Permissions.
Claims scope	Adds the user's roles, tenant and permissions to issued tokens, so the data plane can make authorization decisions without extra lookups.
Identity provider registration	Your IdP, registered from the JWKS and Issuer URIs you supplied.

If provisioning succeeds but sign-in doesn't work

The identity-provider registration step is non-fatal. If it fails — unreachable JWKS URI, malformed issuer, a transient network problem — provisioning still reports success and moves the connection to Provisioned, logging a warning rather than stopping.

That's deliberate (a transient IdP outage shouldn't roll back an otherwise good provision), but it means a green Step 4 doesn't by itself prove your IdP registered correctly. If users can't sign in afterwards, re-check both URLs and re-run provisioning — it's idempotent and safe to repeat. See Troubleshooting.

Step 5 — Activate

Activation flips the connection live. Until then the data plane won't serve tools for it, even with provisioning complete.

Rotating keys and changing IdPs

Your JWKS URI is read when the identity provider is registered, not on every request — but standard key rotation needs no action from you, as long as you keep publishing keys at the same JWKS URI and rotate in the normal overlapping way (publish the new key before retiring the old one).

You do need to re-run provisioning if you change the URL itself, or move to a different IdP or issuer. Update the fields in Step 3, save, and provision again.

Where to go next

Auth Flow — what actually happens on a tool call
Troubleshooting — when configuration doesn't take