巧解 Azure DevOps Agent SPNEGO 身份验证难题，告别 Kerberos 认证失败

内容摘要：巧解 Azure DevOps Agent SPNEGO 身份验证难题，告别 Kerberos 认证失败,

在使用 Azure DevOps Agent 对接企业内部 Kerberos 认证的服务时，经常会遇到 SPNEGO 凭据错误，导致构建、发布流程中断。尤其是在使用 Nginx 作为反向代理、以及启用 AD 域控环境下，这个问题更为常见。本文将深入剖析该问题的底层原理，并提供实战解决方案，助你彻底摆脱困扰。

SPNEGO 与 Kerberos：身份验证的幕后功臣

SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) 是一种协商身份验证机制，允许客户端和服务器协商使用哪种 GSSAPI 机制（例如 Kerberos）进行身份验证。 Kerberos 是一种网络身份验证协议，它使用密钥分发中心 (KDC) 来颁发票证，以便客户端和服务可以安全地相互验证身份。

简单来说，当 Azure DevOps Agent 尝试访问需要 Kerberos 认证的服务时，它会尝试使用 SPNEGO 协商机制与服务器进行身份验证。如果 SPNEGO 协商失败，通常是因为 Agent 无法获取或使用正确的 Kerberos 凭据。这可能是由于以下几个原因：

• Kerberos 配置错误： 例如 krb5.conf 文件配置不正确，导致 Agent 无法找到 KDC。
• Agent 账户权限不足： Agent 运行账户没有访问 KDC 或获取票证的权限。
• DNS 解析问题： Agent 无法正确解析 KDC 或服务主机的域名。
• 时钟同步问题： Agent 与 KDC 之间存在较大的时钟偏差，导致票证失效。

深挖底层：Kerberos 票证获取流程

为了更好地理解问题，我们需要了解 Kerberos 票证的获取流程：

1. 客户端（Azure DevOps Agent）向 KDC 发送 AS_REQ (Authentication Service Request) 请求，请求获取 TGT (Ticket Granting Ticket)。
2. KDC 验证客户端身份，如果验证通过，则返回加密的 TGT。
3. 客户端使用用户密码解密 TGT，并将其缓存。
4. 客户端向 KDC 发送 TGS_REQ (Ticket Granting Service Request) 请求，使用 TGT 请求访问特定服务的票证。
5. KDC 验证 TGT，如果验证通过，则返回加密的服务票证。
6. 客户端使用服务票证访问服务。

如果任何一个环节出现问题，例如 TGT 获取失败、TGT 验证失败、服务票证获取失败，都会导致 SPNEGO 协商失败，从而出现凭据错误。

解决方案：一步一步解决 SPNEGO 凭据问题

针对上述可能的原因，我们可以采取以下步骤来解决 SPNEGO 凭据错误：

1. 检查 Kerberos 配置文件 krb5.conf：

   确保 krb5.conf 文件配置正确，包括 [libdefaults]、[realms]、[domain_realm] 等节的内容。确保 realm 名称、kdc 地址、admin_server 地址等参数配置正确。

   [libdefaults]
       default_realm = EXAMPLE.COM
       dns_lookup_realm = false
       dns_lookup_kdc = false
       ticket_lifetime = 24h
       renew_lifetime = 7d
       forwardable = true
   
   [realms]
       EXAMPLE.COM = {
           kdc = kdc.example.com
           admin_server = kdc.example.com
       }
   
   [domain_realm]
       .example.com = EXAMPLE.COM
       example.com = EXAMPLE.COM
   

2. 确保 Agent 运行账户拥有访问 KDC 的权限：

   

   Agent 运行账户需要能够读取 krb5.conf 文件，并能够连接到 KDC 服务器。必要时，可以为 Agent 运行账户授予相应的 Kerberos 权限。

3. 使用 kinit 命令获取 TGT：

   使用 kinit 命令尝试以 Agent 运行账户的身份获取 TGT。如果 kinit 命令失败，则说明 Agent 无法获取 Kerberos 凭据。我们需要进一步排查 Kerberos 配置、账户权限等问题。

   kinit agent_account@EXAMPLE.COM # 使用 agent 账户获取 TGT
   klist # 查看当前缓存的 Kerberos 票证
   

4. 检查 DNS 解析：

   

   确保 Agent 可以正确解析 KDC 和服务主机的域名。可以使用 nslookup 命令或 ping 命令进行测试。

   nslookup kdc.example.com
   ping service.example.com
   

5. 检查时钟同步：

   确保 Agent 与 KDC 之间的时间差在允许范围内。可以使用 ntpdate 命令或 chrony 命令进行时钟同步。

   ntpdate kdc.example.com
   

6. 配置 Azure DevOps Agent 服务主体名称 (SPN)：

   

   确保 Azure DevOps Agent 的 SPN 已正确注册到 Active Directory 中。可以使用 setspn 命令进行配置。

   setspn -S HTTP/agent.example.com agent_account # 设置 HTTP SPN
   setspn -S HTTP/agent agent_account # 设置简短 SPN
   

7. Nginx 反向代理配置 (可选)： 如果你的 Azure DevOps Agent 通过 Nginx 反向代理访问 Kerberos 认证的服务，你需要确保 Nginx 已正确配置以传递 SPNEGO 身份验证信息。 例如，添加 proxy_set_header Authorization $http_authorization; 到 Nginx 的配置中，确保将客户端的 Authorization 请求头传递给后端服务。

   location / {
       proxy_pass http://backend_service;
       proxy_set_header Host $host;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_set_header Authorization $http_authorization; # 传递 SPNEGO 认证信息
   }
   

实战避坑经验总结

• 保持 Agent 运行账户的简单性： 尽量使用专门的 Agent 运行账户，避免与其他服务的账户混用，以减少权限冲突。
• 详细记录错误日志： 仔细查看 Azure DevOps Agent 的错误日志、Kerberos 的日志，以便快速定位问题。
• 分阶段排查： 从最基本的 Kerberos 配置开始，逐步排查，避免一次性修改过多配置，导致问题更加复杂。
• 关注安全： SPNEGO 和 Kerberos 涉及到安全认证，配置时务必注意安全性，避免泄露敏感信息。
• 利用工具： 使用 Wireshark 等抓包工具，可以帮助你分析 Kerberos 协议的交互过程，从而更好地理解问题。

通过以上步骤，相信你可以成功解决 Azure DevOps Agent 的 SPNEGO 凭据错误问题，保障构建、发布流程的顺利进行。