Add OAuth 2.1 Authorization Support per MCP Specification

[itsbalamurali]

Implement OAuth 2.1 authorization support for poem-mcpserver as specified in the
https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization.

Background

The Model Context Protocol (MCP) specification defines authorization capabilities for HTTP-based
transports, enabling MCP clients to make requests to restricted MCP servers on behalf of
resource owners. This is based on OAuth 2.1 and related RFCs.

Requirements

According to the MCP specification, protected MCP servers (resource servers) MUST implement:

1. OAuth 2.0 Protected Resource Metadata (https://datatracker.ietf.org/doc/html/rfc9728)

• Serve metadata at /.well-known/oauth-protected-resource
• Include authorization_servers field with at least one authorization server URL
• Return WWW-Authenticate header on HTTP 401 responses indicating resource metadata URL

2. Access Token Validation

• Validate access tokens per
  https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#section-5.2
• Accept tokens via Authorization: Bearer header only (NOT query parameters)
• Validate token audience matches this server per
  https://www.rfc-editor.org/rfc/rfc8707.html#section-2
• Return HTTP 401 for invalid/expired tokens
• Return HTTP 403 for valid tokens with insufficient permissions

3. Error Responses

Status Code	Usage
401 Unauthorized	Authorization required or token invalid
403 Forbidden	Invalid scopes or insufficient permissions
400 Bad Request	Malformed authorization request

Proposed Implementation

The implementation should provide:

1. Extractor for validating Bearer tokens on incoming requests and inject to tool methods.
2. Configuration for specifying:
   - Authorization server URL(s)
   - Token validation endpoint or JWT validation keys
   - Resource identifier (canonical URI of this MCP server)
3. Protected Resource Metadata endpoint at /.well-known/oauth-protected-resource
4. WWW-Authenticate header handling on 401 responses

  use poem_mcpserver::oauth::{OAuthConfig, ProtectedResource};

  let oauth_config = OAuthConfig::new()
      .authorization_server("https://auth.example.com")
      .resource_uri("https://mcp.example.com")
      .token_validation(TokenValidation::Jwt {
          jwks_url: "https://auth.example.com/.well-known/jwks.json"
      });

      OAuthProtection::new(oauth_config);

Standards Compliance

Implementation should follow these specifications (subset of features for
security/interoperability):

• OAuth 2.1 IETF DRAFT (https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13)
• OAuth 2.0 Protected Resource Metadata (https://datatracker.ietf.org/doc/html/rfc9728)
• Resource Indicators for OAuth 2.0 (https://www.rfc-editor.org/rfc/rfc8707.html)

Benefits

• Enable secure, multi-tenant MCP servers
• Standard OAuth 2.1 integration for enterprise environments
• Support for various authorization servers (Auth0, Okta, Keycloak, etc.)
• Proper token audience validation to prevent token misuse
• Compliance with MCP specification

References

• https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization
• https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices

[milesgranger]

+1 for this! :)