Skip to main content
JWT validation enables Portkey to verify tokens from your identity provider before processing MCP requests. Use with External OAuth to bring your own IdP.

​
When to Use

Organizations with existing identity providers (Okta, Auth0, Azure AD, Cognito) can use JWT validation. Users authenticate through the IdP, and MCP access works the same way. Flow:
  1. Users get a token from the IdP
  2. Token included in MCP requests
  3. Portkey validates the token against the IdP
  4. Valid requests proceed with user identity attached
Portkey never handles user credentials. Your IdP remains the source of truth for identity.

​
Validation Methods

Configure one validation method per MCP server. Each has different tradeoffs.

​
JWKS URI

Fetch public keys from your IdP’s JWKS endpoint. This is the standard approach for most identity providers. 
{
  "jwt_validation": {
    "jwksUri": "https://your-idp.com/.well-known/jwks.json",
    "algorithms": ["RS256", "ES256"]
  }
}
Portkey fetches keys and caches them (default: 24 hours). When a key rotates, Portkey automatically refetches the JWKS if verification fails with the cached key. Best for: Most production deployments. Minimal configuration, automatic key rotation.

​
Inline JWKS

Embed public keys directly in the configuration. Use for self-contained deployments or environments without a JWKS endpoint. 
{
  "jwt_validation": {
    "jwks": {
      "keys": [{
        "kty": "RSA",
        "n": "0vx7agoebGcQSuu...",
        "e": "AQAB",
        "kid": "key-id-1",
        "use": "sig",
        "alg": "RS256"
      }]
    }
  }
}
Update keys manually when they rotate. Best for: Air-gapped environments, testing, or when IdP doesn’t expose JWKS.

​
Token Introspection (RFC 7662)

For opaque tokens that require real-time validation. Portkey calls your IdP’s introspection endpoint. 
{
  "jwt_validation": {
    "introspectEndpoint": "https://your-idp.com/oauth/introspect",
    "introspectContentType": "application/json",
    "introspectCacheMaxAge": 300
  }
}
The introspection endpoint must return a JSON response with an active boolean field per RFC 7662. Best for: Opaque tokens, real-time revocation checking, or validating token status against the IdP on every request.

​
Configuration Reference

​
Core Options

FieldTypeDefaultDescription
jwksUristring-URL to fetch public keys
jwksobject-Inline JWKS object with keys array
introspectEndpointstring-Token introspection URL (RFC 7662)
headerKeystring"Authorization"Header to read the token from
algorithmsstring[]["RS256"]Allowed signing algorithms

​
Timing Options

FieldTypeDefaultDescription
clockTolerancenumber5Clock skew tolerance in seconds
cacheMaxAgenumber86400JWKS cache TTL in seconds (24 hours)
maxTokenAgestring-Max token age (e.g., "30m", "12h")

​
Introspection Options

FieldTypeDefaultDescription
introspectEndpointstring-Token introspection URL
introspectContentTypestring"application/json"Content-Type for introspection requests
introspectCacheMaxAgenumber-Cache introspection results (seconds)

​
Claim Validation Options

FieldTypeDefaultDescription
requiredClaimsstring[]-Claims that must be present
claimValuesobject-Expected claim values with match types
headerPayloadMatchstring[]-Header claims that must match payload claims

​
Custom Token Header

By default, Portkey reads the token from the Authorization header. For a different header: 
{
  "jwt_validation": {
    "jwksUri": "https://your-idp.com/.well-known/jwks.json",
    "headerKey": "X-Auth-Token"
  }
}
Agents then send: 
{
  "headers": {
    "X-Auth-Token": "Bearer eyJhbGciOiJSUzI1NiIs..."
  }
}

​
Require Specific Claims

Tokens must include these claims or they’re rejected: 
{
  "jwt_validation": {
    "jwksUri": "https://your-idp.com/.well-known/jwks.json",
    "requiredClaims": ["sub", "email", "groups"]
  }
}
If a token is missing sub, email, or groups, Portkey returns: 
{
  "error": "unauthorized",
  "error_description": "Missing required claims: groups"
}

​
Validate Claim Values

Check that claims have expected values: 
{
  "jwt_validation": {
    "jwksUri": "https://your-idp.com/.well-known/jwks.json",
    "claimValues": {
      "iss": {
        "values": "https://your-idp.com",
        "matchType": "exact"
      },
      "aud": {
        "values": ["api", "mcp", "portkey"],
        "matchType": "contains"
      },
      "scope": {
        "values": ["mcp:read", "mcp:write"],
        "matchType": "containsAll"
      },
      "email": {
        "values": "@yourcompany\\.com$",
        "matchType": "regex"
      }
    }
  }
}

​
Match Types

TypeDescriptionExample
exactValue must match exactlyiss must equal "https://your-idp.com"
containsPayload must include at least one value (OR)aud must include "api" OR "mcp" OR "portkey"
containsAllPayload must include all values (AND)scope must include "mcp:read" AND "mcp:write"
regexMatch against a regular expressionemail must match @yourcompany\.com$

​
Header-Payload Matching

Ensure that claims in the JWT header match claims in the payload. This provides additional security for tokens that include claims in both locations. 
{
  "jwt_validation": {
    "jwksUri": "https://your-idp.com/.well-known/jwks.json",
    "headerPayloadMatch": ["kid", "alg"]
  }
}
If a specified claim exists in both the header and payload, they must have identical values. If they don’t match, the token is rejected. Use case: Some IdPs include certain claims in both the protected header and the payload. This validation ensures consistency and detects tampering.

​
Caching Behavior

​
JWKS Caching

  • Keys cached for 24 hours by default (configurable via cacheMaxAge)
  • CryptoKeys are pre-imported and cached for performance
  • If signature verification fails with a cached key, Portkey refetches the JWKS (handles key rotation)

​
Introspection Caching

  • Not cached by default (every request calls the introspection endpoint)
  • Enable caching with introspectCacheMaxAge (in seconds)
  • Cached results respect token expiry—expired tokens aren’t served from cache
Example with caching: 
{
  "jwt_validation": {
    "introspectEndpoint": "https://your-idp.com/oauth/introspect",
    "introspectCacheMaxAge": 300
  }
}
With this configuration:
  • First request: calls introspection endpoint, caches result
  • Subsequent requests (within 5 minutes): uses cached result
  • After 5 minutes: calls introspection endpoint again
Tradeoff: Shorter cache means more latency but faster revocation detection. Longer cache means better performance but slower revocation response.

​
Performance Optimizations

Portkey optimizes JWT validation for production workloads:
OptimizationDescription
Fail-fast expiry checkChecks token expiry before expensive signature verification
JWKS cachingKeys cached and pre-imported as CryptoKeys
Key rotation handlingAuto-refetch JWKS if key not found
Introspection cachingOptional caching of introspection results
Typical validation latency:
  • JWKS (cache hit): < 1ms
  • JWKS (cache miss): 50-200ms (network fetch)
  • Introspection (uncached): 50-300ms (depends on IdP)
  • Introspection (cached): < 1ms

​
Example: Okta Integration

{
  "jwt_validation": {
    "jwksUri": "https://dev-12345.okta.com/oauth2/aus123/v1/keys",
    "algorithms": ["RS256"],
    "clockTolerance": 5,
    "requiredClaims": ["sub", "email"],
    "claimValues": {
      "iss": {
        "values": "https://dev-12345.okta.com/oauth2/aus123",
        "matchType": "exact"
      },
      "aud": {
        "values": "api://mcp",
        "matchType": "exact"
      }
    }
  }
}

​
Example: Auth0 Integration

{
  "jwt_validation": {
    "jwksUri": "https://your-tenant.auth0.com/.well-known/jwks.json",
    "algorithms": ["RS256"],
    "requiredClaims": ["sub", "email"],
    "claimValues": {
      "iss": {
        "values": "https://your-tenant.auth0.com/",
        "matchType": "exact"
      },
      "aud": {
        "values": "https://mcp.yourcompany.com",
        "matchType": "exact"
      }
    }
  }
}

​
Example: Azure AD Integration

{
  "jwt_validation": {
    "jwksUri": "https://login.microsoftonline.com/{tenant-id}/discovery/v2.0/keys",
    "algorithms": ["RS256"],
    "requiredClaims": ["sub", "email", "groups"],
    "claimValues": {
      "iss": {
        "values": "https://login.microsoftonline.com/{tenant-id}/v2.0",
        "matchType": "exact"
      },
      "aud": {
        "values": "{client-id}",
        "matchType": "exact"
      }
    }
  }
}

​
Combining with Identity Forwarding

JWT validation extracts user claims from the token. Identity forwarding passes those claims to MCP servers: 
{
  "jwt_validation": {
    "jwksUri": "https://your-idp.com/.well-known/jwks.json",
    "requiredClaims": ["sub", "email", "groups"]
  },
  "user_identity_forwarding": {
    "method": "claims_header",
    "include_claims": ["sub", "email", "groups"]
  }
}
Flow:
  1. User sends request with IdP token
  2. Portkey validates token, extracts claims
  3. Portkey forwards claims to MCP server
  4. MCP server uses claims for authorization/logging
See Identity Forwarding.

​
Error Responses

ErrorDescription
Missing Authorization headerNo token provided
Invalid authorization header formatNot in Bearer <token> format
JWT validation failedSignature invalid or token malformed
Token is expiredToken’s exp claim is in the past
Token is not yet validToken’s nbf claim is in the future
Missing required claims: <claims>Token missing required claims
Token is not activeIntrospection returned active: false
TopicDescription
External OAuthOverview of using external IdPs
Identity ForwardingPass validated claims to MCP servers