Crate turul_mcp_oauth 

OAuth 2.1 Resource Server support for Turul MCP framework

This crate provides OAuth 2.1 Bearer token validation for MCP servers acting as Resource Servers (RS). It does NOT implement an Authorization Server — tokens are validated against an external AS via JWKS.

Authorization-role posture (MCP 2026-07-28)

The MCP authorization spec assigns requirements per OAuth role. This crate implements the resource-server role only:

• RFC 9728 Protected Resource Metadata (/.well-known/oauth-protected-resource) — the RS MUST — via ProtectedResourceMetadata / WellKnownOAuthHandler.
• OAuth 2.1 §5.2 access-token validation with RFC 8707 audience binding — via JwtValidator / OAuthResourceMiddleware.

Client ID Metadata Documents (CIMD, draft-ietf-oauth-client-id-metadata-document-00) are a SHOULD for authorization servers and MCP clients — client registration never involves the resource server, so no CIMD surface belongs in this crate. Applications embedding an AS or building a full MCP OAuth client implement CIMD there.

Dynamic Client Registration (RFC 7591) is deprecated upstream (MAY, retained for AS back-compat; not removed — earliest removal 2027-07-28) and is likewise an AS/client concern. This crate has never implemented a DCR surface and does not add one.

Architecture

• OAuthResourceMiddleware — Pre-session middleware that validates Bearer tokens and injects claims into request extensions
• JwtValidator — JWT validation with JWKS caching and kid-miss refresh. Owned by turul_jwt_validator and re-exported here
• hardened_validator — builds a JwtValidator with this crate’s key max-age, stale window and fetch retry, and rejects a non-loopback plaintext jwks_uri. The bare constructor leaves all of those disabled
• ProtectedResourceMetadata — RFC 9728 metadata document
• WellKnownOAuthHandler — Route handler for /.well-known/oauth-protected-resource

Usage

use std::sync::Arc;
use turul_mcp_oauth::{
    JwtValidator, OAuthResourceMiddleware, ProtectedResourceMetadata,
    WellKnownOAuthHandler, oauth_resource_server,
};

let metadata = ProtectedResourceMetadata::new(
    "https://example.com/mcp",
    vec!["https://auth.example.com".to_string()],
).unwrap();

let (auth_middleware, routes) = oauth_resource_server(
    metadata,
    "https://auth.example.com/.well-known/jwks.json",
).unwrap();

// Register with McpServer::builder()
//   let mut builder = McpServer::builder().middleware(auth_middleware);
//   for (path, handler) in routes {
//       builder = builder.route(&path, handler);
//   }

Re-exports

pub use error::OAuthError;

pub use jwt::hardened_validator;

pub use metadata::ProtectedResourceMetadata;

pub use middleware::OAuthResourceMiddleware;

pub use well_known::WellKnownOAuthHandler;

Modules

error

OAuth error types

jwt

JWT validation for OAuth 2.1 Resource Server.

metadata

RFC 9728 Protected Resource Metadata

middleware

OAuth Resource Server middleware

well_known

.well-known/oauth-protected-resource route handler

Structs

JwtValidator

JWT validator with JWKS caching and kid-miss refresh.

TokenClaims

Validated token claims extracted from a JWT.

Enums

Algorithm

Re-exported so callers can name algorithms for JwtValidator::with_algorithms without adding their own jsonwebtoken dependency. It appears in that method’s signature either way, so importing it here is what makes the method callable rather than what creates the coupling. Must track the same jsonwebtoken major as turul-jwt-validator. The algorithms supported for signing/verifying JWTs

JwksFetchErrorKind

Categorized cause of a JWKS fetch failure.

JwtValidationError

Errors from JWT validation.

Functions

oauth_resource_server

Convenience function to create both the OAuth middleware and well-known route handlers

Type Aliases

RouteEntry

A route entry: (path, handler) pair for registration with the server builder.