基于 IAM 的 API 身份验证概览

本页面适用于 Apigee，但不适用于 Apigee Hybrid。

Apigee 支持为 API 代理提供基于 IAM 的身份验证和授权。借助此解决方案，调用 API 的访问权限取决于多个因素，包括请求流是否包含 VerifyIAM 政策，以及 API 使用方是否具有调用 Apigee API 所需的 Google Cloud IAM 角色或权限。您可以向任何 Google Cloud 主账号授予授权，而不仅限于个人用户。

使用基于 IAM 的访问权限控制

本部分介绍了设置基于 IAM 的身份验证和授权的端到端流程、在设置访问权限后如何评估请求，以及如何撤消之前有访问权限的 API 使用方访问权限。

添加访问权限管理

如需为 API 代理设置访问管理，请执行以下操作：

将 VerifyIAM 政策添加到 Apigee API 代理或代理中，作为请求流的一部分。
Apigee 项目的 Cloud 管理员：
1. 向 API 使用方的 Google Cloud 主账号在项目级授予 deploymentInvoker IAM 角色（或具有 apigee.deployments.invoke IAM 权限的自定义角色）。这样，API 使用方便可调用关联 Apigee 组织中的所有托管 API。
  
  或
2. 使用 SetIamPolicy 操作在特定部署中向 API 使用方的 Google Cloud 原则授予角色或权限，或在多个部署中迭代授予角色或权限。使用部署资源上的列出操作可查看环境中的所有部署，包括 API 代理和共享流。部署的名称是 API 代理或共享流的名称。
  注意：在共享流部署中添加角色或权限不会对共享流创建 VerifyIAM 政策检查；请仅将权限应用于代理。对于调用共享流的代理，应将权限应用于代理。使用代理链时，请使用该政策向代理授予权限；无需在链中的其他代理上授予权限。
指示 API 使用方生成访问令牌，并在 Apigee API 请求中传递该令牌以进行权限检查。生成的令牌必须具有 https://www.googleapis.com/auth/cloud-platform 授权范围。

管理员操作

本部分列出了 API 管理员（API 提供方）在管理基于 IAM 的权限时执行的操作。

管理基于 IAM 的访问权限时使用的基于 API 的操作的文档，可在 organizations.environments 和 organizations.environments.deployments API 参考文档中找到，其中包括 SetIamPolicy、GetIamPolicy、TestIamPermissions 和 GetDeployment 操作。

下表将操作与所需权限进行了对应：

管理员操作	操作	需要 IAM 权限	需要权限的 IAM 资源^*
GetDeployment	检索 Apigee 环境中部署的信息	apigee.deployments.get	Google Cloud 项目或 Apigee 环境
ListDeployments	列出 Apigee 环境中的部署	apigee.deployments.list	项目或 Apigee 环境
SetIamPolicy	为特定 API 部署的 API 使用方设置调用访问权限	apigee.deployments.setIamPolicy	Google Cloud 项目或 Apigee 环境
GetIamPolicy	为 API 部署提取一组调用访问权限设置	apigee.deployments.getIamPolicy	Google Cloud 项目或 Apigee 环境
TestIamPermissions	检查调用此 API 的用户是否具有载荷中提及的权限	无需 IAM 权限	不适用

^* Google Cloud 项目是用于配置 Apigee 的项目。Apigee 环境级权限是使用 setIAMPolicy 在环境中设置的。

运行时访问权限检查

当 API 使用方尝试使用基于 IAM 的访问权限控制访问 API 时，系统会检查他们是否拥有必要的访问令牌以及项目或部署级别的适当角色或权限。如果是，则允许他们继续访问代理。否则，系统会将其屏蔽。

移除访问权限

如需在项目级别移除访问权限：为了移除在项目级别管理的 API 使用方的访问权限，Apigee 项目的 Cloud 管理员会撤消 API 使用方的 Google Cloud 项目的 Google Cloud 主账号的 deploymentInvoker IAM 角色（或具有 apigee.deployments.invoke IAM 权限的自定义角色）。

如果您使用 setIamPolicy 授予各个部署的访问权限，请使用其他 setIamPolicy 操作从部署中移除角色或权限。

基于 IAM 的访问权限控制的特性和限制

使用基于 IAM 的身份验证和授权时，请注意以下特性和限制：

通常，使用 VerifyIAM 执行政策大约需要 10 毫秒。不过，某些调用可能会遇到大约 50 毫秒的完成延迟。例如，在 asia-east2 区域，平均延迟可能会上升到 50 毫秒，并且某些调用可能需要大约 100 毫秒才能完成。

请注意，这些延迟时间数据并不能保证一定准确。
为代理添加 VerifyIAM 政策仅是验证/未验证检查；API 使用者的特定角色和权限不会在请求或响应流中的后续流程中考虑。
由于只有在执行 VerifyIAM 政策时才会执行授权检查，因此 VerifyIAM 应是请求流程中的第一个政策，仅在流量管理政策之后。
如果权限验证成功或 API 提供方已将 VerifyIAM 政策标记为在发生错误时继续执行，则请求流会继续执行其他政策（如果有）并最终到达目标服务器。如果权限检查失败，且 API 提供方未将政策标记为在发生错误时继续执行，则用户会收到错误。
在环境级别添加调用访问权限 (apigee.deployments.invoke) 不会传达对环境中所有 API 部署的调用访问权限。
部署资源不支持 IAM 条件，因此无法用于控制调用访问权限。如需了解详情，请参阅将 Apigee IAM Conditions 条件添加到政策。
基于 IAM 的访问权限控制在单个政策中最多支持 1,500 个角色绑定，并存在其他限制。请参阅 IAM 配额和限制。
基于 IAM 的访问权限控制会受到 IAM 传播延迟的影响。
尝试通过部署级 setIAMPolicy 管理其他 apigee.deployments 操作（例如 apigee.deployments.delete）将不会生效，但也不会返回错误。只有 apigee.deployements.invoke 有效。
当相应代理从环境中取消部署或删除时，部署的访问权限会被删除；在重新部署时，需要重新添加访问权限。
混合模式目前不支持基于 IAM 的身份验证和授权。

示例

本部分提供了一些示例，说明如何授予和撤消基于 IAM 的 API 访问权限。这些示例均假定 VerifyIAM 已添加到相应的 API 代理。

在这些示例中，请使用 Cloud 控制台或 gcloud（如图所示）来管理 API 使用方的 Google Cloud 主账号的角色或权限。示例中的 $Project 是 Google Cloud 项目。

授予和撤消用户对 Apigee 组织中所有 API 的调用访问权限

如需添加访问权限，请添加 deploymentInvoker 角色：

gcloud projects add-iam-policy-binding {$Project} --member={$user} --role='roles/apigee.deploymentInvoker'

如需撤消访问权限，请移除 deploymentInvoker 角色：

gcloud projects remove-iam-policy-binding {$Project} --member={$user} --role='roles/apigee.deploymentInvoker'

授予和撤消用户对环境内特定部署的访问权限

如需向特定部署添加用户的调用方角色，请执行以下操作：

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:setIamPolicy' \
    --header 'Authorization: Bearer $TOKEN ' \
    --header 'Content-Type: application/json' \
    --data '{"policy":{"bindings":[{"members":["user:$user"],"role":"roles/apigee.deploymentInvoker"}]}}'

成功响应应如下所示：

  {
    "version": 1,
    "etag": "BwYT8i40Vwo=",
    "bindings": [
      {
        "role": "roles/apigee.deploymentInvoker",
        "members": [
          "user:$user"
        ]
      }
    ]
  }

如需确认您添加的政策对象是否已正确保留（可选），请执行以下操作：

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:getIamPolicy' \
  --header 'Authorization: Bearer $TOKEN'

您应该会看到如上所示的成功响应。

为了让用户验证自己是否能够访问指定部署（是否已为指定部署中的指定用户设置 apigee.deployments.invoke 权限），请指示用户使用他们之前生成的访问令牌提交此请求：

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:testIamPermissions' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"permissions":["apigee.deployments.invoke"]}'

响应应包含用户的 apigee.deployments.invoke 权限。

如需撤消对特定部署的访问权限，请移除 deploymentInvoker 角色。首先，获取当前与部署关联的政策对象：

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:getIamPolicy' \
  --header 'Authorization: Bearer $TOKEN'

成功响应内容应如下所示：请注意，您可能还会看到其他绑定。

{
  "version": 1,
  "etag": "BwYT8i40Vwo=",
  "bindings": [
      {
        "role": "roles/apigee.deploymentInvoker",
        "members": [
          "user:$user"
        ]
      }
    ]
  }

如需移除绑定，请执行以下操作：

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:setIamPolicy' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{}'

请注意，提供空载荷会移除所有用户的访问权限，但在本示例中，这是一种合适的做法，因为我们只有一位用户拥有访问权限。如果在其他用户应继续拥有访问权限的情况下移除用户访问权限，请在载荷中指定应继续拥有访问权限的用户，就像为这些用户设置初始访问权限一样。

如需验证绑定是否已移除，请确保部署中不存在针对该用户的 apigee.deployments.invoke 权限：

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:testIamPermissions' \
  --header 'Authorization: Bearer $USER_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"permissions":["apigee.deployments.invoke"]}'

如果没有用户拥有此权限，则应返回空输出。