Azure DevOps Agent SPNEGO 凭据问题排查与终极解决方案

内容摘要：Azure DevOps Agent SPNEGO 凭据问题排查与终极解决方案,

在使用 Azure DevOps Agent 进行持续集成/持续交付 (CI/CD) 时，我们有时会遇到 SPNEGO 凭据相关的错误，导致构建或发布流程失败。这种错误往往比较隐蔽，排查起来也颇为棘手。本文将分享一次解决 Azure DevOps Agent 的 SPNEGO 凭据错误问题的实战经验，并深入剖析其底层原理。

问题场景重现

想象一下这样的场景：你配置了一个 Azure DevOps Pipeline，需要在 Agent 上执行一些需要 Kerberos 认证的操作，例如访问公司内部的 Web 服务或者数据库。然而，Pipeline 运行时却报错，提示类似“GSSException: No valid credentials provided (Mechanism level: Failed to find any Kerberos tgt)”的信息。这通常意味着 Agent 无法获取有效的 Kerberos 票据，从而导致 SPNEGO 认证失败。

底层原理深度剖析

SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) 是一种协商认证协议，允许客户端和服务器协商使用哪种认证机制，通常是 Kerberos。Kerberos 是一种网络认证协议，它使用密钥分发中心 (KDC) 来验证用户和服务的身份。当 Agent 尝试访问需要 Kerberos 认证的服务时，它需要先从 KDC 获取票据授予票据 (TGT)，然后再使用 TGT 获取访问服务的票据。

SPNEGO 的底层原理涉及以下几个关键步骤：

1. 客户端 (Agent) 发起 SPNEGO 协商： 客户端向服务器发送包含支持的认证机制列表的协商请求。
2. 服务器选择认证机制： 服务器从列表中选择一个认证机制，例如 Kerberos，并返回给客户端。
3. Kerberos 认证： 客户端使用 Kerberos 协议进行认证，包括获取 TGT 和服务票据。
4. 客户端向服务器发送票据： 客户端将服务票据发送给服务器，服务器验证票据的有效性。
5. 认证成功： 如果票据有效，服务器授予客户端访问权限。

如果 Agent 无法获取有效的 TGT，或者服务票据无效，就会导致 SPNEGO 认证失败。

解决方案：配置 Kerberos 认证

解决 SPNEGO 凭据错误的关键在于正确配置 Agent 的 Kerberos 认证。以下是一些常见的解决方案：

1. 确保 Agent 运行在 Domain 用户下

Azure DevOps Agent 应该运行在域用户下，而不是本地用户。这样 Agent 才能访问域控制器的 Kerberos 服务。你可以修改 Agent 的服务配置，将其登录身份改为一个域用户，并确保该用户拥有足够的权限。

2. 配置 krb5.conf 文件

krb5.conf 文件是 Kerberos 客户端的配置文件，用于指定 KDC 的地址、域名和其他配置信息。确保 krb5.conf 文件存在并且配置正确。该文件通常位于 /etc/krb5.conf (Linux) 或 C:\Windows\krb5.ini (Windows) 。

一个典型的 krb5.conf 文件如下所示：

[libdefaults]
  default_realm = EXAMPLE.COM # 替换为你的域名
  dns_lookup_realm = false
  dns_lookup_kdc = true
  ticket_lifetime = 24h
  renew_lifetime = 7d
  forwardable = true
[realms]
  EXAMPLE.COM = {
    kdc = kdc.example.com # 替换为你的 KDC 地址
    admin_server = kdc.example.com # 替换为你的 KDC 地址
  }
[domain_realm]
  .example.com = EXAMPLE.COM # 替换为你的域名
  example.com = EXAMPLE.COM # 替换为你的域名

3. 使用 kinit 命令获取 TGT

kinit 命令用于从 KDC 获取 TGT。你可以使用以下命令获取 TGT：

kinit username@EXAMPLE.COM # 替换为你的用户名和域名

你需要输入用户的密码才能获取 TGT。获取 TGT 后，你可以使用 klist 命令查看当前 Agent 拥有的 Kerberos 票据。

4. 环境变量设置

有些应用程序需要通过环境变量来指定 Kerberos 相关的配置信息。例如，Java 应用程序可以使用 java.security.krb5.conf 环境变量来指定 krb5.conf 文件的路径。

export JAVA_OPTS="-Djava.security.krb5.conf=/etc/krb5.conf"

5. 服务主体名称 (SPN) 配置

如果 Agent 需要访问的服务使用了服务主体名称 (SPN)，你需要确保 SPN 已经正确配置。SPN 是 Kerberos 用于标识服务的唯一名称。你可以使用 setspn 命令来配置 SPN。例如，如果 Agent 需要访问一个运行在 webserver.example.com 上的 HTTP 服务，你可以使用以下命令来配置 SPN：

setspn -A HTTP/webserver.example.com@EXAMPLE.COM username # 替换为服务运行的用户

请注意，配置 SPN 需要域管理员权限。

实战避坑经验总结

1. 仔细检查 krb5.conf 文件： krb5.conf 文件中的配置错误是导致 SPNEGO 凭据错误的常见原因。务必仔细检查文件中的域名、KDC 地址等配置信息是否正确。
2. 确保 Agent 用户拥有足够的权限： Agent 用户需要拥有访问 KDC 和目标服务的权限。如果用户权限不足，会导致 Kerberos 认证失败。
3. 注意 SPN 配置： 如果 Agent 需要访问的服务使用了 SPN，务必确保 SPN 已经正确配置。错误的 SPN 配置会导致 Kerberos 认证失败。
4. 考虑使用 Keytab 文件： 在某些情况下，使用 kinit 命令手动获取 TGT 并不方便。你可以考虑使用 Keytab 文件来存储用户的 Kerberos 密钥。Keytab 文件可以自动获取 TGT，而无需手动输入密码。
5. 日志分析： 仔细分析 Agent 和 KDC 的日志，可以帮助你找到问题的根源。Kerberos 相关的日志通常位于 /var/log/krb5kdc.log (Linux) 或 Windows 事件查看器中。

总之，解决 Azure DevOps Agent 的 SPNEGO 凭据错误需要耐心和细致的排查。通过理解 SPNEGO 的底层原理，并结合具体的解决方案，相信你能够成功解决这类问题，保障 CI/CD 流程的顺利进行。