afb8a905e5
1.add oauth2 server and client example 2.add oauth2 impl in sse 3.add auth doc Signed-off-by: jokemanfire <hu.dingyang@zte.com.cn>
125 lines
No EOL
4.4 KiB
Markdown
125 lines
No EOL
4.4 KiB
Markdown
# Model Context Protocol OAuth Authorization
|
|
|
|
This document describes the OAuth 2.1 authorization implementation for Model Context Protocol (MCP), following the [MCP 2025-03-26 Authorization Specification](https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/authorization/).
|
|
|
|
## Features
|
|
|
|
- Full support for OAuth 2.1 authorization flow
|
|
- PKCE support for enhanced security
|
|
- Authorization server metadata discovery
|
|
- Dynamic client registration
|
|
- Automatic token refresh
|
|
- Authorized SSE transport implementation
|
|
- Authorized HTTP Client implementation
|
|
## Usage Guide
|
|
|
|
### 1. Enable Features
|
|
|
|
Enable the auth feature in Cargo.toml:
|
|
|
|
```toml
|
|
[dependencies]
|
|
rmcp = { version = "0.1", features = ["auth", "transport-sse"] }
|
|
```
|
|
|
|
### 2. Use OAuthState
|
|
|
|
```rust ignore
|
|
// Initialize oauth state machine
|
|
let mut oauth_state = OAuthState::new(&server_url, None)
|
|
.await
|
|
.context("Failed to initialize oauth state machine")?;
|
|
oauth_state
|
|
.start_authorization(&["mcp", "profile", "email"], MCP_REDIRECT_URI)
|
|
.await
|
|
.context("Failed to start authorization")?;
|
|
|
|
```
|
|
|
|
### 3. Get authorization url and do callback
|
|
|
|
```rust ignore
|
|
// Get authorization URL and guide user to open it
|
|
let auth_url = oauth_state.get_authorization_url().await?;
|
|
println!("Please open the following URL in your browser for authorization:\n{}", auth_url);
|
|
|
|
// Handle callback - In real applications, this is typically done in a callback server
|
|
let auth_code = "Authorization code obtained from browser after user authorization";
|
|
let credentials = oauth_state.handle_callback(auth_code).await?;
|
|
|
|
println!("Authorization successful, access token: {}", credentials.access_token);
|
|
|
|
```
|
|
|
|
### 4. Use Authorized SSE Transport and create client
|
|
|
|
```rust ignore
|
|
let transport =
|
|
match create_authorized_transport(MCP_SSE_URL.to_string(), oauth_state, Some(retry_config))
|
|
.await
|
|
{
|
|
Ok(t) => t,
|
|
Err(e) => {
|
|
tracing::error!("Failed to create authorized transport: {}", e);
|
|
return Err(anyhow::anyhow!("Connection failed: {}", e));
|
|
}
|
|
};
|
|
|
|
// Create client and connect to MCP server
|
|
let client_service = ClientInfo::default();
|
|
let client = client_service.serve(transport).await?;
|
|
```
|
|
|
|
### 5. May you can use Authorized HTTP Client after authorized
|
|
|
|
```rust ignore
|
|
let client = oauth_state.to_authorized_http_client().await?;
|
|
```
|
|
|
|
## Complete Example
|
|
client: Please refer to `examples/clients/src/oauth_client.rs` for a complete usage example.
|
|
server: Please refer to `examples/servers/src/mcp_oauth_server.rs` for a complete usage example.
|
|
### Running the Example in server
|
|
```bash
|
|
# Run example
|
|
cargo run --example mcp_oauth_server
|
|
```
|
|
|
|
### Running the Example in client
|
|
|
|
```bash
|
|
# Run example
|
|
cargo run --example oauth-client
|
|
```
|
|
|
|
## Authorization Flow Description
|
|
|
|
1. **Metadata Discovery**: Client attempts to get authorization server metadata from `/.well-known/oauth-authorization-server`
|
|
2. **Client Registration**: If supported, client dynamically registers itself
|
|
3. **Authorization Request**: Build authorization URL with PKCE and guide user to access
|
|
4. **Authorization Code Exchange**: After user authorization, exchange authorization code for access token
|
|
5. **Token Usage**: Use access token for API calls
|
|
6. **Token Refresh**: Automatically use refresh token to get new access token when current one expires
|
|
|
|
## Security Considerations
|
|
|
|
- All tokens are securely stored in memory
|
|
- PKCE implementation prevents authorization code interception attacks
|
|
- Automatic token refresh support reduces user intervention
|
|
- Only accepts HTTPS connections or secure local callback URIs
|
|
|
|
## Troubleshooting
|
|
|
|
If you encounter authorization issues, check the following:
|
|
|
|
1. Ensure server supports OAuth 2.1 authorization
|
|
2. Verify callback URI matches server's allowed redirect URIs
|
|
3. Check network connection and firewall settings
|
|
4. Verify server supports metadata discovery or dynamic client registration
|
|
|
|
## References
|
|
|
|
- [MCP Authorization Specification](https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/authorization/)
|
|
- [OAuth 2.1 Specification Draft](https://oauth.net/2.1/)
|
|
- [RFC 8414: OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414)
|
|
- [RFC 7591: OAuth 2.0 Dynamic Client Registration Protocol](https://datatracker.ietf.org/doc/html/rfc7591) |