使用 Google 身份验证

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

本主题介绍如何设置和部署配置为使用 Google 身份验证的 API 代理。

Apigee Hybrid 用户：如果您使用的是 Apigee Hybrid，请注意只有 Apigee Hybrid v1.6.x 及更高版本支持此功能。

简介

Apigee 支持使用 Google OAuth 令牌或 OpenID Connect 令牌向 Google 服务（例如 Cloud Logging 和 Secret Manager）以及在某些 Google Cloud 产品（例如 Cloud Functions 和 Cloud Run）上运行的自定义服务进行身份验证。

如需使用此功能，您必须在以下任一上下文中配置 <Authentication> XML 元素：

• ServiceCallout 政策
• ExternalCallout 政策
• TargetEndpoint 配置

在您完成一些基本设置步骤（如本主题中所述）后，Apigee 会执行令牌生成操作，并为您安全调用目标 Google 服务或自定义托管服务，而无需手动设置身份验证标头或修改服务请求。从 API 开发者的角度来看，从正确配置的 API 代理内部调用 Google 服务的过程是无缝处理的。

API 代理配置选项

本部分介绍在何处可以使用 <Authentication> XML 元素以启用 Google OAuth 令牌或 OpenID Connect 身份验证：

配置选项	说明
ServiceCallout 政策	借助 ServiceCallout 政策，您可以从 API 代理调用其他内部或外部服务。例如，您可以使用 ServiceCallout 来调用外部 Google 服务或自定义托管服务。如需了解使用详情和示例，请参阅 ServiceCallout 政策。
ExternalCallout 政策	通过 ExternalCallout 政策，您可以向 gRPC 服务器发送 gRPC 请求，以实现 Apigee 政策不支持的自定义行为。如需了解使用详情和示例，请参阅 ExternalCallout 政策。
TargetEndpoint	将 Google 服务或自定义托管服务指定为 API 代理目标端点。如需了解使用详情和示例，请参阅 API 代理配置参考文档。

Google 身份验证令牌支持的上下文

<Authentication> 元素有两个子元素配置：<GoogleAccessToken> 或 <GoogleIDToken>。下表显示了支持这些元素的上下文：

用于	GoogleAccessToken	GoogleIDToken
ServiceCallout 政策	支持	支持
ExternalCallout 政策	不支持	支持
TargetEndpoint	支持	支持

注意：ExternalCallout 政策无法调用 Google API，因此不支持 Google 访问令牌。不过，该政策支持 OpenID Connect 令牌，因此，如果目标服务托管在 Cloud Run 之类的产品中，则该政策可以无缝连接到该服务。

注意：请避免使用非 SSL 动态目标。例如，请避免替换 target.url 流变量以指向非 SSL 目标端点。如果使用非 SSL 动态目标，则系统仍会生成 Google 身份验证令牌；但是，该身份验证令牌将以纯文本形式公开。

部署步骤

本部分介绍了如何部署一个使用 Google 身份验证来调用目标 Google 服务或自定义托管服务的 API 代理。我们分别介绍了 Apigee 和 Apigee Hybrid 的部署步骤。

注意：共享流部署还支持在支持的政策和 TargetEndpoint 配置中使用 Authentication 标记。另请参阅共享流部署 API 文档。

在 Apigee 上部署

以下步骤说明了如何在 Apigee 上部署 API 代理，其中代理配置为对 Google 服务或自定义托管服务进行经过身份验证的调用。这些步骤假定您已创建代理，并且其在其中一个受支持的上下文中包含 <Authentication> 元素。

1. 在创建了 Apigee 组织的同一 Google Cloud 项目中创建 Google 服务账号。您在部署配置为使用 Google 身份验证的 API 代理时，必须提供此服务账号的名称，且生成的 OAuth 令牌将代表服务账号。您可以在 Google Cloud 控制台中或使用 gcloud 命令创建服务账号。请参阅创建和管理服务账号。
2. 向将要执行部署的用户（部署者）授予服务账号的 iam.serviceAccounts.actAs 权限。另请参阅服务账号权限简介。
   注意：在服务账号中具有 Service Account User 角色的用户可以用其间接访问该服务账号有权访问的所有资源。如需了解详情，请参阅 Service Account User 角色。我们建议为服务账号配置最小权限，以最大限度地减少用户角色分配的影响。
   注意：如果部署者已具有足够的权限（例如，通过界面进行部署，并且 Google Cloud 用户在项目中拥有 Owner 角色），则此步骤可能是可选操作。

   gcloud iam service-accounts add-iam-policy-binding \
   SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
   --member="MEMBER" \
     --role="roles/iam.serviceAccountUser"
   

其中：

• PROJECT_ID：项目 ID。此 ID 与您的组织名称相同。
• SA_NAME：您在创建服务账号时提供的名称。
• MEMBER：要添加绑定的成员。格式应为 user|group|serviceAccount:email 或 domain:domain，
3. 授予服务账号与目标 Google 服务通信所需的权限。例如，如果要调用 Google Logging 服务，此服务账号必须包含与该服务通信所需的权限。另请参阅了解角色。
4. 在部署配置为使用 Google 身份验证的 API 代理之前，您需要执行以下操作：
   • 您之前创建的服务账号的名称。例如：SA_NAME@PROJECT_ID.iam.gserviceaccount.com
   • 作为执行部署的用户（部署者），您必须已经拥有服务账号的 iam.serviceAccounts.actAs 权限。请参阅授予、更改和撤消对资源的访问权限。
5. 部署包含您实现的 Google 身份验证配置的 API 代理。您可以使用 Apigee 界面或 API 来部署代理。如需了解详情，请参阅部署 API 代理。
   • 如果使用界面，系统会要求您提供服务账号名称。使用您在第 1 步中创建的代理服务账号的名称。例如：SA_NAME@PROJECT_ID.iam.gserviceaccount.com。

     

   • 如果您希望使用 Apigee 部署 API 来部署代理，则可以使用以下示例 cURL 命令。请注意，该命令包含作为查询参数服务账号名称。这是您在第 1 步中创建的服务账号的名称：

     curl -H "Authorization: Bearer $TOKEN" \
     "https://apigee.googleapis.com/v1/organizations/ORG_NAME/environments/ENV_NAME/apis/apiproxy/revisions/2/deployments?serviceAccount=SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
     -H "Content-Type: application/json" -X POST

     其中：

     • TOKEN：为换取 Google 凭据而必须获取的 OAuth 令牌。如需了解详情，请参阅获取 OAuth 2.0 访问令牌。
     • ORG_NAME：您的 Apigee 组织名称。
     • ENV_NAME：要在其中部署 API 代理的环境的名称。
     • SA_NAME：创建服务账号时提供的名称。
     • PROJECT_ID：您的 Google Cloud 项目 ID（与组织名称相同）。
6. 部署完成后，测试您的 API 代理，确保 Google 服务返回预期响应。

在 Apigee Hybrid 上部署

以下步骤说明了如何将 API 代理部署到 Apigee Hybrid，该代理已配置为对 Google 服务进行经过身份验证的调用。这些步骤假定您已创建代理，并且其在其中一个受支持的上下文中包含 <Authentication> 元素。

注意：下面的第 1-3 步为必需步骤，但都是一次性设置步骤。

1. 使用以下方法之一为 Apigee Hybrid 运行时组件创建服务账号和密钥：
   注意：如果您已经在安装 Apigee Hybrid 时创建了 apigee-runtime 服务账号，则可以跳过此步骤。
   • 使用 Apigee Hybrid 提供的 create-service-account 工具创建 apigee-runtime 服务账号。该工具会创建服务账号并返回服务账号密钥。如需了解详情，请参阅 create-service-account。
   • 在 Google Cloud 控制台中或使用 gcloud 命令创建服务账号。请参阅创建和管理服务账号。 如需提取服务账号密钥，请参阅创建和管理服务账号密钥。
   注意：您可以在有权创建的任何 Google Cloud 项目中创建运行时服务账号。您无需在 Apigee 组织所用的项目中创建。
2. 打开您的 overrides.yaml 文件，并为需要 Google 身份验证功能的每种环境指定服务账号密钥文件的路径：

   envs:
     - name: "ENVIRONMENT_NAME"
       serviceAccountPaths:
         runtime: "KEY_FILE_PATH"

   注意：如果您有多个环境需要 Google 身份验证功能，则每个环境都可以有自己的服务账号，或者可以共享同一服务账号。另请参阅服务账号权限简介。

   例如：

   envs:
     - name: "test"
       serviceAccountPaths:
         runtime: "./service_accounts/my_runtime_sa.json"

3. 使用 apigeectl apply 将替换文件应用于集群。
4. 创建第二个服务账号，我们称之为代理服务账号。此服务账号必须位于您用于创建 Apigee 组织的同一 Google Cloud 项目中。当您部署配置为使用 Google 身份验证的 API 代理时，您必须提供此服务账号的电子邮件地址，并且生成的 OAuth 令牌将代表该服务账号。
5. 向将要执行部署的用户（部署者）授予服务账号的 iam.serviceAccounts.actAs 权限。 另请参阅服务账号权限简介。
   注意：在服务账号中具有 Service Account User 角色的用户可以用其间接访问该服务账号有权访问的所有资源。如需了解详情，请参阅 Service Account User 角色。我们建议为服务账号配置最小权限，以最大限度地减少用户角色分配的影响。
   注意：如果部署者已具有足够的权限（例如，通过界面进行部署，并且 Google Cloud 用户在项目中拥有 Owner 角色），则此步骤可能是可选操作。

   gcloud iam service-accounts add-iam-policy-binding \
   SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
   --member="MEMBER" \
     --role="roles/iam.serviceAccountUser"
   

其中：

• PROJECT_ID：项目 ID。此 ID 与您的组织名称相同。
• SA_NAME：您在创建服务账号时提供的名称。
• MEMBER：要添加绑定的成员。应采用 user|group|serviceAccount:email 或 domain:domain 格式。
6. 授予代理服务账号与目标 Google 服务通信所需的权限。例如，如果要调用 Google Logging 服务，此服务账号必须包含与该服务通信所需的权限。另请参阅了解角色。
7. 确保运行时能够模拟代理服务账号。如需提供此功能，请向运行时服务账号授予代理服务账号的 iam.serviceAccountTokenCreator 角色。另请参阅服务账号权限简介。例如：

   gcloud iam service-accounts add-iam-policy-binding \
   PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
   --member=serviceAccount:RUNTIME_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
   --role=roles/iam.serviceAccountTokenCreator
   

   其中：

   • PROJECT_ID：项目 ID。此 ID 与您的组织名称相同。请注意，您不必使用与组织关联的项目来创建运行时服务账号。只需确保在此命令中使用正确的项目 ID 即可。
   • PROXY_SA_NAME：代理服务账号的 ID。
   • RUNTIME_SA_NAME：运行时服务账号的 ID。
8. 在部署配置为使用 Google 身份验证的 API 代理之前，您需要执行以下操作：
   • 您之前创建的代理服务账号的名称。例如：PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com
   • 作为执行部署的用户，您必须在已预配 Apigee 组织的 Google Cloud 项目中拥有或被授予 iam.serviceAccounts.actAs 权限。请参阅授予、更改和撤消对资源的访问权限。
9. 部署包含您实现的 Google 身份验证配置的 API 代理。您可以使用 Apigee 界面或 API 来部署代理。如需了解详情，请参阅部署 API 代理。
   • 如果使用界面，系统会要求您提供服务账号名称。使用您之前创建的代理服务账号的名称。例如：PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com。

     

   • 如果您希望使用 Apigee 部署 API 来部署代理，则可以使用以下示例 cURL 命令。请注意，该命令包含作为查询参数服务账号名称。这是代理服务账号的名称：

     curl -H "Authorization: Bearer $TOKEN" \
     "https://apigee.googleapis.com/v1/organizations/ORG_NAME/environments/ENV_NAME/apis/apiproxy/revisions/2/deployments?serviceAccount=PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
     -H "Content-Type: application/json" -X POST

     其中：

     • TOKEN：为换取 Google 凭据而必须获取的 OAuth 令牌。如需了解详情，请参阅获取 OAuth 2.0 访问令牌。
     • ORG_NAME：您的 Apigee 组织名称。
     • ENV_NAME：要在其中部署 API 代理的环境的名称。
     • PROXY_SA_NAME：代理服务账号的名称。
     • PROJECT_ID：您的 Google Cloud 项目 ID（与组织名称相同）。
10. 部署完成后，测试您的 API 代理，确保 Google 服务返回预期响应。

服务账号权限简介

如需配置 API 代理以使用 Google 身份验证，您必须按照下表中的说明创建服务账号。另请参阅创建和管理服务账号。

服务账号	对于以下各项是必需的	说明
代理	Apigee 和 Apigee Hybrid	具有 API 代理对目标 Google 服务进行身份验证调用所需的权限。 必须在与 Apigee 组织相同的 Google Cloud 项目中创建。 执行部署的用户（部署者）必须拥有代理服务账号的 iam.serviceAccounts.actAs 权限。 必须包含与特定目标 Google 服务通信所需的权限。例如，如果要调用 Google Logging 服务，此服务账号必须包含与该服务通信所需的权限。另请参阅了解角色。 部署使用 Google 身份验证的代理时，必须提供服务账号的名称。
运行时	仅限 Apigee Hybrid	允许 Apigee 运行时生成令牌，以在 API 代理请求的 Google 服务上进行身份验证。此服务账号“模拟”代理专用服务账号，并代表其进行经过身份验证的调用。 为了能够模拟代理服务账号并创建令牌，运行时服务账号必须拥有代理服务账号上的角色 roles/iam.serviceAccountTokenCreator。请参阅管理对服务账号的访问权限。