基于 IAM 的 API 身份验证概览

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

Apigee 支持为 API 代理提供基于 IAM 的身份验证和授权。如需使用此功能，请在代理的请求流中添加 VerifyIAM 政策，并将 API 使用方的用户标识符（通常是邮箱）配置为拥有调用 Apigee API 所需的 Google Cloud IAM 角色或权限。API 请求应传递该用户的有效 Google Cloud 访问令牌。

管理员可以向任何 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 主账号的角色或权限。

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

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

APIGEE_ORG=GCP_PROJECT
USER=USER_EMAIL_HERE
gcloud projects add-iam-policy-binding "${APIGEE_ORG}" --member="${USER}" \
    --role='roles/apigee.deploymentInvoker'

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

APIGEE_ORG=GCP_PROJECT
USER=USER_EMAIL_HERE
gcloud projects remove-iam-policy-binding "${APIGEE_ORG}" --member="${USER}" \
    --role='roles/apigee.deploymentInvoker'

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

如需向单个用户添加对特定部署的调用方角色，请运行以下命令：

APIGEE_ORG=GCP_PROJECT
ENV=APIGEE_ENVIRONMENT
API=APIPROXY_NAME
USER=USER_EMAIL_HERE
TOKEN=$(gcloud auth print-access-token)
curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_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-email@example.com"
        ]
      }
    ]
  }

如需向多个用户添加对特定部署的调用方角色，请运行以下命令：

APIGEE_ORG=GCP_PROJECT
ENV=APIGEE_ENVIRONMENT
API=APIPROXY_NAME
USER1=EMAIL_FOR_USER1
USER2=EMAIL_FOR_USER2
USER3=EMAIL_FOR_USER3
TOKEN=$(gcloud auth print-access-token)
curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:setIamPolicy" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "policy": {
    "bindings": [
      {
        "members": [
        "user:'"$USER1"'",
        "user:'"$USER2"'",
        "user:'"$USER3"'"
        ],
        "role": "roles/apigee.deploymentInvoker"
      }
    ]
  }
}'

如需查询之前设置的政策对象，请运行以下命令：

curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:getIamPolicy" \
  --header "Authorization: Bearer $TOKEN"

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

用户无需直接调用部署的 API，即可验证自己是否能够访问指定部署（即是否为该用户设置了指定部署的 apigee.deployments.invoke 权限）。为此，用户可以使用自己生成的访问令牌提交以下请求：

APIGEE_ORG=GCP_PROJECT
ENV=APIGEE_ENVIRONMENT
API=APIPROXY_NAME
USER=USER_EMAIL_HERE
TOKEN=$(gcloud auth print-access-token)
curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:testIamPermissions" \
    --header "Authorization: Bearer $TOKEN" \
    --header 'Content-Type: application/json' \
    --data '{"permissions":["apigee.deployments.invoke"]}'

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

如需撤销单个用户对特定部署的访问权限，请移除该用户的 deploymentInvoker 角色。为此，请先获取当前与部署关联的政策对象：

curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:getIamPolicy" \
  --header "Authorization: Bearer $TOKEN"

成功响应内容应如下所示。

{
  "version": 1,
  "etag": "BwYT8i40Vwo=",
  "bindings": [
      {
        "role": "roles/apigee.deploymentInvoker",
        "members": [
          "user:user1-email@example.com",
          "user:user2-email@example.com",
          "user:user3-email@example.com"
        ]
      }
    ]
  }

如需移除单个用户的绑定，请使用 setIamPolicy，并在载荷中指定应继续拥有访问权限的用户，就像为这些用户设置初始访问权限一样。继续使用上例，如果您想移除 USER1 的访问权限，但保留 USER2 和 USER3 的访问权限，则可使用以下命令：

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

如需移除所有用户与特定部署的绑定，请指定一个空载荷：

  curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_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/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:testIamPermissions" \
    --header "Authorization: Bearer $TOKEN" \
    --header 'Content-Type: application/json' \
    --data '{"permissions":["apigee.deployments.invoke"]}'

此命令应该会返回相应的响应；例如，如果没有任何用户拥有调用相应 API 的权限，则返回空输出。