rm noise
This commit is contained in:
Olivier Chafik
parent
6e4fc52c7e
commit
ec0c50425e
2 changed files with 0 additions and 236 deletions
125
CLAUDE.local.md
125
CLAUDE.local.md
|
|
@ -1,125 +0,0 @@
|
|||
# RFC 8707 Resource Indicators Implementation for MCP TypeScript SDK
|
||||
|
||||
This PR implements RFC 8707 (Resource Indicators for OAuth 2.0) in the MCP TypeScript SDK, addressing critical security vulnerabilities and adding resource-scoped authorization support.
|
||||
|
||||
## Issues Addressed
|
||||
|
||||
- **Fixes #592**: Implements client-side resource parameter passing to prevent token confusion attacks
|
||||
- **Related to #635**: Demonstrates server-side RFC 8707 validation in the demo OAuth provider
|
||||
|
||||
## Overview
|
||||
|
||||
This implementation adds resource parameter support to MCP's OAuth flow, explicitly binding access tokens to specific MCP servers. This prevents malicious servers from stealing OAuth tokens intended for other services.
|
||||
|
||||
## Implementation Summary
|
||||
|
||||
### 1. Core Auth Infrastructure
|
||||
|
||||
#### Client-Side Changes (`src/client/`)
|
||||
- **auth.ts**: Added resource parameter support to authorization and token exchange flows
|
||||
- **Transport layers** (sse.ts, streamableHttp.ts): Automatically extract canonical server URIs for resource parameter
|
||||
|
||||
#### Server-Side Changes (`src/server/auth/`)
|
||||
- **handlers/**: Updated authorize and token handlers to accept and pass through resource parameters
|
||||
- **provider.ts**: Extended provider interface to support resource parameters
|
||||
- **errors.ts**: Added `InvalidTargetError` for RFC 8707 compliance
|
||||
|
||||
#### Shared Utilities (`src/shared/`)
|
||||
- **auth-utils.ts**: Created utilities for resource URI validation and canonicalization
|
||||
- **auth.ts**: Updated OAuth schemas to include resource parameter
|
||||
|
||||
### 2. Demo OAuth Provider Enhancement (`src/examples/server/`)
|
||||
|
||||
The demo provider demonstrates how to implement RFC 8707 validation:
|
||||
- Optional resource validation during authorization (via `DemoOAuthProviderConfig`)
|
||||
- Resource consistency checks during token exchange
|
||||
- Resource information included in token introspection
|
||||
- Support for validating resources against a configured server URL
|
||||
- Client-specific resource allowlists
|
||||
|
||||
### 3. Resource URI Requirements
|
||||
|
||||
Resource URIs follow RFC 8707 requirements:
|
||||
- **MUST NOT** include fragments (automatically removed by the SDK)
|
||||
- The SDK preserves all other URL components (scheme, host, port, path, query) exactly as provided
|
||||
- No additional canonicalization is performed to maintain compatibility with various server configurations
|
||||
|
||||
## Client vs Server Implementation Differences
|
||||
|
||||
### Client-Side Implementation
|
||||
- **Automatic resource extraction**: Transports automatically determine the server URI for resource parameter
|
||||
- **Transparent integration**: Resource parameter is added without changing existing auth APIs
|
||||
- **Fragment removal**: Fragments are automatically removed from URIs per RFC 8707
|
||||
- **Focus**: Ensuring resource parameter is correctly included in all OAuth requests
|
||||
|
||||
### Server-Side Implementation
|
||||
- **Core handlers**: Pass through resource parameter without validation
|
||||
- **Demo provider**: Shows how to implement resource validation
|
||||
- **Provider flexibility**: Auth providers decide how to enforce resource restrictions
|
||||
- **Backward compatibility**: Servers work with clients that don't send resource parameter
|
||||
- **Focus**: Demonstrating best practices for resource validation
|
||||
|
||||
## Testing Approach Differences
|
||||
|
||||
### Client-Side Tests
|
||||
- **Unit tests**: Verify resource parameter is included in auth URLs and token requests
|
||||
- **Validation tests**: Ensure resource URI validation and canonicalization work correctly
|
||||
- **Integration focus**: Test interaction between transport layer and auth module
|
||||
|
||||
### Server-Side Tests
|
||||
- **Handler tests**: Verify resource parameter is accepted and passed to providers
|
||||
- **Demo provider tests**: Comprehensive tests for server URL validation and client-specific allowlists
|
||||
- **Security tests**: Verify invalid resources are rejected with proper errors
|
||||
- **Configuration tests**: Test various demo provider configurations
|
||||
- **End-to-end tests**: Full OAuth flow with resource validation
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Token Binding**: Tokens are explicitly bound to the resource they're intended for
|
||||
2. **Validation**: Both client and server validate resource URIs to prevent attacks
|
||||
3. **Consistency**: Resource must match between authorization and token exchange
|
||||
4. **Introspection**: Resource information is included in token introspection responses
|
||||
|
||||
## Migration Guide
|
||||
|
||||
### For Client Developers
|
||||
No changes required - the SDK automatically includes the resource parameter based on the server URL.
|
||||
|
||||
### For Server Developers
|
||||
1. Core server handlers automatically pass through the resource parameter
|
||||
2. Custom auth providers can implement resource validation as shown in the demo provider
|
||||
3. Demo provider configuration options:
|
||||
- `serverUrl`: The canonical URL of the MCP server
|
||||
- `validateResourceMatchesServer`: Enable strict resource validation
|
||||
4. Return `invalid_target` error for unauthorized resources
|
||||
5. Include resource in token introspection responses
|
||||
|
||||
## Example Usage
|
||||
|
||||
```typescript
|
||||
// Client automatically includes resource parameter
|
||||
const transport = new StreamableHttpClientTransport(
|
||||
'https://api.example.com/mcp',
|
||||
authProvider
|
||||
);
|
||||
|
||||
// Demo provider configuration with resource validation
|
||||
const demoProviderConfig = {
|
||||
serverUrl: 'https://api.example.com/mcp',
|
||||
validateResourceMatchesServer: true // Makes resource required and validates it
|
||||
};
|
||||
const provider = new DemoInMemoryAuthProvider(demoProviderConfig);
|
||||
```
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
1. Add support for multiple resource parameters (RFC 8707 allows arrays)
|
||||
2. Implement resource-specific scope restrictions
|
||||
3. Add telemetry for resource parameter usage
|
||||
4. Create migration tooling for existing deployments
|
||||
|
||||
## References
|
||||
|
||||
- [RFC 8707 - Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)
|
||||
- [OAuth 2.0 Security Best Current Practice](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics)
|
||||
- [MCP Issue #544 - Security Vulnerability](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/544)
|
||||
|
|
@ -1,111 +0,0 @@
|
|||
# RFC 8707 Resource Indicators Implementation
|
||||
|
||||
<!-- Provide a brief summary of your changes -->
|
||||
Implements RFC 8707 (Resource Indicators for OAuth 2.0) support in the MCP TypeScript SDK. This adds the `resource` parameter to OAuth authorization and token exchange flows, allowing access tokens to be explicitly bound to specific MCP servers. The implementation includes automatic resource extraction in client transports, server-side parameter passing, and demonstrates resource validation in the demo OAuth provider.
|
||||
|
||||
(Fixes #592, Related to #635)
|
||||
|
||||
## Motivation and Context
|
||||
<!-- Why is this change needed? What problem does it solve? -->
|
||||
This change addresses critical security vulnerabilities identified in https://github.com/modelcontextprotocol/modelcontextprotocol/issues/544. Without resource indicators, OAuth tokens intended for one MCP server could be stolen and misused by malicious servers. RFC 8707 prevents these token confusion attacks by explicitly binding tokens to their intended resources.
|
||||
|
||||
Key problems solved:
|
||||
- Prevents token theft/confusion attacks where a malicious MCP server steals tokens meant for other services
|
||||
- Enables fine-grained access control by restricting OAuth clients to specific resources
|
||||
- Improves security posture by following OAuth 2.0 Security Best Current Practice recommendations
|
||||
|
||||
## How Has This Been Tested?
|
||||
<!-- Have you tested this in a real application? Which scenarios were tested? -->
|
||||
Comprehensive test coverage has been added:
|
||||
|
||||
**Client-side testing:**
|
||||
- Unit tests verify resource parameter inclusion in authorization URLs and token requests (512 new lines in auth.test.ts)
|
||||
- Transport layer tests ensure automatic resource extraction works correctly
|
||||
- Fragment removal and URI validation tests
|
||||
|
||||
**Server-side testing:**
|
||||
- Authorization handler tests for resource parameter acceptance
|
||||
- Token handler tests for resource parameter passing
|
||||
- Demo provider tests for resource restrictions and validation (including server URL validation)
|
||||
- Proxy provider tests for resource parameter forwarding
|
||||
|
||||
**Integration testing:**
|
||||
- End-to-end OAuth flow with resource validation
|
||||
- Resource validation example demonstrating real-world usage patterns
|
||||
- Tests for both clients with and without resource restrictions
|
||||
|
||||
## Breaking Changes
|
||||
|
||||
While the change is breaking at a protocol level, it should not require code changes from SDK users (just SDK version bumping).
|
||||
|
||||
- **Client developers**: No code changes required. The SDK automatically extracts and includes the resource parameter from the server URL
|
||||
- **Server developers**: The core server handlers now pass through the resource parameter. Resource validation is demonstrated in the demo provider but remains optional for custom providers
|
||||
- **Auth providers**: Should be updated to accept and handle the resource parameter. The demo provider shows how to implement server URL validation and client-specific resource restrictions
|
||||
|
||||
## Types of changes
|
||||
<!-- What types of changes does your code introduce? Put an `x` in all the boxes that apply: -->
|
||||
- [x] Bug fix (non-breaking change which fixes an issue)
|
||||
- [x] New feature (non-breaking change which adds functionality)
|
||||
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
|
||||
- [ ] Documentation update
|
||||
|
||||
## Checklist
|
||||
<!-- Go over all the following points, and put an `x` in all the boxes that apply. -->
|
||||
- [x] I have read the [MCP Documentation](https://modelcontextprotocol.io)
|
||||
- [x] My code follows the repository's style guidelines
|
||||
- [x] New and existing tests pass locally
|
||||
- [x] I have added appropriate error handling
|
||||
- [x] I have added or updated documentation as needed
|
||||
|
||||
## Additional context
|
||||
<!-- Add any other context, implementation notes, or design decisions -->
|
||||
|
||||
### Server-Side Implementation Approach
|
||||
|
||||
The core server implementation focuses on passing through the resource parameter without enforcing validation, maintaining backward compatibility and flexibility. The demo provider demonstrates how to implement RFC 8707 validation:
|
||||
|
||||
1. **Core Server**: Handlers accept and forward the resource parameter to auth providers without validation
|
||||
2. **Demo Provider**: Shows how to implement comprehensive resource validation including:
|
||||
- Server URL matching validation (configurable via `DemoOAuthProviderConfig`)
|
||||
- Client-specific resource allowlists
|
||||
- Warning logs for missing resource parameters
|
||||
- Consistent resource validation between authorization and token exchange
|
||||
|
||||
This separation allows:
|
||||
- Existing providers to continue working without modification
|
||||
- New providers to implement validation according to their security requirements
|
||||
- Gradual migration to RFC 8707 compliance
|
||||
- Different validation strategies for different deployment scenarios
|
||||
|
||||
### Implementation Approach
|
||||
|
||||
Resource URIs are used as-is with only fragment removal (per RFC requirement). This allows having different MCP servers under different subpaths (even w/ different query URLs) w/o sharing spilling their resource authorization to each other (to allow a variety of MCP server federation use cases).
|
||||
|
||||
### Key Components Added
|
||||
1. **Shared utilities** (`auth-utils.ts`): Resource URI handling and validation
|
||||
2. **Client auth** modifications: Resource parameter support in authorization/token flows
|
||||
3. **Transport layers**: Automatic resource extraction from server URLs
|
||||
4. **Server handlers**: Resource parameter acceptance and forwarding
|
||||
5. **Demo provider**: Full RFC 8707 implementation with resource validation
|
||||
6. **Error handling**: New `InvalidTargetError` for RFC 8707 compliance
|
||||
|
||||
### Example Usage
|
||||
```typescript
|
||||
// Client-side (automatic)
|
||||
const transport = new StreamableHttpClientTransport(
|
||||
'https://api.example.com/mcp',
|
||||
authProvider
|
||||
);
|
||||
|
||||
// Demo provider configuration with validation
|
||||
const demoProviderConfig = {
|
||||
serverUrl: 'https://api.example.com/mcp',
|
||||
validateResourceMatchesServer: true // Makes resource required and validates it matches serverUrl
|
||||
};
|
||||
const provider = new DemoInMemoryAuthProvider(demoProviderConfig);
|
||||
```
|
||||
|
||||
### References
|
||||
- [RFC 8707 - Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)
|
||||
- Fixes #592: OAuth token confusion vulnerability - client-side resource parameter support
|
||||
- Related to #635: Demonstrates server-side RFC 8707 validation in demo provider
|
||||
Loading…
Reference in a new issue