Documentation
¶
Overview ¶
Package oauthserver implements a minimal, standards-based OAuth 2.1 authorization server plus resource-server token verification so MCPlex can be exposed to OAuth-only MCP clients (e.g. Gemini custom apps) through a public HTTPS tunnel, following the MCP Authorization specification (2025-11-25):
- RFC 9728 Protected Resource Metadata (`/.well-known/oauth-protected-resource[/<mcp-path>]`)
- RFC 8414 Authorization Server Metadata (`/.well-known/oauth-authorization-server`)
- RFC 7591 Dynamic Client Registration (`/oauth/register`) with a redirect-URI allowlist
- Authorization code + mandatory PKCE S256 (`/oauth/authorize`), approved by the owner secret
- RFC 8707 resource-bound, opaque, hashed-at-rest access/refresh tokens (`/oauth/token`)
- RFC 7009 revocation (`/oauth/revoke`), RFC 9207 `iss` in authorization responses
Refresh tokens rotate for public clients (OAuth 2.1 §4.3.1) and stay stable with a sliding expiry for confidential clients (Gemini "persistent linking" requirement).
Index ¶
- Constants
- Variables
- func RevokeClients(dataDir string, ids []string) (int, error)
- func StateDir(dataDir string) string
- type ClientInfo
- type Config
- type Server
- func (s *Server) Issuer() string
- func (s *Server) PublicHost() string
- func (s *Server) Resource() string
- func (s *Server) ResourceMetadataURL() string
- func (s *Server) Routes() map[string]http.HandlerFunc
- func (s *Server) SetOwnerSecret(secret string) error
- func (s *Server) VerifyAccessToken(token string) bool
- func (s *Server) WWWAuthenticate(invalidToken bool) string
Constants ¶
const (
// ScopeMCP is the single scope granted to OAuth clients: full access to the MCP endpoint.
ScopeMCP = "mcp"
)
Variables ¶
var GoogleRedirectPatterns = []string{
"https://oauth-redirect.googleusercontent.com/r/*",
"https://oauth-redirect-sandbox.googleusercontent.com/r/*",
"https://oauth-redirect-test.googleusercontent.com/r/*",
"https://oauth-redirect.googleusercontent.com/a/*",
"https://oauth-redirect-sandbox.googleusercontent.com/a/*",
"https://oauth-redirect-test.googleusercontent.com/a/*",
}
GoogleRedirectPatterns are the redirect URIs Gemini / Google Connected Apps use for OAuth account linking.
Functions ¶
func RevokeClients ¶
RevokeClients deletes the given client IDs (or all clients when ids contains "all") together with their grants and tokens. A running server picks the change up on its next request. Returns the number of clients removed.
Types ¶
type ClientInfo ¶
type ClientInfo struct {
ID string `json:"id"`
Name string `json:"name,omitempty"`
AuthMethod string `json:"authMethod"`
Redirects []string `json:"redirectUris"`
Grants int `json:"activeGrants"`
CreatedAt time.Time `json:"createdAt"`
LastUsedAt time.Time `json:"lastUsedAt"`
}
ClientInfo is a read-only summary of a registered client for `mcplex oauth clients`.
func ListClients ¶
func ListClients(dataDir string) ([]ClientInfo, error)
ListClients returns registered clients persisted under dataDir.
type Config ¶
type Config struct {
// PublicURL is the externally reachable HTTPS origin of this MCPlex instance (e.g. https://mcp.example.com).
// It becomes the OAuth issuer; the protected resource is PublicURL + MCPPath.
PublicURL string
// MCPPath is the MCP Streamable HTTP endpoint path (default "/mcp").
MCPPath string
// OwnerSecret is the secret the owner types on the consent page to approve a client (MCPlex reuses --token).
OwnerSecret string
// DataDir stores persisted clients and grants under DataDir/oauth-server.
DataDir string
// RedirectAllow lists extra allowed redirect URI patterns. A trailing "*" is a prefix wildcard; the special
// value "loopback" allows http://127.0.0.1|localhost|[::1] on any port (native clients such as Claude Code).
// Google's redirect URIs are always allowed.
RedirectAllow []string
// Now overrides the clock (tests).
Now func() time.Time
}
Config configures the OAuth server.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is the OAuth authorization server + resource-server verifier for one public MCPlex endpoint.
func (*Server) PublicHost ¶
PublicHost returns the host[:port] of the public URL (for Host-header allowlisting).
func (*Server) Resource ¶
Resource returns the canonical protected resource URI (public origin + MCP path).
func (*Server) ResourceMetadataURL ¶
ResourceMetadataURL is advertised in WWW-Authenticate on 401 responses from the MCP endpoint.
func (*Server) Routes ¶
func (s *Server) Routes() map[string]http.HandlerFunc
Routes returns the OAuth/metadata endpoints keyed by exact path.
func (*Server) SetOwnerSecret ¶ added in v0.5.1
SetOwnerSecret rotates the owner secret checked on the authorization consent page at runtime. Existing approved grants and access/refresh tokens remain valid until revoked.
func (*Server) VerifyAccessToken ¶
VerifyAccessToken validates an OAuth access token for the MCP endpoint: it must exist, be unexpired, belong to a live grant and be bound to this server's resource (RFC 8707 audience).