📦 OAuth 调试器

OAuth 调试器 无需猜测即可调试 OAuth 2.0 与 OpenID Connect 流程。逐段追踪授权链路，精准定位故障（redirect URI 不匹配、scope 问题、token 交换失败、JWKS 配置错误），并给出确切修复方案。

使用场景： “oauth 不工作”、“redirect URI 不匹配”、“invalid_grant”、“登录流程坏了”、“OIDC 配置”、“token 交换失败”、“PKCE 报错”、“授权码错误”，或 SSO/社交登录失效时。

命令

• trace — 逐步追踪 OAuth 流程

Step 1: 发现 OAuth 配置 # OpenID Connect discovery 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\")}') "

Step 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') "

Step 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 交换成功') 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\")}') "

• diagnose — 常见 OAuth 错误

invalid_grant:

• 授权码过期（通常 10 min TTL）→ 重新授权
• 授权码已用（一次性）→ 勿重试，重新授权
• token 请求中的 redirect_uri 与 authorize 请求不一致 → 必须完全匹配
• PKCE verifier 与 challenge 不符 → 检查编码

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:

• 用户拒绝授权
• 需管理员授权但用户非管理员
• 条件访问策略拦截

# OAuth 调试报告

Flow: Authorization Code + PKCE

Provider: Auth0 (tenant.auth0.com)

Trace

• ✅ Discovery: .well-known/openid-configuration 找到
• ✅ Authorization 请求: 参数合法
• ✅ 用户认证并授权
• ❌ Token 交换: invalid_grant

诊断

• Token 请求 redirect URI: http://localhost:3000/callback
• Authorize 请求 redirect URI: http://localhost:3000/callback/
• 🔴 末尾斜杠不一致 — 两次请求必须完全相同

修复

将 token 请求中的 redirect_uri 改为 http://localhost:3000/callback/（带斜杠） 或去掉 authorize 请求的末尾斜杠，并同步更新提供商注册的 redirect URIs。

• test-flow — 模拟 OAuth 流程

Client Credentials（机器对机器）: 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 "cl