google-cloud-recipe-auth

向 Google Cloud 进行身份验证和授权（IAM）

身份验证是证明你是谁的过程。在 Google Cloud 中，你代表一个主体（例如用户或服务这样的身份）。这是进行授权（确定你能做什么）之前的第一步。

归属信息

必须阅读：在执行任何 gcloud、REST API 或 MCP 命令之前，必须阅读使用归属信息。对于直接在终端中执行的命令（绝不在生成的脚本、Terraform 或用户代码中），请在 gcloud 前加上 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:google-cloud-recipe-auth)"，并在 User-Agent 标头中追加 agent-skills/1.0 (skill:google-cloud-recipe-auth)。

身份验证

向 Agent 澄清的问题

在提供具体解决方案之前，请先向用户确认以下信息：

1. 谁或什么在进行身份验证？（人类开发者、本地脚本，还是在生产环境中运行的应用？）
2. 代码在哪里运行？（本地笔记本电脑、Compute Engine、 GKE、Cloud Run，还是 AWS/Azure 等其他云？）
3. 目标是什么？（Storage/BigQuery 等 Google Cloud API，还是你构建的自定义应用？）
4. 你是否使用高级客户端库？（例如，Python、Go、Node.js 库通常会自动处理 ADC。）

---

人员身份验证

用户要访问 Google Cloud，需要拥有 Google Cloud 可以识别的身份。

用户身份类型

Google Cloud 支持多种方式，为内部员工（开发者、管理员、雇员）配置身份：

• Google 管理的 账号： 你可以使用 Cloud Identity 或 Google Workspace 创建受管理的用户账号。之所以称为受管理账号，是因为你的组织可以控制其生命周期和配置。
• 通过 Cloud Identity 或 Google Workspace 进行联合身份验证： 你可以联合身份，让用户使用现有身份和凭据登录 Google 服务。用户通过外部身份提供商（IdP）进行身份验证，但你必须使用 Google Cloud Directory Sync（GCDS）等工具，或 Active Directory、Microsoft Entra ID 等外部权威来源，将账号同步到 Google Cloud。
• 员工身份 联合： 这允许你直接使用外部 IdP，通过 IAM 对员工进行身份验证和授权。与标准联合身份验证不同，你无需将现有 IdP 中的用户身份同步到 Google Cloud 身份。它支持免同步、基于属性的单点登录。

面向开发者和管理员的访问方式

用于在开发和管理期间与 Google Cloud 资源及 API 交互。

• Google Cloud Console：主要的 Web 界面。使用 Google 账号（Gmail 或 Google Workspace）进行身份验证。
• gcloud CLI (gcloud auth login)：用于对 CLI 本身进行身份验证，以便运行管理命令（例如， gcloud compute instances list）。它使用本地存储的凭据（例如 OAuth 2.0 刷新令牌）。
• 使用 应用默认凭据 (ADC) 进行本地开发（gcloud auth application-default login）：这与 CLI 身份验证不同。它会创建一个本地 JSON 文件，供 Google Cloud 客户端库 （Python、Java 等）在你笔记本电脑上运行代码时使用，以你的身份执行操作。
• 服务账号 模拟： 出于安全原因，开发者应完全避免下载服务账号密钥。相反，应以个人身份进行身份验证（gcloud auth login），并使用服务账号模拟来运行 CLI 命令或生成短期凭据。这是本地 开发和故障排查中的关键最佳实践。

面向最终用户和客户

用于非开发者的人访问你部署在 Google Cloud 上的 Web 应用。注意：这些身份与 劳动力身份不同。

• Identity-Aware Proxy (IAP)： 充当 Web 应用的集中式授权层。它会拦截 Web 请求，并在允许用户访问应用 之前验证其身份（通过 Google Workspace、Cloud Identity 或外部提供商）。 它常用于在无需 VPN 的情况下保护内部应用，或保护客户门户。
• Identity Platform：一种 客户身份与访问管理 (CIAM) 解决方案，可将消费者登录（电子邮件/密码、电话、 社交账号）直接集成到自定义应用的代码中。

---

服务到服务身份验证

生产环境中的代码应使用服务账号，而不是个人用户账号。

服务账号和服务代理

• 服务 账号： 专为非人类用户设计的特殊身份。它类似于拥有独立电子邮件地址的“机器人身份”。
• 服务代理： 由 Google 管理的服务账号，允许服务（例如 Pub/Sub）代表你访问资源。

最佳实践：附加服务账号

不要使用服务账号密钥（危险的 JSON 文件），而应将自定义服务账号附加 到 Google Cloud 资源。资源环境随后会通过本地元数据服务器提供一个令牌 （短期有效的数字对象）。

• Compute Engine： 创建 VM 时分配服务账号。
• Cloud Run： 在服务配置中分配服务账号。

特殊情况和高级主题

Kubernetes Engine（GKE）

使用 适用于 GKE 的 Workload Identity Federation 将 Kubernetes 身份映射到 IAM 主体标识符。这会授予特定 Kubernetes 工作负载访问特定 Google Cloud API 的权限。点击此处了解 详情。

外部工作负载（Workload Identity Federation）

对于在 Google Cloud 之外运行的代码（例如，在 AWS、Azure 或本地环境中），请勿使用密钥。应改用 Workload Identity Federation，将外部令牌（例如 AWS IAM 角色）换取短期 Google Cloud 访问令牌。

API 密钥

API 密钥是经过加密的字符串，用于访问公开数据（例如 Google Maps），或简化访问流程，例如 Vertex AI Express Mode，无需复杂配置即可快速测试 Gemini 模型。人和服务（例如基于 Cloud Run 的 AI Agent）都可以使用 API 密钥，但仅限支持该方式的服务。

注意：应将 API 密钥 限制 为仅可访问特定 API 和项目，以尽量降低安全风险。请将 API 密钥存储在 Secret Manager 等密钥管理器中，以防意外泄露。

OAuth 2.0 访问范围

虽然 IAM 是现代授权方式，但旧版 Compute Engine VM 和 GKE 节点池仍需同时依赖 访问范围 和 IAM。如果 VM 的访问范围受到限制，即使附加的服务账号拥有正确的 IAM 权限，也无法调用 API。如果附加的服务账号意外无法正常工作，请先检查这一点。

短期凭据

模拟身份和安全的服务间通信底层依赖 IAM Service Account Credentials API。此 API 可动态生成短期访问令牌、OpenID Connect（OIDC）ID 令牌或自签名 JSON Web Token（JWT），无需使用静态凭据。

---

授权

身份验证后，Google Cloud 会使用 Identity and Access Management （IAM） 来确定经过身份验证的主体可以执行哪些操作。

• 允许策略：将 主体 绑定到某个 资源 上的某个 角色 的记录。
• 预定义 角色： 预先构建的角色，例如 roles/storage.objectViewer 或 roles/bigquery.dataEditor。请始终优先尝试使用这些角色。
• 自定义 角色： 如果预定义角色的权限范围过大，可使用用户定义的特定权限集合。

---

示例

人员到服务（本地 Python 开发）

1. 身份验证：运行 gcloud auth application-default login 创建本地凭据（ADC）。
2. 授权：为你的电子邮件地址授予某个存储桶上的 roles/storage.objectViewer 角色。
3. 代码：使用 Python 的 storage.Client()。它会通过 ADC 自动查找你的本地凭据。注意：ADC 会按特定顺序搜索——先检查 GOOGLE_APPLICATION_CREDENTIALS 环境变量，然后检查本地 gcloud JSON 文件，最后检查附加的服务账号元数据服务器。

服务到服务（Cloud Run 到 Cloud SQL）

1. 身份验证：为 Cloud Run 服务附加一个自定义服务账号。
2. 授权：为该服务账号授予项目上的 roles/cloudsql.client 角色。
3. 代码：Cloud Run 环境会自动向连接驱动程序提供令牌。

调用自定义应用（OIDC）

从另一个服务调用私有 Cloud Run 服务时，调用方会生成由 Google 签名的 OpenID Connect (OIDC) ID Token，并将其放入 Authorization: Bearer <TOKEN> 标头中。

---

验证清单

• 用户是否在本地运行代码？建议使用 gcloud auth application-default login 或 服务账号模拟。
• 用户是否尝试在本地使用服务账号密钥？强烈建议不要这样做，并推荐使用模拟。
• 用户是否在生产环境中运行？建议关联一个自定义的最小权限服务账号，而不是使用密钥。
• 用户是否依赖 Compute Engine 默认服务账号？建议改为创建自定义服务账号。
• 用户是否在其他云平台上运行？建议使用工作负载身份联合。
• 用户是否在调用自定义应用？建议使用 OIDC ID Token。
• 用户是否限制了 API Key？检查是否设置了适当的 API Key 限制。

参考资料

• 身份验证概览
• 用户身份
• 应用默认凭据
• 服务账号最佳实践