Skip to content

Commit ff81f2f

Browse files
jbajba
authored
docs: add auth and security sections (#492)
For #442.
1 parent 1696b59 commit ff81f2f

File tree

2 files changed

+121
-4
lines changed

2 files changed

+121
-4
lines changed

‎docs/protocol.md‎

Lines changed: 63 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,12 @@
88
1. [Custom transports](#custom-transports)
99
1. [Concurrency](#concurrency)
1010
1. [Authorization](#authorization)
11+
1. [Server](#server)
12+
1. [Client](#client)
1113
1. [Security](#security)
14+
1. [Confused Deputy](#confused-deputy)
15+
1. [Token Passthrough](#token-passthrough)
16+
1. [Session Hijacking](#session-hijacking)
1217
1. [Utilities](#utilities)
1318
1. [Cancellation](#cancellation)
1419
1. [Ping](#ping)
@@ -232,11 +237,67 @@ for more background.
232237

233238
## Authorization
234239

235-
<!-- TODO -->
240+
### Server
241+
242+
To write an MCP server that performs authorization,
243+
use [`RequireBearerToken`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#RequireBearerToken).
244+
This function is middleware that wraps an HTTP handler, such as the one returned
245+
by [`NewStreamableHTTPHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#NewStreamableHTTPHandler), to provide support for verifying bearer tokens.
246+
The middleware function checks every request for an Authorization header with a bearer token,
247+
and invokes the
248+
[`TokenVerifier`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#TokenVerifier)
249+
passed to `RequireBearerToken` to parse the token and perform validation.
250+
The middleware function checks expiration and scopes (if they are provided in
251+
[`RequireBearerTokenOptions.Scopes`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#RequireBearerTokenOptions.Scopes)), so the
252+
`TokenVerifer` doesn't have to.
253+
If [`RequireBearerTokenOptions.ResourceMetadataURL`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#RequireBearerTokenOptions.ResourceMetadataURL) is set and verification fails,
254+
the middleware function sets the WWW-Authenticate header as required by the [Protected Resource
255+
Metadata spec](https://datatracker.ietf.org/doc/html/rfc9728).
256+
257+
The [_auth middleware example_](https://github.com/modelcontextprotocol/go-sdk/tree/main/examples/server/auth-middleware) shows how to implement authorization for both JWT tokens and API keys.
258+
259+
### Client
260+
261+
Client-side OAuth is implemented by setting
262+
[`StreamableClientTransport.HTTPClient`](https://pkg.go.dev/github.com/modelcontextprotocol/[email protected]/mcp#StreamableClientTransport.HTTPClient) to a custom [`http.Client`](https://pkg.go.dev/net/http#Client)
263+
Additional support is forthcoming; see #493.
236264

237265
## Security
238266

239-
<!-- TODO -->
267+
Here we discuss the mitigations described under
268+
the MCP spec's [Security Best Practices](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices) section, and how we handle them.
269+
270+
### Confused Deputy
271+
272+
The [mitigation](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices#mitigation), obtaining user consent for dynamically registered clients,
273+
happens on the MCP client. At present we don't provide client-side OAuth support.
274+
275+
276+
### Token Passthrough
277+
278+
The [mitigation](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices#mitigation-2), accepting only tokens that were issued for the server, depends on the structure
279+
of tokens and is the responsibility of the
280+
[`TokenVerifier`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#TokenVerifier)
281+
provided to
282+
[`RequireBearerToken`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#RequireBearerToken).
283+
284+
### Session Hijacking
285+
286+
The [mitigations](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices#mitigation-3) are as follows:
287+
288+
- _Verify all inbound requests_. The [`RequireBearerToken`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#RequireBearerToken)
289+
middleware function will verify all HTTP requests that it receives. It is the
290+
user's responsibility to wrap that function around all handlers in their server.
291+
292+
- _Secure session IDs_. This SDK generates cryptographically secure session IDs by default.
293+
If you create your own with
294+
[`ServerOptions.GetSessionID`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ServerOptions.GetSessionID), it is your responsibility to ensure they are secure.
295+
If you are using Go 1.24 or above,
296+
we recommend using [`crypto/rand.Text`](https://pkg.go.dev/crypto/rand#Text)
297+
298+
- _Binding session IDs to user information_. This is an application requirement, out of scope
299+
for the SDK. You can create your own session IDs by setting
300+
[`ServerOptions.GetSessionID`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ServerOptions.GetSessionID).
240301

241302
## Utilities
242303

‎internal/docs/protocol.src.md‎

Lines changed: 58 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -164,11 +164,67 @@ for more background.
164164

165165
## Authorization
166166

167-
<!-- TODO -->
167+
### Server
168+
169+
To write an MCP server that performs authorization,
170+
use [`RequireBearerToken`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#RequireBearerToken).
171+
This function is middleware that wraps an HTTP handler, such as the one returned
172+
by [`NewStreamableHTTPHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#NewStreamableHTTPHandler), to provide support for verifying bearer tokens.
173+
The middleware function checks every request for an Authorization header with a bearer token,
174+
and invokes the
175+
[`TokenVerifier`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#TokenVerifier)
176+
passed to `RequireBearerToken` to parse the token and perform validation.
177+
The middleware function checks expiration and scopes (if they are provided in
178+
[`RequireBearerTokenOptions.Scopes`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#RequireBearerTokenOptions.Scopes)), so the
179+
`TokenVerifer` doesn't have to.
180+
If [`RequireBearerTokenOptions.ResourceMetadataURL`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#RequireBearerTokenOptions.ResourceMetadataURL) is set and verification fails,
181+
the middleware function sets the WWW-Authenticate header as required by the [Protected Resource
182+
Metadata spec](https://datatracker.ietf.org/doc/html/rfc9728).
183+
184+
The [_auth middleware example_](https://github.com/modelcontextprotocol/go-sdk/tree/main/examples/server/auth-middleware) shows how to implement authorization for both JWT tokens and API keys.
185+
186+
### Client
187+
188+
Client-side OAuth is implemented by setting
189+
[`StreamableClientTransport.HTTPClient`](https://pkg.go.dev/github.com/modelcontextprotocol/[email protected]/mcp#StreamableClientTransport.HTTPClient) to a custom [`http.Client`](https://pkg.go.dev/net/http#Client)
190+
Additional support is forthcoming; see #493.
168191

169192
## Security
170193

171-
<!-- TODO -->
194+
Here we discuss the mitigations described under
195+
the MCP spec's [Security Best Practices](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices) section, and how we handle them.
196+
197+
### Confused Deputy
198+
199+
The [mitigation](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices#mitigation), obtaining user consent for dynamically registered clients,
200+
happens on the MCP client. At present we don't provide client-side OAuth support.
201+
202+
203+
### Token Passthrough
204+
205+
The [mitigation](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices#mitigation-2), accepting only tokens that were issued for the server, depends on the structure
206+
of tokens and is the responsibility of the
207+
[`TokenVerifier`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#TokenVerifier)
208+
provided to
209+
[`RequireBearerToken`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#RequireBearerToken).
210+
211+
### Session Hijacking
212+
213+
The [mitigations](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices#mitigation-3) are as follows:
214+
215+
- _Verify all inbound requests_. The [`RequireBearerToken`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#RequireBearerToken)
216+
middleware function will verify all HTTP requests that it receives. It is the
217+
user's responsibility to wrap that function around all handlers in their server.
218+
219+
- _Secure session IDs_. This SDK generates cryptographically secure session IDs by default.
220+
If you create your own with
221+
[`ServerOptions.GetSessionID`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ServerOptions.GetSessionID), it is your responsibility to ensure they are secure.
222+
If you are using Go 1.24 or above,
223+
we recommend using [`crypto/rand.Text`](https://pkg.go.dev/crypto/rand#Text)
224+
225+
- _Binding session IDs to user information_. This is an application requirement, out of scope
226+
for the SDK. You can create your own session IDs by setting
227+
[`ServerOptions.GetSessionID`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ServerOptions.GetSessionID).
172228

173229
## Utilities
174230

0 commit comments

Comments
 (0)