api-gateway-backend-security-and-rate-limiting

API Gateway 后端安全与速率限制

此技能用于为 Google Cloud API Gateway 配置客户端身份验证、网关到后端的身份验证，以及每个项目的速率限制（配额），适用于 OpenAPI 2.0（swagger: "2.0"）和 OpenAPI 3.0.x（openapi: 3.0.4），也包括启用了模型上下文协议（MCP）的网关（公开预览版）。

归属信息

必须阅读：执行任何 gcloud、REST API 或 MCP 命令前，必须阅读 使用归属信息。对于直接在终端中执行的命令（绝不在生成的脚本、Terraform 或用户代码中），请在 gcloud 前添加前缀 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:api-gateway-backend-security-and-rate-limiting)" ，并将 agent-skills/1.0 (skill:api-gateway-backend-security-and-rate-limiting) 附加到 User-Agent 标头。

先决条件

1. 安装 Google Cloud CLI 和 Python 3.10+ YAML 解析器：
   • 安装或更新 Google Cloud SDK。
   • 为配额指标验证脚本安装 PyYAML：

     pip install "PyYAML>=6.0,<7.0"
     

2. 对环境进行身份验证：
   • 本地 CLI 会话：gcloud auth login
   • 应用默认凭据（SDK）：gcloud auth application-default login
   • 服务账号密钥文件（CI 所需时）：设置 GOOGLE_APPLICATION_CREDENTIALS={key_file_path}
3. 选择或创建项目，验证结算信息，并选择受支持的网关位置：
   • 选择现有项目（gcloud config set project {project_id}），或创建项目（可作为备用方案运行 gcloud projects create {project_id}）。
   • 确认 {project_id} 已关联有效的结算账号（即使使用 API Gateway 免费定价层，也必须关联）。
   • API Gateway 命令默认使用 us-central1 作为 --location。其他受支持的区域请参阅 API Gateway 部署模型。
4. 启用所需的 Google Cloud API：

   gcloud services enable \
     apigateway.googleapis.com \
     servicemanagement.googleapis.com \
     servicecontrol.googleapis.com \
     iam.googleapis.com \
     apikeys.googleapis.com \
     --project={project_id}
   

   API Gateway 无需启用 Cloud Run API。如果后端运行在 Cloud Run 上，该 API 已在后端所属的项目中启用。
5. 确认具备所需的 IAM 角色：
   • 管理 API Gateway 资源和启用服务：roles/apigateway.admin 和 roles/serviceusage.serviceUsageAdmin
   • 创建网关服务账号并将其关联到 API 配置：roles/iam.serviceAccountAdmin 和 roles/iam.serviceAccountUser
   • 在使用方项目中管理 API 密钥：roles/serviceusage.apiKeysAdmin
   • 允许网关服务账号调用后端：roles/run.invoker（Cloud Run 或第 2 代函数）或 roles/cloudfunctions.invoker（第 1 代函数）

决策矩阵：客户端身份验证、后端安全和配额

选择符合安全要求的层：

目标	要配置的机制	关键限制	详细参考
识别调用方使用方项目，以便进行配额和账单管理	API 密钥（x-api-key 请求头约定；key 查询参数备用方案）	切勿仅依赖 API 密钥来验证最终用户身份。**理由：**API 密钥标识的是 Google Cloud 项目，而不是用户，且客户端可以提取这些密钥。	客户端身份验证
验证最终用户或调用服务的身份	JWT（OAS 2.0 中使用带有 x-google-issuer / x-google-jwks_uri 的 oauth2 方案，或 OAS 3.x 中使用 x-google-auth）	操作级 security 会覆盖根级 security。当某个端点同时需要用户身份和配额时，请在同一个安全要求对象中加入 api_key: [] 和 JWT 方案。	客户端身份验证
阻止直接调用后端服务	专用网关服务账号（--backend-auth-service-account）+ roles/run.invoker + 后端 --no-allow-unauthenticated	在运行中的后端设置 --no-allow-unauthenticated 之前，先使用 --backend-auth-service-account 部署网关配置，以避免因 403 导致服务中断。	后端安全
按使用方项目限制请求速率（1/min/{project}）	x-google-management（OAS 2.0）或 x-google-api-management（OAS 3.x）+ x-google-quota	如果该 API 的任何网关仍在运行引用该配额指标的旧配置，则在创建新 API 配置时，切勿重命名或删除配额指标。**理由：**创建配置会立即覆盖 API 级配额，并导致旧网关出现 HTTP 500 Failed to call Service Control Quota。	配额和速率限制
保护 /mcp 上的 MCP tools/list 和 tools/call（公开预览版）	x-google-api-management.mcp.tools-list.security（恰好一个 JWT 或 API 密钥方案）+ 操作 security 和 x-google-mcp-tool: false	x-google-mcp-tool: false 仅会对 MCP 隐藏某个操作；除非对底层 REST 路由进行保护或将其移除，否则该路由仍处于启用状态。	MCP 流量安全

执行工作流与验证循环

编写或更新 API Gateway 安全配置或配额配置时，请遵循以下零停机顺序：

1. 创建网关服务账号并授予后端调用者权限：
   • 按照后端安全中的步骤 1–3 创建 {gateway_sa_name}，并在向 {backend_service} 授予 roles/run.invoker 前请求人工批准。
   • 更新后端处理程序代码，从 X-Apigateway-Api-Userinfo（经过 base64url 编码的 JSON）解码已验证的用户声明，而不是从 Authorization 解码。
2. 编写 OpenAPI 身份验证和配额定义：
   • 使用客户端身份验证和配额与速率限制中的 OpenAPI 2.0 或 OpenAPI 3.0.x 模板及提供商表格。
   • 如果规范启用了 MCP（x-google-api-management.mcp），请在 tools-list 上准确配置一个 JWT 或 API key 方案（同时在根 security 列表中列出 JWT 方案），并参阅 MCP 流量安全检查各操作的退出配置。
3. 在运行 api-configs create 之前，运行配额指标验证循环：
   • 如果当前生效的规范和 {candidate_openapi_spec} 都未定义配额指标（x-google-management.metrics 或 x-google-api-management.metrics），则跳过此步骤。
   • 创建定义或修改配额的 API 配置前，请请求人工批准，因为 api-configs create 会立即替换该 API 所有网关上的配额定义。
   • 默认情况下，针对 {project_id} 中为 {api_id} 部署的所有活动网关运行 scripts/check_quota_metrics.py：

     python3 scripts/check_quota_metrics.py \
       --spec={candidate_openapi_spec} \
       --project={project_id} \
       --api={api_id}
     

   • 离线环境无法访问 gcloud 时的备用方案（为 API 网关当前提供服务的每个配置传入 --baseline-spec）：

     python3 scripts/check_quota_metrics.py \
       --spec={candidate_openapi_spec} \
       --baseline-spec={previous_openapi_spec} \
       --dry-run
     

   • 如果 scripts/check_quota_metrics.py 以代码 1 退出（status: "FAIL"），请将缺少的指标和限制重新添加到 {candidate_openapi_spec}，将 ignored_quota_extensions 中列出的每个 x-google-quota 移到其适用的操作中，并重新运行脚本，直到它以代码 0 退出（status: "PASS"）。如果用户有意移除某项限制，请与用户确认，因为这会从该 API 的每个网关中移除该限制。如果 skipped_configs 不为空，请告知用户脚本未检查这些 API 配置（例如 gRPC 配置），并手动检查其配额指标和限制。如果脚本以代码 2 退出，请修复 stderr 中打印的问题：CLI 参数、gcloud 身份验证，或脚本无法检查的 API 配置。
4. 创建 API 配置、更新网关、启用托管服务并锁定后端：
   • 按照后端安全中的步骤 4–5 运行 gcloud api-gateway api-configs create 和 gcloud api-gateway gateways update（更新生产网关前请求人工批准），在使用方项目中启用该 API 的 managedService（客户端身份验证），然后使用 --no-allow-unauthenticated 限制对 {backend_service} 的访问。
   • 验证：直接调用后端 *.run.app URL 会返回 403，未通过身份验证的调用网关 defaultHostname 会返回 401，通过身份验证的调用会返回 200。

部署前检查清单

• 专用的 {gateway_sa_name} 已获授 roles/run.invoker（或 roles/cloudfunctions.invoker），并且在网关配置生效后应用了 --no-allow-unauthenticated。
• 后端代码会解码 X-Apigateway-Api-Userinfo，以获取用户声明。
• 安全执行机制不单纯依赖网关前方的负载均衡器或 Google Cloud Armor，因为无法停用网关的 defaultHostname（*.gateway.dev）。
• 每个受配额限制的操作都要求使用 API 密钥（api_key: []），并且 API 的 managedService 已启用，且已在每个使用方项目中允许该 API 密钥使用。
• 针对活动网关配置或所有基线规范运行 python3 scripts/check_quota_metrics.py，并返回 status: "PASS"（退出代码 0），然后再执行 api-configs create。
• 如果启用了 MCP，x-google-api-management.mcp.tools-list.security 必须准确指定一个 JWT 或 API 密钥方案（JWT 方案也必须列在根级 security 列表中），并且除设置 x-google-mcp-tool: false 外，还必须通过 REST 保护管理端点。

资源清理

为避免拆除测试或预发布环境时持续产生费用，请先获得人工批准，然后按依赖顺序删除网关、所有 API 配置、API 和服务账号：

gcloud api-gateway gateways delete {gateway_id} --location={region} --project={project_id}
gcloud api-gateway api-configs delete {config_id} --api={api_id} --project={project_id}
gcloud api-gateway apis delete {api_id} --project={project_id}
gcloud iam service-accounts delete {gateway_sa_name}@{project_id}.iam.gserviceaccount.com --project={project_id}