Skip to main content

​
fastmcp.server.auth.jwt_issuer

JWT token issuance and verification for FastMCP OAuth Proxy. This module implements the token factory pattern for OAuth proxies, where the proxy issues its own JWT tokens to clients instead of forwarding upstream provider tokens. This maintains proper OAuth 2.0 token audience boundaries.

​
Functions

​
derive_jwt_key

Derive JWT signing key from a high-entropy or low-entropy key material and server salt.

​
Classes

​
JWTIssuer

Issues and validates FastMCP-signed JWT tokens using HS256. This issuer creates JWT tokens for MCP clients with proper audience claims, maintaining OAuth 2.0 token boundaries. Tokens are signed with HS256 using a key derived from the upstream client secret. Methods:

​
issue_access_token

Issue a minimal FastMCP access token. FastMCP tokens are reference tokens containing only the minimal claims needed for validation and lookup. The JTI maps to the upstream token which contains actual user identity and authorization data. Args:
  • client_id: MCP client ID
  • scopes: Token scopes
  • jti: Unique token identifier (maps to upstream token)
  • expires_in: Token lifetime in seconds
  • upstream_claims: Optional claims from upstream IdP token to include
  • subject: Optional sub claim. Set for self-contained tokens (e.g. minted from an ID-JAG) where the subject is carried directly in the token rather than looked up via a JTI mapping.
  • extra_claims: Optional additional top-level claims to embed. Used to mark self-contained tokens (e.g. the ID-JAG issuer/marker) so load_access_token can validate them without a JTI mapping.
Returns:
  • Signed JWT token

​
issue_refresh_token

Issue a minimal FastMCP refresh token. FastMCP refresh tokens are reference tokens containing only the minimal claims needed for validation and lookup. The JTI maps to the upstream token which contains actual user identity and authorization data. Args:
  • client_id: MCP client ID
  • scopes: Token scopes
  • jti: Unique token identifier (maps to upstream token)
  • expires_in: Token lifetime in seconds (should match upstream refresh expiry)
  • upstream_claims: Optional claims from upstream IdP token to include
Returns:
  • Signed JWT token

​
verify_token

Verify and decode a FastMCP token. Validates JWT signature, expiration, issuer, audience, and token type. Args:
  • token: JWT token to verify
  • expected_token_use: Expected token type (“access” or “refresh”). Defaults to “access”, which rejects refresh tokens.
Returns:
  • Decoded token payload
Raises:
  • JoseError: If token is invalid, expired, or has wrong claims