Skip to main content

JWT Passthrough

JWT passthrough allows users to access internal MCP servers using their SSO identity without entering separate credentials. When enabled, Willow captures the user's JWT at login and passes it automatically to internal MCP servers. Users authenticate once and Willow handles token refresh transparently.

Prerequisites​

  • SSO must already be configured (see Configure SSO)
  • Your internal MCP servers must accept JWT tokens in the Authorization: Bearer <token> header
  • Your IdP must support refresh tokens

Enable JWT passthrough​

  1. Go to Admin → Settings → Authentication Settings
  2. Scroll to your configured SSO provider
  3. Check Enable passthrough refresh token
  4. The OIDC Token Endpoint is auto-discovered from your IdP's .well-known/openid-configuration. Verify it is correct.
  5. Select Save Changes

Configure your internal MCP servers​

Your internal MCP servers must:

  1. Accept JWT tokens in the Authorization: Bearer <token> header
  2. Validate tokens against your IdP's JWKS endpoint
  3. Extract user identity from standard claims (sub, email, preferred_username)

Register the internal MCP in Willow​

  1. Go to Build > MCP Servers
  2. Open the server's edit page, or add a new custom server pointing to your internal endpoint (see Add an MCP Server)
  3. Open the Setup tab
  4. Select Proxy Passthrough
  5. Select Save Changes

See Configure MCP Server Authentication for details on Proxy Passthrough.

How token refresh works​

Willow stores encrypted OAuth credentials (access token + refresh token) at login. When a token expires, Willow automatically refreshes it from your IdP's token endpoint and passes the new token to the MCP server, transparently and without user action.

Troubleshoot​

"No OAuth credentials found for user": The user must log out and log back in to capture credentials.

"Organization does not have OIDC token endpoint configured": Go to Admin → Settings → Authentication Settings, check the OIDC Token Endpoint field, and enter the endpoint manually if needed.

"Failed to refresh token" / "invalid_grant": The refresh token has expired. The user must log out and back in. Check your IdP's refresh token lifetime settings.

Token endpoint auto-discovery not working: Visit https://your-idp.com/.well-known/openid-configuration in a browser to verify the token_endpoint field exists, then paste it manually into the Willow configuration.

On this page