排查代理身份验证问题

本文档介绍了如何解决使用代理身份和代理身份身份验证管理器对代理进行身份验证时的常见错误。

如需了解如何配置身份验证提供程序，请参阅管理 Agent Identity 身份验证提供程序。 如需了解如何在外部服务中验证代理身份 ID 令牌，请参阅使用代理自身的身份向外部服务进行身份验证。

重定向 URI 不匹配

如果您在 OAuth 流程期间收到来自第三方应用的 redirect URI mismatch 错误，请确保在第三方开发者门户中注册的重定向 URI 与身份验证管理器生成的 URI 完全一致。

如需解决此问题，请在 Cloud de Confiance 控制台中查看身份验证提供方详细信息，或运行以下 gcloud 命令，找到生成的重定向 URI：

gcloud alpha agent-identity authProviders describe AUTH_PROVIDER_NAME \
    --location="LOCATION"

缺少用户角色

如果您的代理无法使用身份验证提供方，请验证代理身份是否对身份验证提供方资源具有 roles/agentidentity.user 角色。

如需解决此问题，请使用 Cloud de Confiance 控制台授予相应角色，或运行 add-iam-policy-binding 命令。

发卡机构端点问题

对于 OIDC 提供方，请验证颁发者端点是否可公开访问，以及是否支持 .well-known/openid-configuration 发现文档。

如果 Cloud de Confiance 无法提取 OIDC 元数据或 JWKS，请确保端点不在防火墙或受限网络后面。

401 UNAUTHENTICATED 错误

如果代理无法进行身份验证，可能会出现以下错误。此错误通常是由强制执行 mTLS 绑定和 DPoP 加密证明的 Google 管理的情境感知访问权限政策引起的：

{
  "error": {
    "code": 401,
    "message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.",
    "status": "UNAUTHENTICATED"
  }
}

如需解决此错误，您可以在有特定的令牌共享要求或必须将令牌直接注入到标头中时，选择停用默认的情境感知访问权限政策。如需选择停用，请在部署代理时设置以下环境变量：

config={
  "env_vars": {
    "GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN": "false",
  }
}

API 密钥服务已遭屏蔽 (API_KEY_SERVICE_BLOCKED)

如果您验证 API 密钥，可能会出现以下错误。此错误表示相应服务已被屏蔽：

"details": [
  {
    "@type": "type.googleapis.com/google.rpc.ErrorInfo",
    "reason": "API_KEY_SERVICE_BLOCKED",
    "domain": "googleapis.com",
    "metadata": {
      "methodName": "google.cloud.translate.v2.TranslateService.TranslateText",
      "service": "translate.googleapis.com",
      "consumer": "projects/PROJECT_NUMBER",
      "apiName": "translate"
    }
  },
  {
    "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
    "locale": "en-US",
    "message": "Requests to this API translate method google.cloud.translate.v2.TranslateService.TranslateText are blocked."
  }
]

出现此错误的原因是，目标 API 服务（例如 Cloud Translation API）尚未在您的 Cloud de Confiance 项目中启用，或者 API 密钥的限制不允许访问此服务。

如需解决此错误，请按以下步骤操作：

1. 在 Cloud de Confiance 控制台中，前往 API 和服务 > 库页面，并确保目标 API 已启用。

   前往“API 和服务”>“库”

2. 在 Cloud de Confiance 控制台中，前往 API 和服务 > 凭证页面，修改您的 API 密钥，并验证其 API 限制是否允许访问相应服务。

   前往“API 和服务”>“凭据”

API 密钥无效 (API_KEY_INVALID)

向第三方服务发送请求时，可能会出现以下错误。此错误表示 API 密钥无效：

"details": [
  {
    "@type": "type.googleapis.com/google.rpc.ErrorInfo",
    "reason": "API_KEY_INVALID",
    "domain": "googleapis.com",
    "metadata": {
      "service": "translate.googleapis.com"
    }
  },
  {
    "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
    "locale": "en-US",
    "message": "API key not valid. Please pass a valid API key."
  }
]

出现此错误的原因是，请求标头中传递的 API 密钥字符串不正确、格式不正确，或者不存在于项目凭据中。

如需解决此错误，请验证您是否已从 Cloud de Confiance 控制台的凭据页面复制了正确的 API 密钥字符串，并且未包含前导或尾随空格。

检索凭据时权限遭拒 (agentidentity.authProviders.retrieveCredentials)

在本地运行 adk web 或与已部署的智能体互动时，可能会出现以下 403 Forbidden 错误：

google.api_core.exceptions.Forbidden: 403 POST https://agentidentitycredentials.mtls.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME/credentials:retrieve?%24alt=json%3Benum-encoding%3Dint: Permission 'agentidentity.authProviders.retrieveCredentials' denied on resource '//agentidentity.googleapis.com/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME' (or it may not exist).

出现此错误的原因是，尝试调用身份验证提供方的主账号没有检索凭据所需的 IAM 权限。

如需解决此错误，请向主账号授予 Agent Identity User (roles/agentidentity.user) 角色：

• 如果在本地开发期间（uv run adk web 或 uvicorn）出现此错误，请确保您已向自己的个人用户账号 (user:USER_EMAIL) 授予相应角色。
• 如果此错误是在与已部署的代理互动时发生的，请确保您已向代理的 SPIFFE ID 主账号 (principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID) 授予相应角色。

一般部署失败

使用 uv run adk deploy 部署代理时，该命令可能会失败并显示一般性错误消息。

此错误是由于缺少 Python 依赖项、agent.py 中存在语法错误或环境变量配置错误而导致的。

要解决此错误，请执行以下操作：

1. 打开 Cloud de Confiance 控制台，然后前往 Logs Explorer 页面。
2. 搜索临时部署容器日志（例如 maps_mcp_agent_tmp... 或 bigquery_mcp_agent_tmp...）。
3. 检查 Python 轨迹，以识别语法错误或跟踪缺失的软件包。
4. 确保您的 requirements.txt 文件中列出了所有必需的软件包。

ServiceNow 身份验证循环或意外范围

当客服人员使用三方模式 OAuth 向 ServiceNow 进行身份验证时，身份验证流程可能会失败，或者客服人员可能会进入请求循环。

出现此问题的原因是 ServiceNow 在应用级层确定授予的范围，而不是根据代理请求的范围来确定。如果管理员在 ServiceNow 应用上配置了特定范围（例如 useraccount），即使代理请求了不同的范围（例如 mcp_server），ServiceNow 也会返回仅包含这些配置范围的令牌。如果代理严格预期或验证所请求的范围，则会拒绝收到的令牌，并可能会循环重新请求凭据。

如需解决此问题，请执行以下操作：

1. 以管理员身份登录您的 ServiceNow 实例。
2. 前往 ServiceNow OAuth 应用配置。
3. 确保将代理所需的所有范围明确添加到应用的允许范围列表中。
4. 将代理配置为仅请求在 ServiceNow 中启用的范围。

如需了解详情，请参阅支持的第三方服务。

GitHub 或 Microsoft 多范围错误

为 GitHub 或 Microsoft 配置身份验证提供方时，如果您请求多个 OAuth 范围，身份验证会失败。

身份验证管理器支持 GitHub 和 Microsoft 的单范围集成。身份验证管理器不支持同时请求多个范围。

如需解决此问题，请将您的代理或身份验证提供方配置为仅请求集成所需的单个范围。

如需了解详情，请参阅支持的第三方服务。

OpenID Connect 发现和 JWKS 端点错误

外部服务或信赖方可以查询 Cloud de Confiance安全令牌服务 OpenID Connect 发现 (/.well-known/openid-configuration) 或 JSON Web 密钥集 (/openid/jwks) 端点，以验证 Agent Identity ID 令牌。查询这些端点时，请求可能会失败，并显示 HTTP 400、404、429 或 500 错误。

下表介绍了这些错误的原因和解决方法：

密钥轮替后，令牌签名验证失败

当外部服务验证 Agent Identity ID 令牌时，即使来自同一代理的先前令牌成功通过验证，新签发的令牌也可能无法通过签名验证。

出现此问题的原因是， Cloud de Confiance 会定期轮替工作负载身份池的私钥和公钥签名密钥。因此，传入令牌的 kid（密钥 ID）可能不在验证器的本地密钥缓存中。

如需解决此问题，请配置验证器，使其在收到具有无法识别的 kid 的令牌时，先从 /openid/jwks 端点提取新的 JWKS，然后再拒绝该令牌。

后续步骤

• Agent Identity 身份验证管理器概览
• Agent Identity 概览
• 使用代理的自有身份向 Cloud de Confiance 进行身份验证
• 使用代理的自有身份向外部服务进行身份验证
• 使用三方模式 OAuth 和身份验证管理器进行身份验证
• 使用双方模式 OAuth 和身份验证管理器进行身份验证
• 使用 API 密钥通过身份验证管理器进行身份验证
• 管理 Agent Identity 身份验证提供方