JWT Token Validator - Portkey Docs

The JWT Token Validator guardrail provides comprehensive JWT (JSON Web Token) validation and authentication for the Portkey Gateway. It supports signature verification, claim validation, and custom business logic rules.

Features

Signature Verification: Validates JWT signatures using JWKS (JSON Web Key Set)
Inline JWKS Support: Provide JWKS directly without requiring external URI
Token Introspection: Validates tokens via external introspection endpoint (RFC 7662)
Required Claims: Ensures specific claims are present in the token
Claim Value Validation: Validates claim values with flexible matching strategies
Header-Payload Matching: Ensures consistency between header and payload values
JWKS Caching: Efficient JWKS caching to reduce external calls (URI-based)
Introspection Caching: Cache introspection results with automatic expiry validation
Multi-tenant Support: Validate tenant IDs and other organizational claims
Role-Based Access: Validate user groups, roles, and permissions
OAuth2/OIDC Support: Standard audience, issuer, and scope validation
Claim Extraction: Extract JWT claims and inject them into request context as headers

Validation Methods

The guardrail supports three validation methods:

Method	Best For	Pros	Cons
Inline JWKS	Testing, static key deployments	No external dependencies, fastest validation	Requires config updates for key rotation
JWKS URI	Production with key rotation	Automatic key rotation, caching, industry standard	Requires network access
Token Introspection	Opaque tokens, revocation support	Works with opaque tokens, immediate revocation	Network latency, external dependency

Configuration Parameters

Core Parameters

Parameter	Type	Required	Default	Description
`jwks`	object	Conditional*	-	Inline JWKS object for token verification
`jwksUri`	string	Conditional*	-	URI to fetch JSON Web Key Set for token verification
`introspectEndpoint`	string	Conditional*	-	Token introspection endpoint URL (RFC 7662)
`headerKey`	string	No	`"Authorization"`	Header containing the JWT token

*Either jwks, jwksUri, or introspectEndpoint must be provided.

JWKS Validation Parameters

When using jwks or jwksUri:

Parameter	Type	Required	Default	Description
`algorithms`	string[]	No	`["RS256"]`	Allowed signing algorithms
`cacheMaxAge`	number	No	`86400`	JWKS cache duration in seconds (24h) - only applies to `jwksUri`
`clockTolerance`	number	No	`5`	Clock tolerance in seconds for time-based claims (`exp`, `nbf`)
`maxTokenAge`	string	No	`"1d"`	Maximum token age (e.g., ‘1d’, ‘12h’, ‘30m’)

Token Introspection Parameters

When using introspectEndpoint:

Parameter	Type	Required	Default	Description
`introspectContentType`	string	No	-	Content type for Introspection Endpoint
`introspectCacheMaxAge`	number	No	-	Cache introspection results for this many seconds
`clockTolerance`	number	No	`5`	Clock tolerance in seconds for time-based claims

Claim Validation Parameters

Parameter	Type	Required	Description
`requiredClaims`	string[]	No	Array of claim names that must be present
`claimValues`	object	No	Object mapping claim names to expected values with match types
`headerPayloadMatch`	string[]	No	Array of keys where header[key] must equal payload[key]
`extractClaims`	string[]	No	Array of claim names to extract and inject into request context
`claimPrefix`	string	No	Prefix for extracted claim headers (default: `"x-jwt-"`)

Match Types

The claimValues parameter supports different match types for flexible validation:

`exact` (default)

The claim value must exactly equal the expected value. Requires single-value string claim and single expected value. Use cases: iss, sub, client_id - single exact value validation

{
  "claimValues": {
    "iss": {
      "values": "https://auth.example.com"
    }
  }
}

`contains`

Array/string must contain at least one of the expected values (OR logic). Use this for array claims. Use cases: aud (JWT audience arrays), groups, roles, permissions

{
  "claimValues": {
    "groups": {
      "values": ["admin", "moderator"],
      "matchType": "contains"
    }
  }
}

`containsAll`

Array/string must contain ALL of the expected values (AND logic). Use this when ALL values are required. Use cases: scope (requires ALL specified scopes), required permissions

{
  "claimValues": {
    "scope": {
      "values": ["read:api", "write:api"],
      "matchType": "containsAll"
    }
  }
}

`regex`

Value must match the regex pattern. Use cases: Email domain validation, pattern matching

{
  "claimValues": {
    "email": {
      "values": ".*@(company1|company2)\\.com$",
      "matchType": "regex"
    }
  }
}

Quick Reference

Claim Type	Example	Recommended matchType
Single value, exact match	`iss`, `sub`, `client_id`	`exact`
Single value, OR logic	`tenant_id` with multiple tenants	`contains`
Array - check if contains any	`aud`, `groups` (OR logic)	`contains`
Array - check if contains all	`scope` (AND logic)	`containsAll`
Pattern matching	`email` domain validation	`regex`

Usage Examples

Basic JWT Validation (Inline JWKS)

{
  "jwks": {
    "keys": [
      {
        "kty": "RSA",
        "kid": "my-key-id",
        "use": "sig",
        "alg": "RS256",
        "n": "xGOr-H7A-PWH_4...",
        "e": "AQAB"
      }
    ]
  },
  "algorithms": ["RS256"]
}

Basic JWT Validation (JWKS URI)

{
  "jwksUri": "https://auth.example.com/.well-known/jwks.json",
  "algorithms": ["RS256"]
}

Token Introspection with Caching

{
  "introspectEndpoint": "https://auth.example.com/oauth/introspect",
  "introspectCacheMaxAge": 300,
  "clockTolerance": 5
}

Required Claims Validation

{
  "jwksUri": "https://auth.example.com/.well-known/jwks.json",
  "requiredClaims": ["sub", "email", "tenant_id"]
}

Issuer and Audience Validation

{
  "jwksUri": "https://auth.example.com/.well-known/jwks.json",
  "claimValues": {
    "iss": {
      "values": "https://auth.example.com"
    },
    "aud": {
      "values": ["https://api.example.com"],
      "matchType": "contains"
    }
  }
}

Group/Role Validation (OR logic)

{
  "jwksUri": "https://auth.example.com/.well-known/jwks.json",
  "claimValues": {
    "groups": {
      "values": ["admin", "moderator"],
      "matchType": "contains"
    }
  }
}

Scope Validation (AND logic)

{
  "jwksUri": "https://auth.example.com/.well-known/jwks.json",
  "claimValues": {
    "scope": {
      "values": ["read:api", "write:api"],
      "matchType": "containsAll"
    }
  }
}

Multi-Tenant Validation

{
  "jwksUri": "https://auth.example.com/.well-known/jwks.json",
  "requiredClaims": ["tenant_id"],
  "claimValues": {
    "tenant_id": {
      "values": ["tenant-123", "tenant-456", "tenant-789"],
      "matchType": "contains"
    }
  }
}

Email Domain Validation

{
  "jwksUri": "https://auth.example.com/.well-known/jwks.json",
  "claimValues": {
    "email": {
      "values": ".*@(company1|company2)\\.com$",
      "matchType": "regex"
    }
  }
}

Claim Extraction to Context

Extracts validated JWT claims and injects them as headers for downstream services:

{
  "jwksUri": "https://auth.example.com/.well-known/jwks.json",
  "extractClaims": ["sub", "email", "tenant_id", "groups"],
  "claimPrefix": "x-jwt-"
}

Result: Claims are extracted and added as headers:

x-jwt-sub: user-123
x-jwt-email: [email protected]
x-jwt-tenant-id: tenant-456
x-jwt-groups: admin,developer

Comprehensive Production Setup

{
  "jwksUri": "https://auth.example.com/.well-known/jwks.json",
  "algorithms": ["RS256", "ES256"],
  "cacheMaxAge": 86400,
  "clockTolerance": 5,
  "maxTokenAge": "1d",
  "requiredClaims": ["sub", "email", "tenant_id"],
  "claimValues": {
    "iss": {
      "values": "https://auth.example.com"
    },
    "aud": {
      "values": "https://api.example.com",
      "matchType": "contains"
    },
    "tenant_id": {
      "values": ["tenant-123", "tenant-456"],
      "matchType": "contains"
    },
    "groups": {
      "values": ["admin", "developer"],
      "matchType": "contains"
    },
    "scope": {
      "values": ["read:api", "write:api"],
      "matchType": "containsAll"
    },
    "email": {
      "values": ".*@(company1|company2)\\.com$",
      "matchType": "regex"
    }
  },
  "headerPayloadMatch": ["kid"],
  "extractClaims": ["sub", "email", "tenant_id", "groups", "scope"],
  "claimPrefix": "x-jwt-"
}

Response Format

Success Response

{
  "error": null,
  "verdict": true,
  "data": {
    "verdict": true,
    "explanation": "JWT token validation succeeded",
    "validations": {
      "signatureValid": true,
      "requiredClaims": { "valid": true },
      "claimValues": { "valid": true },
      "headerPayloadMatch": { "valid": true }
    }
  },
  "transformedData": {
    "headers": {
      "x-jwt-sub": "user-123",
      "x-jwt-email": "[email protected]",
      "x-jwt-tenant-id": "tenant-456"
    }
  },
  "transformed": true
}

Failure Response

{
  "error": null,
  "verdict": false,
  "data": {
    "verdict": false,
    "explanation": "JWT validation failed: Missing required claims: email, tenant_id; Invalid claim values: groups",
    "validations": {
      "signatureValid": true,
      "requiredClaims": {
        "valid": false,
        "missing": ["email", "tenant_id"]
      },
      "claimValues": {
        "valid": false,
        "failed": ["groups"]
      }
    }
  }
}

Token Format

The guardrail expects JWT tokens in the following format:

Authorization: Bearer <JWT_TOKEN>

Or with a custom header:

X-API-Token: Bearer <JWT_TOKEN>

The Bearer prefix is optional and will be automatically stripped if present.

Common Patterns

API Gateway Authentication

{
  "jwksUri": "https://auth.example.com/.well-known/jwks.json",
  "requiredClaims": ["sub"],
  "claimValues": {
    "iss": { "values": "https://auth.example.com" },
    "aud": { "values": "https://api.example.com", "matchType": "contains" }
  }
}

Admin-Only Access

{
  "jwksUri": "https://auth.example.com/.well-known/jwks.json",
  "claimValues": {
    "groups": {
      "values": ["admin"],
      "matchType": "contains"
    }
  }
}

Tenant Isolation

{
  "jwksUri": "https://auth.example.com/.well-known/jwks.json",
  "requiredClaims": ["tenant_id"],
  "claimValues": {
    "tenant_id": {
      "values": ["<SPECIFIC_TENANT_ID>"]
    }
  }
}

Service-to-Service Authentication

{
  "jwksUri": "https://auth.example.com/.well-known/jwks.json",
  "requiredClaims": ["client_id"],
  "claimValues": {
    "scope": {
      "values": ["service:read", "service:write"],
      "matchType": "containsAll"
    }
  }
}

Best Practices

Security

Always validate the issuer (iss) to prevent token substitution attacks
Validate the audience (aud) to ensure tokens are intended for your API
Use appropriate clockTolerance (5-10 seconds) to handle clock skew
Set reasonable maxTokenAge to limit token lifetime
Enable headerPayloadMatch for kid to prevent key confusion attacks

Performance

Set appropriate cacheMaxAge (default 24h) to reduce JWKS fetches
Inline JWKS provides the fastest validation (no external calls)
Use introspection caching when using token introspection endpoint

Multi-Tenancy

Always include tenant_id in requiredClaims
Validate tenant_id values explicitly
Consider adding tenant-specific JWKS URIs for larger deployments

Claim Extraction

Only extract claims needed by downstream services
Use consistent claimPrefix across your infrastructure
Be mindful of header size limits when extracting large claims
Extracted claims are only added if validation succeeds

Troubleshooting

Token Not Found

Missing authorization header

Ensure the token is sent in the correct header (Authorization by default).

Invalid Signature

JWT signature validation error: ...

Verify your JWKS URI is correct and the token was signed by the expected issuer.

Missing Claims

JWT validation failed: Missing required claims: email, tenant_id

Ensure your auth provider includes these claims in the token.

Invalid Claim Values

JWT validation failed: Invalid claim values: groups

Check that the claim values in your token match the expected values in your configuration.

Clock Skew Issues

JWT signature validation error: token is expired

Increase clockTolerance to handle clock differences between systems.

Ecosystem

LLM Integrations

Cloud Platforms

Guardrails

Plugins

Vector Databases

Agents

AI Apps

Libraries

Tracing Providers

MCP Clients

MCP Servers

​Features

​Validation Methods

​Configuration Parameters

​Core Parameters

​JWKS Validation Parameters

​Token Introspection Parameters

​Claim Validation Parameters

​Match Types

​exact (default)

​contains

​containsAll

​regex

​Quick Reference

​Usage Examples

​Basic JWT Validation (Inline JWKS)

​Basic JWT Validation (JWKS URI)

​Token Introspection with Caching

​Required Claims Validation

​Issuer and Audience Validation

​Group/Role Validation (OR logic)

​Scope Validation (AND logic)

​Multi-Tenant Validation

​Email Domain Validation

​Claim Extraction to Context

​Comprehensive Production Setup

​Response Format

​Success Response

​Failure Response

​Token Format

​Common Patterns

​API Gateway Authentication

​Admin-Only Access

​Tenant Isolation

​Service-to-Service Authentication

​Best Practices

​Security

​Performance

​Multi-Tenancy

​Claim Extraction

​Troubleshooting

​Token Not Found

​Invalid Signature

​Missing Claims

​Invalid Claim Values

​Clock Skew Issues