Skip to main content

JWT Passthrough Authentication

Enable seamless single sign-on for users accessing internal MCP servers. With JWT passthrough, users authenticate once with your Identity Provider and automatically gain access to internal tools without re-entering credentials.

Use Case​

Your organization has internal MCP servers (APIs, databases, custom tools) that require user identity for authorization and audit logging. Instead of managing separate credentials for each system, JWT passthrough allows users to authenticate once through your SSO provider (e.g Okta/Entra), and Webrix automatically passes their JWT token to internal MCP servers.

Example Scenario:

A data analyst logs into Webrix via Okta SSO. They can now query your internal analytics API, access internal databases, and use custom MCP tools—all using their Okta identity. The internal systems receive a valid JWT token identifying the user, enabling proper authorization and audit trails.

How It Works​

The flow:

  1. Initial Login: User authenticates via SSO (Okta/Keycloak) at connect.mcp-s.com
  2. Token Storage: Webrix requests offline access and stores encrypted OAuth credentials (access token, refresh token, expiry)
  3. Automatic Passthrough: When accessing internal MCP servers, Webrix passes the user's JWT in the Authorization header
  4. Seamless Access: Users experience uninterrupted access to internal tools

Configuration​

Prerequisites​

Before enabling JWT passthrough:

  • Your SSO provider (e.g Okta/Entra) must be configured in Webrix
  • Your internal MCP servers must accept JWT tokens from your IdP
  • Your IdP must support refresh tokens

Step 1: Enable JWT Passthrough​

  1. Navigate to Settings → Authentication in the admin portal
  2. Scroll to your configured SSO provider
  3. Check the box Enable passthrough refresh token
  4. The OIDC Token Endpoint will be auto-discovered from your IdP's .well-known/openid-configuration
  5. Verify the token endpoint is correct (e.g., https://dev-123456.okta.com/oauth2/default/v1/token)
  6. Click Save

Step 2: Configure Your Internal MCP Servers​

Your internal MCP servers must be configured to:

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

Example JWT validation (pseudocode):

// Fetch IdP's public keys
const jwks = await fetch("https://your-idp.com/.well-known/jwks.json")

// Verify the token signature
const decoded = jwt.verify(token, jwks)

// Extract user identity
const userId = decoded.sub
const userEmail = decoded.email

Step 3: Register Your Internal MCP in Webrix​

  1. Go to Integrations → New Integration
  2. Select Custom MCP (via proxy)
  3. Enter your internal MCP server endpoint
  4. Set Authentication Type to User JWT Passthrough
  5. Configure visibility and permissions
  6. Save

Security​

Token Encryption​

All OAuth credentials (access tokens, refresh tokens) are encrypted at rest using Webrix's Vault encryption system. Tokens are never stored in plain text.

Token Refresh​

When a token expires, Webrix automatically:

  1. Retrieves the encrypted refresh token from the database
  2. Calls your IdP's token endpoint to obtain a new access token
  3. Stores the new encrypted credentials
  4. Passes the fresh token to the MCP server

This happens transparently without user interaction.

Scope and Claims​

Webrix passes the JWT exactly as issued by your IdP. Your internal MCP servers should:

  • Validate the token signature
  • Check token expiration (exp claim)
  • Verify the issuer (iss claim)
  • Extract user identity from standard claims (sub, email, etc.)

Troubleshooting​

"No OAuth credentials found for user"​

Cause: The user hasn't logged in since JWT passthrough was enabled, or their credentials weren't captured during SSO.

Solution: Have the user log out of Webrix and log back in. The new login will capture and store the OAuth credentials.

"Organization does not have OIDC token endpoint configured"​

Cause: The OIDC token endpoint wasn't auto-discovered or wasn't saved.

Solution:

  1. Go to Settings → Authentication
  2. Check the OIDC Token Endpoint field
  3. Manually enter your IdP's token endpoint if needed
  4. Save the configuration

"Failed to refresh token" / "invalid_grant"​

Cause: The refresh token is expired or invalid.

Solution:

  • Refresh tokens have their own expiration (typically 7-90 days depending on IdP configuration)
  • Have the user log out and log back in to obtain a new refresh token
  • Check your IdP's refresh token lifetime settings

"Invalid token" from Internal MCP Server​

Cause: Your MCP server isn't correctly validating the JWT.

Solution:

  1. Verify your MCP server is fetching the correct JWKS from your IdP
  2. Check that the token issuer matches your IdP's issuer URL
  3. Ensure your MCP server's clock is synchronized (for exp validation)
  4. Test with a known-good JWT from your IdP

Token Endpoint Auto-Discovery Not Working​

Cause: Your IdP's .well-known/openid-configuration endpoint is not accessible or malformed.

Solution:

  1. Manually visit https://your-idp.com/.well-known/openid-configuration in a browser
  2. Verify the token_endpoint field exists
  3. Manually copy and paste the token endpoint into the Webrix configuration

Best Practices​

  • Monitor Token Expiration: Configure reasonable token lifetimes in your IdP (typically 1 hour for access tokens, 7-30 days for refresh tokens)
  • Audit Logging: Your internal MCP servers should log the user identity from JWT claims for audit purposes
  • Least Privilege: Configure your IdP to include only necessary claims in the JWT
  • Regular Re-authentication: Consider requiring periodic re-authentication for sensitive operations