Skip to content

Commit 12cbafe

Browse files
authored
oauthex: oauth discovery checks (#1220)
add extra checks for the default oauth discovery client: * disallow redirects which downgrade to http * disallow redirects to localhost or private ip * disallow the initial call to a private ip * proxy configuration opts out of dial time checking
1 parent 3632967 commit 12cbafe

6 files changed

Lines changed: 376 additions & 31 deletions

File tree

‎docs/protocol.md‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -639,24 +639,24 @@ provided to
639639

640640
### Server-Side Request Forgery
641641

642-
The [mitigations](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices#mitigation-3) are as follows:
642+
The OAuth discovery helpers apply these [mitigations](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices#mitigation-3) by default:
643643

644-
- _Enforce HTTPS_. The OAuth helpers provided by the SDK reject the `http://` URLs
645-
except loopback addresses (`localhost`, `127.0.0.1`, `::1`).
644+
- _Enforce HTTPS_. Reject `http://` URLs (except loopback: `localhost`, `127.0.0.1`, `::1`)
645+
and redirects that downgrade `https` to a non-`https` scheme.
646646

647-
- _Block Private IP Ranges_. The OAuth helpers provided by the SDK allow passing
648-
a custom `http.Client`. Developers are advised to customize the client it with
649-
appropriate network protections, including IP range blocking. The SDK does not provide
650-
this capability out of the box.
647+
- _Block Private IP Ranges_. Reject targets that resolve to a non-public address
648+
(private, link-local including the `169.254.169.254` metadata endpoint, CGNAT, multicast,
649+
unspecified). The check runs on the initial URL and at dial time, guarding against DNS rebinding.
651650

652-
- _Validate Redirect Targets_. Similarly to previous point, customized `http.Client`
653-
can be used to validate network hops. The SDK does not provide this capability out
654-
of the box.
651+
- _Validate Redirect Targets_. Reject redirects to non-public addresses and cap the redirect count.
655652

656-
- _Use Egress Proxies_. This is out of scope for the SDK and can be configured separately.
653+
- _Use Egress Proxies_. Out of scope for the SDK; configure separately.
657654

658-
- _DNS Resolution Considerations_. The SDK has DNS rebinding protection on the server side which is enabled by default. For the client side, consider providing
659-
a custom `http.Client` that would implement DNS pinning.
655+
**Opting out.** Passing a custom `http.Client` can bypass these checks, making SSRF
656+
protection your responsibility. Specifically: a custom `Transport.DialContext`/`DialTLSContext`,
657+
a non-`*http.Transport`, or a configured `Proxy` disables the dial-time IP check; setting
658+
`CheckRedirect` replaces all redirect validation. In these cases, implement your own IP
659+
blocking, redirect validation, and DNS pinning.
660660

661661
### Session Hijacking
662662

‎internal/docs/protocol.src.md‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -534,24 +534,24 @@ provided to
534534

535535
### Server-Side Request Forgery
536536

537-
The [mitigations](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices#mitigation-3) are as follows:
537+
The OAuth discovery helpers apply these [mitigations](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices#mitigation-3) by default:
538538

539-
- _Enforce HTTPS_. The OAuth helpers provided by the SDK reject the `http://` URLs
540-
except loopback addresses (`localhost`, `127.0.0.1`, `::1`).
539+
- _Enforce HTTPS_. Reject `http://` URLs (except loopback: `localhost`, `127.0.0.1`, `::1`)
540+
and redirects that downgrade `https` to a non-`https` scheme.
541541

542-
- _Block Private IP Ranges_. The OAuth helpers provided by the SDK allow passing
543-
a custom `http.Client`. Developers are advised to customize the client it with
544-
appropriate network protections, including IP range blocking. The SDK does not provide
545-
this capability out of the box.
542+
- _Block Private IP Ranges_. Reject targets that resolve to a non-public address
543+
(private, link-local including the `169.254.169.254` metadata endpoint, CGNAT, multicast,
544+
unspecified). The check runs on the initial URL and at dial time, guarding against DNS rebinding.
546545

547-
- _Validate Redirect Targets_. Similarly to previous point, customized `http.Client`
548-
can be used to validate network hops. The SDK does not provide this capability out
549-
of the box.
546+
- _Validate Redirect Targets_. Reject redirects to non-public addresses and cap the redirect count.
550547

551-
- _Use Egress Proxies_. This is out of scope for the SDK and can be configured separately.
548+
- _Use Egress Proxies_. Out of scope for the SDK; configure separately.
552549

553-
- _DNS Resolution Considerations_. The SDK has DNS rebinding protection on the server side which is enabled by default. For the client side, consider providing
554-
a custom `http.Client` that would implement DNS pinning.
550+
**Opting out.** Passing a custom `http.Client` can bypass these checks, making SSRF
551+
protection your responsibility. Specifically: a custom `Transport.DialContext`/`DialTLSContext`,
552+
a non-`*http.Transport`, or a configured `Proxy` disables the dial-time IP check; setting
553+
`CheckRedirect` replaces all redirect validation. In these cases, implement your own IP
554+
blocking, redirect validation, and DNS pinning.
555555

556556
### Session Hijacking
557557

‎internal/util/net.go‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,3 +24,26 @@ func IsLoopback(addr string) bool {
2424
}
2525
return ip.IsLoopback()
2626
}
27+
28+
// cgnat is the RFC 6598 carrier-grade NAT range (100.64.0.0/10). netip's
29+
// IsPrivate does not report it, but it is shared ISP space that is not publicly
30+
// routable and could point at another tenant behind the same NAT.
31+
var cgnat = netip.MustParsePrefix("100.64.0.0/10")
32+
33+
// IsPrivateOrReserved reports whether ip belongs to a range that must not be
34+
// reachable through a server-controlled URL, as a defense against SSRF: private
35+
// (RFC 1918 / RFC 4193 ULA), link-local (including the 169.254.169.254 cloud
36+
// metadata endpoint), carrier-grade NAT, multicast, and the unspecified address.
37+
func IsPrivateOrReserved(ip netip.Addr) bool {
38+
ip = ip.Unmap()
39+
if !ip.IsValid() {
40+
return true
41+
}
42+
if ip.IsPrivate() ||
43+
ip.IsLinkLocalUnicast() ||
44+
ip.IsMulticast() ||
45+
ip.IsUnspecified() {
46+
return true
47+
}
48+
return cgnat.Contains(ip)
49+
}

‎internal/util/net_test.go‎

Lines changed: 53 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,10 @@
33
// that can be found in the LICENSE file.
44
package util
55

6-
import "testing"
6+
import (
7+
"net/netip"
8+
"testing"
9+
)
710

811
// TestIsLoopback tests the IsLoopback helper function.
912
func TestIsLoopback(t *testing.T) {
@@ -33,3 +36,52 @@ func TestIsLoopback(t *testing.T) {
3336
})
3437
}
3538
}
39+
40+
func TestIsPrivateOrReserved(t *testing.T) {
41+
tests := []struct {
42+
ip string
43+
want bool
44+
}{
45+
// Private (RFC 1918) and IPv6 ULA (RFC 4193).
46+
{"10.0.0.1", true},
47+
{"172.16.5.4", true},
48+
{"192.168.1.1", true},
49+
{"fd00::1", true},
50+
// Link-local, including the cloud metadata endpoint.
51+
{"169.254.169.254", true},
52+
{"169.254.0.1", true},
53+
{"fe80::1", true},
54+
// Carrier-grade NAT (RFC 6598).
55+
{"100.64.0.1", true},
56+
{"100.127.255.255", true},
57+
// Multicast and unspecified.
58+
{"224.0.0.1", true},
59+
{"ff02::1", true},
60+
{"0.0.0.0", true},
61+
{"::", true},
62+
// IPv4-mapped IPv6 of a private address must also be caught.
63+
{"::ffff:10.0.0.1", true},
64+
{"::ffff:192.168.0.1", true},
65+
// Loopback is intentionally NOT reserved here (policy handled elsewhere).
66+
{"127.0.0.1", false},
67+
{"::1", false},
68+
// Public addresses are allowed.
69+
{"8.8.8.8", false},
70+
{"1.1.1.1", false},
71+
{"2606:4700:4700::1111", false},
72+
// Just outside CGNAT.
73+
{"100.63.255.255", false},
74+
{"100.128.0.0", false},
75+
}
76+
for _, tt := range tests {
77+
t.Run(tt.ip, func(t *testing.T) {
78+
ip, err := netip.ParseAddr(tt.ip)
79+
if err != nil {
80+
t.Fatalf("ParseAddr(%q): %v", tt.ip, err)
81+
}
82+
if got := IsPrivateOrReserved(ip); got != tt.want {
83+
t.Errorf("IsPrivateOrReserved(%q) = %v, want %v", tt.ip, got, tt.want)
84+
}
85+
})
86+
}
87+
}

‎oauthex/discovery_test.go‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
// Copyright 2025 The Go MCP SDK Authors. All rights reserved.
2+
// Use of this source code is governed by an MIT-style
3+
// license that can be found in the LICENSE file.
4+
5+
package oauthex
6+
7+
import (
8+
"net/http"
9+
"net/http/httptest"
10+
"strings"
11+
"testing"
12+
)
13+
14+
func TestCheckHTTPSOrLoopback(t *testing.T) {
15+
tests := []struct {
16+
name string
17+
addr string
18+
wantErr bool
19+
}{
20+
{name: "empty", addr: "", wantErr: false},
21+
{name: "https dns allowed", addr: "https://example.com/prm", wantErr: false},
22+
{name: "cleartext dns disallowed", addr: "http://example.com/prm", wantErr: true},
23+
{name: "https loopback ip allowed", addr: "http://127.0.0.1:8080/prm", wantErr: false},
24+
{name: "http localhost allowed", addr: "http://localhost/prm", wantErr: false},
25+
{name: "https private ip disallowed", addr: "https://10.0.0.1/prm", wantErr: true},
26+
{name: "link local metadata disallowed", addr: "https://169.254.169.254/", wantErr: true},
27+
{name: "mapped private address disallowed", addr: "https://[::ffff:10.0.0.1]/prm", wantErr: true},
28+
{name: "https public ip allowed", addr: "https://8.8.8.8/prm", wantErr: false},
29+
}
30+
for _, tt := range tests {
31+
t.Run(tt.name, func(t *testing.T) {
32+
err := checkHTTPSOrLoopback(tt.addr)
33+
if (err != nil) != tt.wantErr {
34+
t.Errorf("checkHTTPSOrLoopback(%q) error = %v, wantErr %v", tt.addr, err, tt.wantErr)
35+
}
36+
})
37+
}
38+
}
39+
40+
func TestDiscoveryClientRedirect(t *testing.T) {
41+
newRequestTo := func(u string) *http.Request {
42+
t.Helper()
43+
r, err := http.NewRequest(http.MethodGet, u, nil)
44+
if err != nil {
45+
t.Fatalf("NewRequest(%q): %v", u, err)
46+
}
47+
return r
48+
}
49+
testCases := []struct {
50+
name string
51+
custom *http.Client
52+
req *http.Request
53+
via []*http.Request
54+
wantBlocked bool
55+
}{
56+
{
57+
name: "redirect to public allowed",
58+
req: newRequestTo("https://8.8.8.8/"),
59+
via: []*http.Request{newRequestTo("https://93.184.216.34/")},
60+
wantBlocked: false,
61+
},
62+
{
63+
name: "downgrade blocked",
64+
req: newRequestTo("http://93.184.216.34/"),
65+
via: []*http.Request{newRequestTo("https://93.184.216.34/")},
66+
wantBlocked: true,
67+
},
68+
{
69+
name: "redirect to loopback blocked",
70+
req: newRequestTo("https://127.0.0.1/"),
71+
via: []*http.Request{newRequestTo("https://93.184.216.34/")},
72+
wantBlocked: true,
73+
},
74+
{
75+
name: "redirect to hostname resolving to loopback blocked",
76+
req: newRequestTo("https://localhost/"),
77+
via: []*http.Request{newRequestTo("https://93.184.216.34/")},
78+
wantBlocked: true,
79+
},
80+
{
81+
name: "custom client with no custom check",
82+
custom: &http.Client{},
83+
req: newRequestTo("https://127.0.0.1/"),
84+
via: []*http.Request{newRequestTo("https://93.184.216.34/")},
85+
wantBlocked: true,
86+
},
87+
{
88+
name: "custom client check disable",
89+
custom: &http.Client{
90+
CheckRedirect: func(req *http.Request, via []*http.Request) error {
91+
return nil
92+
},
93+
},
94+
req: newRequestTo("https://127.0.0.1/"),
95+
via: []*http.Request{newRequestTo("https://93.184.216.34/")},
96+
wantBlocked: false,
97+
},
98+
{
99+
name: "too many redirects",
100+
req: newRequestTo("https://8.8.8.8/"),
101+
via: func() []*http.Request {
102+
via := make([]*http.Request, maxDiscoveryRedirects)
103+
for i := range via {
104+
via[i] = newRequestTo("https://8.8.8.8/")
105+
}
106+
return via
107+
}(),
108+
wantBlocked: true,
109+
},
110+
}
111+
for _, tc := range testCases {
112+
t.Run(tc.name, func(t *testing.T) {
113+
client := newDiscoveryClient(tc.custom)
114+
gotErr := client.CheckRedirect(tc.req, tc.via)
115+
if gotErr != nil && !tc.wantBlocked {
116+
t.Fatalf("client.CheckRedirect() error = %v", gotErr)
117+
}
118+
if gotErr == nil && tc.wantBlocked {
119+
t.Fatal("client.CheckRedirect() error = nil, want blocked")
120+
}
121+
})
122+
}
123+
}
124+
125+
func TestDiscoveryBlocksInternalTarget(t *testing.T) {
126+
ctx := t.Context()
127+
for _, target := range []string{
128+
"https://169.254.169.254/latest/meta-data/",
129+
"https://10.0.0.1/.well-known/oauth-protected-resource",
130+
} {
131+
t.Run(target, func(t *testing.T) {
132+
_, err := GetProtectedResourceMetadata(ctx, target, target, nil)
133+
if err == nil {
134+
t.Fatalf("GetProtectedResourceMetadata(%q) succeeded, want SSRF rejection", target)
135+
}
136+
if !strings.Contains(err.Error(), "non-public") {
137+
t.Errorf("error = %v, want it to mention a non-public address", err)
138+
}
139+
})
140+
}
141+
}
142+
143+
func TestDiscoveryAllowsLoopbackInitial(t *testing.T) {
144+
ctx := t.Context()
145+
h := &fakeResourceHandler{}
146+
server := httptest.NewTLSServer(h)
147+
defer server.Close()
148+
h.installHandlers(server.URL)
149+
150+
metadataURL := server.URL + "/.well-known/oauth-protected-resource"
151+
prm, err := GetProtectedResourceMetadata(ctx, metadataURL, server.URL, server.Client())
152+
if err != nil {
153+
t.Fatalf("GetProtectedResourceMetadata on loopback failed: %v", err)
154+
}
155+
if prm == nil {
156+
t.Fatal("nil prm")
157+
}
158+
}

0 commit comments

Comments
 (0)