排查代理身份验证问题

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

重定向 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_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": 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 文件中列出了所有必需的软件包。

后续步骤