Azure DevOps Agent SPNEGO 凭据失效？一文带你彻底解决 Kerberos 认证难题

内容摘要：Azure DevOps Agent SPNEGO 凭据失效？一文带你彻底解决 Kerberos 认证难题,

在使用 Azure DevOps Agent 进行自动化构建和部署时，经常会遇到 SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) 凭据错误，导致 Agent 无法正常连接到 Azure DevOps 服务。这通常与 Kerberos 认证配置不当有关，尤其是在企业内部网络环境中。本文将深入剖析此类问题，并提供一系列解决方案和最佳实践。

问题场景重现：SPNEGO 凭据错误的常见表现

最常见的错误提示如下：

AuthenticationException: The request for security token could not be satisfied because authentication failed.

或者在 Agent 日志中出现类似 Kerberos 认证失败的错误信息。这些错误通常发生在 Agent 尝试访问需要 Kerberos 认证的服务时，例如连接到 SQL Server 数据库、访问共享文件服务器等。

底层原理深度剖析：Kerberos 认证流程详解

要理解 SPNEGO 凭据错误，首先需要了解 Kerberos 认证的基本流程。Kerberos 是一种网络认证协议，它使用密钥分发中心 (KDC) 来验证用户和服务身份。典型的 Kerberos 认证流程如下：

1. 客户端 (Agent) 请求票据授予票据 (TGT)：Agent 向 KDC 发送请求，请求用于获取服务票据的 TGT。
2. KDC 验证客户端身份并颁发 TGT：KDC 验证 Agent 的身份，如果验证成功，则颁发 TGT 给 Agent。
3. 客户端使用 TGT 请求服务票据：Agent 使用 TGT 向 KDC 请求访问特定服务的服务票据。
4. KDC 颁发服务票据：KDC 验证 Agent 的 TGT，如果验证成功，则颁发服务票据给 Agent。
5. 客户端使用服务票据访问服务：Agent 使用服务票据向服务进行身份验证，并建立安全连接。

SPNEGO 则是 Kerberos 认证的一种协商机制，它允许客户端和服务端协商使用哪种认证协议。当 SPNEGO 协商失败时，通常会导致凭据错误。

代码/配置解决方案：解决 SPNEGO 凭据错误的详细步骤

以下提供几种常见的解决方案，根据实际情况选择适合你的方案：

1. 确保 Agent 运行账户具有 Kerberos 权限

Agent 运行账户必须是域账户，并且具有访问所需服务的 Kerberos 权限。检查步骤：

1. 确认 Agent 以域用户身份运行。
2. 检查域用户的权限，确保其具有访问目标服务的权限，例如 SQL Server 的数据库访问权限，或者文件服务器的共享文件夹访问权限。

2. 配置 Service Principal Names (SPN)

SPN 是 Kerberos 认证中用于标识服务的唯一名称。确保为 Agent 运行账户注册了正确的 SPN。

可以使用 setspn 命令来管理 SPN。例如，如果要为名为 azuredevopsagent 的域用户注册一个用于 SQL Server 服务的 SPN，可以使用以下命令：

setspn -S MSSQLSvc/sql.example.com:1433 azuredevopsagent

其中 sql.example.com 是 SQL Server 的主机名，1433 是 SQL Server 的端口号，azuredevopsagent 是 Agent 运行账户的用户名。

3. 检查 Kerberos 配置文件 (krb5.conf)

确保 Agent 服务器上存在有效的 Kerberos 配置文件 (krb5.conf)，并且配置正确。该文件通常位于 /etc 目录下。检查以下配置项：

• [libdefaults]: 包含 Kerberos 的默认配置，例如 default_realm 和 dns_lookup_kdc。
• [realms]: 定义 Kerberos 域的配置，例如 KDC 的地址。
• [domain_realm]: 定义域名与 Kerberos 域的映射关系。

一个典型的 krb5.conf 配置文件如下：

[libdefaults]
  default_realm = EXAMPLE.COM
  dns_lookup_kdc = true
  dns_lookup_realm = false
  ticket_lifetime = 24h
  renew_lifetime = 7d
  forwardable = true

[realms]
  EXAMPLE.COM = {
    kdc = kerberos.example.com
    admin_server = kerberos.example.com
  }

[domain_realm]
  .example.com = EXAMPLE.COM
  example.com = EXAMPLE.COM

4. 使用 kinit 命令手动获取 Kerberos 票据

可以使用 kinit 命令手动获取 Kerberos 票据，验证 Agent 运行账户是否可以成功进行 Kerberos 认证。

kinit azuredevopsagent@EXAMPLE.COM

如果 kinit 命令成功执行，则表示 Agent 运行账户可以成功获取 Kerberos 票据。如果 kinit 命令失败，则需要检查 Kerberos 配置和权限设置。

5. 在 Azure DevOps Pipeline 中配置 Kerberos 认证

如果你的 Azure DevOps Pipeline 需要访问需要 Kerberos 认证的服务，需要在 Pipeline 中配置 Kerberos 认证。例如，可以使用 Invoke-Sqlcmd 命令连接到 SQL Server 数据库时，需要指定 -UseIntegratedSecurity 参数。

Invoke-Sqlcmd -ServerInstance sql.example.com -Database MyDatabase -Query "SELECT * FROM MyTable" -UseIntegratedSecurity

实战避坑经验总结

• 仔细检查 SPN 配置：SPN 配置错误是导致 SPNEGO 凭据错误的最常见原因之一。请务必仔细检查 SPN 配置，确保 SPN 与服务和 Agent 运行账户匹配。
• 使用 klist 命令查看 Kerberos 票据：可以使用 klist 命令查看当前用户的 Kerberos 票据，验证票据是否有效。
• 启用 Kerberos 日志：启用 Kerberos 日志可以帮助诊断认证问题。可以在 krb5.conf 文件中配置 Kerberos 日志。
• 考虑 Nginx 反向代理：如果你的应用使用了 Nginx 作为反向代理，需要确保 Nginx 也配置了 Kerberos 认证，以便将 Kerberos 凭据传递给后端服务。要关注 Nginx 的并发连接数和负载均衡策略。
• 宝塔面板上的配置：如果服务器使用了宝塔面板，注意防火墙设置可能影响 Kerberos 通信。检查相关端口是否开放。

希望以上指南能够帮助你解决 Azure DevOps Agent 的 SPNEGO 凭据错误问题，提升自动化构建和部署的效率。