排查代理身份验证问题

如需解决使用 Agent Identity 和 Agent Identity 身份验证管理器对智能体进行身份验证时出现的常见错误，请验证您的身份验证提供方配置、Identity and Access Management (IAM) 角色绑定、OAuth 范围和 OpenID Connect (OIDC) 令牌验证设置。

如需管理身份验证提供方，请参阅管理代理身份身份验证提供方。如需在外部服务中验证代理身份 ID 令牌，请参阅使用代理自己的身份向外部服务进行身份验证。

重定向 URI 不匹配

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

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

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

缺少用户角色

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

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

发卡机构端点问题

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

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

401 UNAUTHENTICATED 错误

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

{
  "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）尚未在您的 Google Cloud 项目中启用，或者 API 密钥的限制不允许访问此服务。

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

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

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

  2. 在 Google Cloud 控制台中，前往 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 密钥字符串不正确、格式不正确或不存在于项目凭证中。

如需解决此错误，请验证您是否从 Google Cloud 控制台中的凭证页面复制了正确的 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. 打开 Google Cloud 控制台，然后前往 Logs Explorer 页面。
  2. 搜索临时部署容器日志（例如 maps_mcp_agent_tmp... 或 bigquery_mcp_agent_tmp...）。
  3. 检查 Python 回溯，找出语法错误或跟踪缺失的软件包。
  4. 确保 requirements.txt 文件中列出了所有必需的软件包。

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

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

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

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

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

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

GitHub 或 Microsoft 多个范围错误

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

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

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

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

OpenID Connect 发现和 JWKS 端点错误

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

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

HTTP 状态 原因 解决方法
400 Bad Request 出现此错误的原因是，请求网址中的工作负载身份池资源名称无效，或者请求包含 Authorization HTTP 标头。 如需解决此错误，请执行以下操作：
  • 验证工作负载身份池资源名称是否使用受支持的代理信任域格式（agents.global.org-ORGANIZATION_ID.system.id.goog 或 agents.global.proj-PROJECT_NUMBER.system.id.goog）。
  • 从请求中移除所有 Authorization 或 OAuth 标头。/.well-known/openid-configuration 和 /openid/jwks 端点是公开且未经身份验证的；传递身份验证标头会导致请求失败并出现 HTTP 400 错误。
404 Not Found 出现此错误的原因是，指定的组织 ID、项目编号或工作负载身份池不存在，或者网址路径不正确。 如需解决此错误，请确认网址中的组织 ID、项目编号和信任域（工作负载身份池 ID）准确无误。另外，验证网址路径是否以 /.well-known/openid-configuration 或 /openid/jwks 结尾。
429 Too Many Requests 出现此错误的原因是，您的验证方通过查询发现或 JWKS 端点而未缓存响应，超出了请求速率限制。 如需解决此错误，请根据 Cache-Control: public, max-age=86400, must-revalidate 响应标头，将验证方配置为缓存发现文档和 JWKS 最多 24 小时。
500 Internal Server Error 发生此错误的原因是，服务器在提取公开签名密钥时遇到了临时内部问题。 如需解决此错误，请使用缓存的 JWKS（如果有），或使用指数退避算法重试请求。

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

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

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

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

后续步骤