OAuth 调试器

无需猜测即可调试 OAuth 2.0 和 OpenID Connect 流程。逐步追踪授权流程，精准定位失败环节（如重定向 URI 不匹配、scope 配置问题、token 交换失败、JWKS 配置错误等），并提供确切修复方案。

适用场景：遇到“oauth 不工作”、“重定向 URI 不匹配”、“invalid_grant”、“登录流程中断”、“OIDC 配置问题”、“token 交换失败”、“PKCE 错误”、“授权码错误”，或单点登录（SSO）/社交登录异常时。

命令

1. trace — 逐步追踪 OAuth 流程

步骤 1：发现 OAuth 配置

# OpenID Connect 发现
curl -s "https://$AUTH_DOMAIN/.well-known/openid-configuration" | python3 -c "
import json, sys
config = json.load(sys.stdin)
print('Authorization endpoint:', config.get('authorization_endpoint', '❌ MISSING'))
print('Token endpoint:', config.get('token_endpoint', '❌ MISSING'))
print('JWKS URI:', config.get('jwks_uri', '❌ MISSING'))
print('Supported flows:', config.get('grant_types_supported', ['not listed']))
print('Supported scopes:', config.get('scopes_supported', ['not listed']))
print('Token signing:', config.get('id_token_signing_alg_values_supported', ['not listed']))
"

# 检查 JWKS 端点
curl -s "https://$AUTH_DOMAIN/.well-known/jwks.json" | python3 -c "
import json, sys
jwks = json.load(sys.stdin)
for key in jwks.get('keys', []):
    print(f'Key ID: {key.get("kid")} | Algorithm: {key.get("alg")} | Use: {key.get("use")}')
"

步骤 2：验证授权请求

针对 Authorization Code + PKCE 流程：

# 检查授权 URL 构造
# 必需参数：
# - response_type=code
# - client_id=
# - redirect_uri=<必须完全匹配>
# - scope=<请求的 scopes>
# - state=
# - code_challenge=
# - code_challenge_method=S256

python3 -c "
import hashlib, base64, secrets
verifier = secrets.token_urlsafe(32)
challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b'=').decode()
print(f'code_verifier: {verifier}')
print(f'code_challenge: {challenge}')
print(f'code_challenge_method: S256')
"

步骤 3：诊断 Token 交换

# 测试 token 交换
curl -s -X POST "https://$AUTH_DOMAIN/oauth/token" 
  -H "Content-Type: application/x-www-form-urlencoded" 
  -d "grant_type=authorization_code" 
  -d "code=$AUTH_CODE" 
  -d "redirect_uri=$REDIRECT_URI" 
  -d "client_id=$CLIENT_ID" 
  -d "client_secret=$CLIENT_SECRET" 
  -d "code_verifier=$CODE_VERIFIER" | python3 -c "
import json, sys
resp = json.load(sys.stdin)
if 'access_token' in resp:
    print('✅ Token exchange successful')
    print(f'Access token type: {resp.get("token_type")}')
    print(f'Expires in: {resp.get("expires_in")}s')
    print(f'Scopes: {resp.get("scope")}')
    if 'id_token' in resp:
        print(f'ID token: present')
    if 'refresh_token' in resp:
        print(f'Refresh token: present')
else:
    print(f'❌ Error: {resp.get("error")}')
    print(f'Description: {resp.get("error_description")}')
"

2. diagnose — 常见 OAuth 错误

invalid_grant:

• 授权码已过期（通常 TTL 为 10 分钟）→ 重新发起授权
• 授权码已被使用（一次性有效）→ 不可重试，需重新授权
• Token 请求中的 redirect_uri 与授权请求中不一致 → 必须完全匹配
• PKCE verifier 与 challenge 不匹配 → 检查编码方式（如 Base64 URL-safe 编码）

redirect_uri_mismatch:

• 末尾斜杠敏感：http://localhost:3000 ≠ http://localhost:3000/
• 协议敏感：http ≠ https
• 端口敏感：localhost:3000 ≠ localhost:3001
• 路径敏感：/callback ≠ /auth/callback
• 检查身份提供商注册的 redirect URIs 列表

invalid_client:

• client_id 或 client_secret 错误
• 客户端凭据未正确发送（Basic Auth vs POST body）
• 该客户端在提供商侧已被删除或禁用

invalid_scope:

• 所请求的 scope 未为此客户端启用
• scope 格式错误（应为空格分隔，而非逗号分隔）
• 提供商已重命名 scope（例如，email → openid email）

access_denied:

• 用户拒绝授权
• 需要管理员同意，但当前用户非管理员
• 条件访问策略（Conditional Access Policy）阻止了该请求

# OAuth 调试报告

## 流程：Authorization Code + PKCE
## 提供商：Auth0（tenant.auth0.com）

## 追踪结果
1. ✅ Discovery：已找到 .well-known/openid-configuration
2. ✅ 授权请求：参数合法
3. ✅ 用户已认证并完成授权
4. ❌ Token 交换：`invalid_grant`

## 诊断结论
- Token 请求中的 redirect_uri：`http://localhost:3000/callback`
- 授权请求中的 redirect_uri：`http://localhost:3000/callback/`
- 🔴 **末尾斜杠不匹配** — 两次请求中的 redirect_uri 必须完全一致

## 修复方案
将 Token 请求中的 redirect_uri 改为 `http://localhost:3000/callback/`（带末尾斜杠）  
或修改授权请求，移除末尾斜杠。  
同时，请同步更新提供商后台注册的 redirect URIs 配置。

3. test-flow — 模拟 OAuth 流程

客户端凭据（machine-to-machine）：

curl -s -X POST "https://$AUTH_DOMAIN/oauth/token" 
  -H "Content-Type: application/x-www-form-urlencoded" 
  -d "grant_type=client_credentials" 
  -d "client_id=$CLIENT_ID" 
  -d "client_secret=$CLIENT_SECRET" 
  -d "audience=$API_AUDIENCE"

刷新 Token：

curl -s -X POST "https://$AUTH_DOMAIN/oauth/token" 
  -H "Content-Type: application/x-www-form-urlencoded" 
  -d "grant_type=refresh_token" 
  -d "refresh_token=$REFRESH_TOKEN" 
  -d "client_id=$CLIENT_ID"

4. security-check — 审计 OAuth 实现安全性

识别潜在安全风险：

• 仍在使用隐式流程（已弃用，token 出现在 URL 片段中）
• 公共客户端未启用 PKCE（存在授权码劫持风险）
• 缺失 state 参数（存在 CSRF 漏洞）
• token 出现在 URL 查询字符串中（易被日志记录、代理缓存等泄露）
• 使用通配符 redirect URI（开放重定向风险）
• 长期有效的 access token 且未配置 refresh（有效期 > 1 小时）
• 前端代码中硬编码 client secret（对用户完全暴露）