Skip to content

Commit c090dd6

Browse files
authored
Merge pull request #545 from koic/add_oauth_2_1_resource_server_support
Add OAuth 2.1 resource server support
2 parents 201f99a + e4ea601 commit c090dd6

42 files changed

Lines changed: 5851 additions & 123 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎Gemfile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ gem "yard-sorbet", "~> 0.9" if RUBY_VERSION >= "3.1"
2727
group :test do
2828
gem "event_stream_parser", ">= 1.0"
2929
gem "faraday", ">= 2.0"
30+
gem "jwt"
3031
gem "minitest", "~> 5.1", require: false
3132
gem "mocha"
3233
gem "webmock"

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Detailed guides are available at https://ruby.sdk.modelcontextprotocol.io.
66

77
## Features
88

9-
- Build [MCP servers](https://ruby.sdk.modelcontextprotocol.io/server/) that expose tools, prompts, and resources to any MCP host
9+
- Build [MCP servers](https://ruby.sdk.modelcontextprotocol.io/server/) that expose tools, prompts, and resources to any MCP host, with OAuth 2.1 resource-server protection
1010
- Build [MCP clients](https://ruby.sdk.modelcontextprotocol.io/client/) that connect to any MCP server, with automatic lifecycle negotiation and OAuth 2.1 authorization
1111
- Speak every standard transport: stdio and Streamable HTTP (including SSE), with a Rails integration
1212
- Cover the full protocol surface: server-to-client requests, multi round-trip requests, notifications, progress, logging, cancellation, completions, and pagination

‎docs/_client/authorization.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -502,3 +502,8 @@ An authorization server that changes between authorization and refresh is caught
502502
present a refresh token to a different one, even when the client identity is portable across authorization servers as a Client ID Metadata Document URL is.
503503
The transport answers that refusal by running a full authorization, which brings the new authorization server back here for you to accept or refuse.
504504
Tokens stored before this behavior shipped carry no issuer and keep refreshing; the binding applies from their next authorization.
505+
506+
## Server Side
507+
508+
Protecting a server as an OAuth 2.1 resource server, verifying bearer tokens and serving the Protected Resource Metadata that this client discovers,
509+
is documented on the server [Authorization](/server/authorization/) page.

‎docs/_server/authorization.md‎

Lines changed: 332 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/_server/configuration.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
layout: default
33
title: Configuration
4-
nav_order: 21
4+
nav_order: 22
55
---
66

77
# Configuration

‎docs/_server/custom-methods.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
layout: default
33
title: Custom Methods
4-
nav_order: 22
4+
nav_order: 23
55
---
66

77
# Custom Methods

‎docs/_server/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ It implements the Model Context Protocol specification, handling model context r
2525
- Supports roots (server-to-client filesystem boundary queries; deprecated as of 2026-07-28)
2626
- Supports sampling (server-to-client LLM completion requests; deprecated as of 2026-07-28)
2727
- Supports cursor-based pagination for list operations
28+
- Supports OAuth 2.1 resource-server protection (bearer verification, RFC 9728 Protected Resource Metadata, RFC 6750 challenges);
29+
see [Authorization](/server/authorization/)
2830
- Supports cancellation of in-flight requests on both server and client (notifications/cancelled)
2931

3032
## Supported Methods

‎docs/_server/server-context.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
layout: default
33
title: Server Context
4-
nav_order: 20
4+
nav_order: 21
55
---
66

77
# Server Context
@@ -29,6 +29,14 @@ Note that the exception reporter does not receive this user-defined hash, and in
2929
callbacks omit it unless you opt in with `instrument_server_context`.
3030
See the [Configuration](/server/configuration/) page for the arguments they receive.
3131

32+
## Authenticated Identity
33+
34+
When the Streamable HTTP transport verifies bearer tokens (see [Authorization](/server/authorization/)), the verified
35+
`MCP::Server::OAuth::AccessToken` is available to handlers as `server_context.auth_info` (`server_context[:auth_info]` when the context
36+
is a plain Hash), and `server_context.require_scopes!("some:scope")` rejects the current operation with a JSON-RPC error when the token
37+
lacks a scope. Without bearer authentication `auth_info` is `nil` and `require_scopes!` fails closed;
38+
see [Accessing the Token in Handlers](/server/authorization/#accessing-the-token-in-handlers).
39+
3240
## Request-specific `_meta` Parameter
3341

3442
The MCP protocol supports a special [`_meta` parameter](https://modelcontextprotocol.io/specification/latest/basic#general-fields) in requests that allows clients to pass request-specific metadata. The server automatically extracts this parameter and makes it available to tools and prompts as a nested field within the `server_context`.

‎docs/_server/transports.md‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -259,9 +259,10 @@ by `max_listen_subscriptions:`.
259259
### Session Ownership
260260

261261
`StreamableHTTPTransport` issues a random `SecureRandom.uuid` session ID and validates incoming requests by session
262-
existence and idle timeout only. It does not bind a session to a user, because the transport never receives
263-
an authenticated identity on its own. A caller that obtains a valid session ID could therefore act on that session,
264-
so binding a session to a user is the deploying application's responsibility (the MCP spec frames this as a SHOULD).
262+
existence and idle timeout only. Without bearer authentication it does not bind a session to a user, because the transport
263+
then receives no authenticated identity on its own. A caller that obtains a valid session ID could therefore act on that session,
264+
so binding a session to a user is the deploying application's responsibility (the MCP spec frames this as a SHOULD);
265+
with `token_verifier:` configured the transport does it itself, as described at the end of this section.
265266

266267
The primary control is the `session_request_validator`. It is called as `->(request, session_id) { true | false }`
267268
on every non-`initialize` POST, GET, and DELETE against an existing session (including notification and response POSTs,
@@ -276,15 +277,18 @@ transport = MCP::Server::Transports::StreamableHTTPTransport.new(
276277
)
277278
```
278279

279-
Without a validator the transport does not enforce ownership. As a limited defense in depth (not authentication),
280+
Without a validator or bearer authentication the transport does not enforce ownership. As a limited defense in depth (not authentication),
280281
it also records the `Origin` header at `initialize` and rejects a later request whose `Origin` differs, but only
281282
when both are present - a non-browser client that omits `Origin` (e.g. `curl` or a script) is not stopped by this check.
282283
Enforcing ownership against a determined attacker requires supplying the validator with an authenticated principal.
284+
Bearer authentication configured with `token_verifier:` supplies one automatically: each session is then also bound
285+
to the token identity that initialized it; see [Authorization](/server/authorization/).
283286

284287
Requests of the [modern lifecycle](/server/discover/#the-stateless-modern-lifecycle) carry no `Mcp-Session-Id` and touch no stored session,
285288
so there is no session to steal, and neither the validator nor the recorded-`Origin` comparison runs for them
286289
(the per-request `Origin` validation of the DNS rebinding protection above still applies);
287-
on that path, authorization is enforced per request by the deploying application.
290+
on that path, bearer enforcement configured with `token_verifier:` still applies to every request; without it,
291+
authorization is enforced per request by the deploying application.
288292

289293
### Request Size Limits
290294

‎docs/examples.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ Runnable examples live in [`examples`](https://github.com/modelcontextprotocol/r
1616
- [`http_server.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/main/examples/http_server.rb) - a Rack-based Streamable HTTP server with session management and SSE support
1717
- [`http_client.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/main/examples/http_client.rb) - a client driving the HTTP server through all MCP protocol methods
1818
- [`streamable_http_server.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/main/examples/streamable_http_server.rb) - an SSE-focused server with tools that trigger notifications and progress updates
19+
- [`streamable_http_server_oauth.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/main/examples/streamable_http_server_oauth.rb) - a Streamable HTTP server protected as an OAuth 2.1 resource server, with a `whoami` tool that reads the verified token; `DEV_MODE=1` signs demo tokens locally
1920
- [`streamable_http_client.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/main/examples/streamable_http_client.rb) - an interactive, menu-driven client for testing the SSE stream
2021

2122
Each script is standalone and run from the repository root:

0 commit comments

Comments
 (0)