MCP Oauth Dynamicclient

MCP OAuth动态客户端

一个生产就绪的OAuth 2.1授权服务器，支持RFC 7591动态客户端注册，专为MCP OAuth网关设计。

特性

• 符合OAuth 2.1标准 -具有强制PKCE的现代OAuth实现
• 动态客户端注册 -符合RFC 7591的自动客户端设置
• 客户端管理协议 -符合RFC 7592的CRUD操作
• GitHub OAuth集成 -通过GitHub进行用户身份验证
• JWT代币管理 -RS256（推荐）和HS256支持
• ForwardAuth兼容 -与Traefik无缝协作
• Redis状态存储 -可扩展的令牌和客户端存储
• 代币反思 -符合RFC 7662的令牌验证
• 令牌撤销 -符合RFC 7009的令牌生命周期

安装

使用pip

pip install mcp-oauth-dynamicclient

使用 pixi

pixi add --pypi mcp-oauth-dynamicclient

Docker部署

FROM python:3.11-slim

# Install the package
RUN pip install mcp-oauth-dynamicclient

# Set environment variables (configure via .env or docker-compose)
ENV HOST=0.0.0.0
ENV PORT=8000

# Expose the port
EXPOSE 8000

# Run the server
CMD ["mcp-oauth-server", "--host", "0.0.0.0", "--port", "8000"]

快速开始

1.设置环境变量

创建一个 .env 具有所需配置的文件：

# GitHub OAuth App credentials
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret

# JWT Configuration
JWT_SECRET=your_jwt_secret_key
JWT_ALGORITHM=RS256  # or HS256
JWT_PRIVATE_KEY_B64=your_base64_encoded_rsa_key  # For RS256

# Domain configuration
BASE_DOMAIN=yourdomain.com

# Redis configuration
REDIS_URL=redis://localhost:6379/0
REDIS_PASSWORD=your_redis_password  # Optional

# Token lifetimes (in seconds)
ACCESS_TOKEN_LIFETIME=1800      # 30 minutes
REFRESH_TOKEN_LIFETIME=31536000 # 1 year
SESSION_TIMEOUT=300             # 5 minutes
CLIENT_LIFETIME=7776000         # 90 days (0 = never expires)

# Access control
ALLOWED_GITHUB_USERS=user1,user2,user3  # or '*' for any GitHub user

# MCP Protocol version
MCP_PROTOCOL_VERSION=2025-06-18

2.运行服务器

使用CLI：

mcp-oauth-server --host 0.0.0.0 --port 8000

使用Python：

from mcp_oauth_dynamicclient import create_app, Settings
import uvicorn

settings = Settings()  # Loads from .env
app = create_app(settings)

uvicorn.run(app, host="0.0.0.0", port=8000)

3.注册客户

import httpx
import asyncio

async def register_client():
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://auth.yourdomain.com/register",
            json={
                "redirect_uris": ["https://myapp.com/callback"],
                "client_name": "My Application",
                "scope": "openid profile email"
            }
        )

        if response.status_code == 201:
            result = response.json()
            print(f"Client ID: {result['client_id']}")
            print(f"Client Secret: {result['client_secret']}")
            print(f"Registration Token: {result['registration_access_token']}")
            # Save these credentials securely!

asyncio.run(register_client())

API终点

公共端点

• POST /register -注册新的OAuth客户端（RFC 7591）
• GET /.well-known/oauth-authorization-server -服务器元数据
• GET /jwks -用于令牌验证的JSON Web密钥集

OAuth流端点

• GET /authorize -启动授权流程
• POST /token -代币的交换授权码
• GET /callback -GitHub OAuth回调处理程序

受保护的端点（需要承载令牌）

• GET /verify -验证ForwardAuth的令牌
• POST /revoke -撤销令牌
• POST /introspect -内省令牌详细信息

客户端管理（需要注册访问令牌）

• GET /register/{client_id} -获取客户端配置
• PUT /register/{client_id} -更新客户端配置
• DELETE /register/{client_id} -删除客户端注册

OAuth流

1. 客户注册

- 客户POS到 /register 带有元数据 - 接收 client_id, client_secret，以及 registration_access_token

1. 授权

- 客户端将用户重定向到 /authorize PKCE挑战 - 用户通过GitHub进行身份验证 - 服务器使用授权码重定向回

1. 代币交换

- 客户端POS代码 /token 带PKCE验证器 - 接收JWT访问令牌和刷新令牌

1. 令牌使用情况

- 客户端在中包含令牌 Authorization: Bearer 头球 - 服务器在每个请求上验证令牌

安全功能

• PKCE 需要 -仅支持S256代码挑战方法
• JWT代币 -使用RS256或HS256进行加密签名
• 令牌到期 -具有自动清理功能的可配置生命周期
• GitHub用户验证 -限制特定GitHub用户的访问权限
• Redis令牌存储 -代币可以立即撤销
• 注册访问令牌 -安全的客户端管理

Docker部署

该服务旨在使用MCP OAuth网关在Docker中运行：

services:
  auth:
    image: mcp-oauth-dynamicclient:latest
    environment:
      - GITHUB_CLIENT_ID=${GITHUB_CLIENT_ID}
      - GITHUB_CLIENT_SECRET=${GITHUB_CLIENT_SECRET}
      - JWT_SECRET=${JWT_SECRET}
      - JWT_ALGORITHM=RS256
      - JWT_PRIVATE_KEY_B64=${JWT_PRIVATE_KEY_B64}
      - BASE_DOMAIN=${BASE_DOMAIN}
      - REDIS_URL=redis://redis:6379/0
      - REDIS_PASSWORD=${REDIS_PASSWORD}
      - ACCESS_TOKEN_LIFETIME=1800
      - REFRESH_TOKEN_LIFETIME=31536000
      - SESSION_TIMEOUT=300
      - CLIENT_LIFETIME=7776000
      - ALLOWED_GITHUB_USERS=${ALLOWED_GITHUB_USERS}
      - MCP_PROTOCOL_VERSION=2025-06-18
    depends_on:
      - redis
    networks:
      - internal
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.auth.rule=Host(`auth.${BASE_DOMAIN}`)"
      - "traefik.http.routers.auth.tls=true"
      - "traefik.http.routers.auth.tls.certresolver=letsencrypt"

Traefik集成

配置Traefik以使用此服务进行身份验证：

# ForwardAuth middleware
- "traefik.http.middlewares.auth.forwardauth.address=http://auth:8000/verify"
- "traefik.http.middlewares.auth.forwardauth.authResponseHeaders=X-User-Id,X-User-Name,X-Auth-Token"

# Apply to protected services
- "traefik.http.routers.myservice.middlewares=auth"

发展

运行测试

# Start dependencies
docker-compose up -d redis

# Run tests
pytest

开发模式

# Install in development mode
pip install -e .

# Run with auto-reload
mcp-oauth-server --reload

配置参考

许可证

Apache-2.0许可证

贡献

欢迎投稿！请确保：

1. 所有测试都通过了真正的Redis（没有模拟！）
2. 代码遵循既定的模式
3. 新端点符合RFC标准
4. 文档已更新

看 CLAUDE.md 详细的开发指南。