NextAuth/Auth.js集成Keycloak遇OAuthCallbackError：JWT签名验证失败（T3 Stack）

核心问题分析 #

本地容器化Keycloak集成正常，但NGINX反向代理的远程Keycloak出现JWT签名验证失败，本质是NextAuth获取到的JWT issuer/公钥与配置不匹配，或Keycloak生成的JWT基于内部地址导致验证逻辑不通过。以下是针对性解决方案：

1. 修正Keycloak的外部访问配置 #

• 登录Keycloak控制台，进入目标Realm → Realm Settings → General：
  • 设置Frontend URL为外部可访问的完整URL（例如https://your-keycloak-domain.com/realms/your-realm，注意Keycloak 17+默认移除了/auth路径）
  • 访问https://your-keycloak-domain.com/realms/your-realm/.well-known/openid-configuration，确认返回的issuer字段与NextAuth配置的env.KEYCLOAK_ISSUER完全一致（包括HTTP/HTTPS、路径、是否带斜杠）

2. 调整NGINX反向代理配置 #

确保NGINX正确传递请求头，让Keycloak识别外部访问地址：

server {
    listen 443 ssl;
    server_name your-keycloak-domain.com;

    ssl_certificate /path/to/your-cert.pem;
    ssl_certificate_key /path/to/your-key.pem;

    location / {
        proxy_pass http://your-keycloak-internal-address:8080;
        # 必须传递的代理头
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}

同时启动Keycloak容器时添加代理参数：

./kc.sh start --proxy edge --hostname your-keycloak-domain.com --hostname-port 443 --hostname-strict-https true

--proxy edge表示Keycloak信任反向代理传递的X-Forwarded-*头，生成基于外部地址的JWT。

3. 验证JWKS端点的可访问性 #

在Next.js应用容器内执行：

curl https://your-keycloak-domain.com/realms/your-realm/protocol/openid-connect/certs

确保能正常获取公钥集合，且公钥的kid与JWT头中的kid匹配（可通过JWT解码工具查看id_token的头信息）。若无法访问，需检查网络策略、防火墙是否允许应用容器访问Keycloak的HTTPS端口。

4. 检查NextAuth配置细节 #

• 确认KEYCLOAK_ISSUER是完整的Realm URL，例如https://your-keycloak-domain.com/realms/your-realm，不要遗漏Realm名称
• 若生产环境使用自签名证书（不推荐），可临时添加参数测试（生产环境禁用）：

KeycloakProvider({
  clientId: env.KEYCLOAK_CLIENT_ID,
  clientSecret: env.KEYCLOAK_CLIENT_SECRET,
  issuer: env.KEYCLOAK_ISSUER,
  // 仅测试用，生产环境禁止
  skipClientIdCheck: true,
  skipIssuerCheck: true,
})

5. 核对JWT的issuer字段 #

开启NextAuth的debug: true后，在日志中找到返回的id_token，用JWT解码工具解析，查看iss字段是否与NextAuth配置的issuer完全一致。任何细微差异（如HTTP/HTTPS、末尾斜杠）都会触发签名验证失败。

内容的提问来源于stack exchange，提问作者smeebear