使用 Google 身份验证

本页面适用于 ApigeeApigee Hybrid

查看 Apigee Edge 文档。

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

简介

Apigee 支持使用 Google OAuth 令牌OpenID Connect 令牌向 Google 服务(例如 Cloud LoggingSecret Manager)以及在某些 Google Cloud 产品(例如 Cloud FunctionsCloud 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 支持 支持

部署步骤

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

在 Apigee 上部署

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

  1. 在创建了 Apigee 组织的同一 Google Cloud 项目中创建 Google 服务账号。您在部署配置为使用 Google 身份验证的 API 代理时,必须提供此服务账号的名称,且生成的 OAuth 令牌将代表服务账号。您可以在 Google Cloud 控制台中或使用 gcloud 命令创建服务账号。请参阅创建和管理服务账号
  2. 向将要执行部署的用户(部署者)授予服务账号的 iam.serviceAccounts.actAs 权限。另请参阅服务账号权限简介
    gcloud iam service-accounts add-iam-policy-binding \
    SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --member="MEMBER" \
      --role="roles/iam.serviceAccountUser"
    
  3. 其中:

    • PROJECT_ID:项目 ID。此 ID 与您的组织名称相同。
    • SA_NAME:您在创建服务账号时提供的名称。
    • MEMBER:要添加绑定的成员。格式应为 user|group|serviceAccount:emaildomain:domain
  4. 授予服务账号与目标 Google 服务通信所需的权限。例如,如果要调用 Google Logging 服务,此服务账号必须包含与该服务通信所需的权限。另请参阅了解角色
  5. 在部署配置为使用 Google 身份验证的 API 代理之前,您需要执行以下操作:
    • 您之前创建的服务账号的名称。例如:SA_NAME@PROJECT_ID.iam.gserviceaccount.com
    • 作为执行部署的用户(部署者),您必须已经拥有服务账号的 iam.serviceAccounts.actAs 权限。请参阅授予、更改和撤消对资源的访问权限
  6. 部署包含您实现的 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(与组织名称相同)。
  7. 部署完成后,测试您的 API 代理,确保 Google 服务返回预期响应。

在 Apigee Hybrid 上部署

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

  1. 使用以下方法之一为 Apigee Hybrid 运行时组件创建服务账号和密钥:
  2. 打开您的 overrides.yaml 文件,并为需要 Google 身份验证功能的每种环境指定服务账号密钥文件的路径:
    envs:
      - name: "ENVIRONMENT_NAME"
        serviceAccountPaths:
          runtime: "KEY_FILE_PATH"

    例如:

    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 权限。 另请参阅服务账号权限简介
    gcloud iam service-accounts add-iam-policy-binding \
    SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --member="MEMBER" \
      --role="roles/iam.serviceAccountUser"
    
  6. 其中:

    • PROJECT_ID:项目 ID。此 ID 与您的组织名称相同。
    • SA_NAME:您在创建服务账号时提供的名称。
    • MEMBER:要添加绑定的成员。应采用 user|group|serviceAccount:email 或 domain:domain 格式。
  7. 授予代理服务账号与目标 Google 服务通信所需的权限。例如,如果要调用 Google Logging 服务,此服务账号必须包含与该服务通信所需的权限。另请参阅了解角色
  8. 确保运行时能够模拟代理服务账号。如需提供此功能,请向运行时服务账号授予代理服务账号的 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。
  9. 在部署配置为使用 Google 身份验证的 API 代理之前,您需要执行以下操作:
    • 您之前创建的代理服务账号的名称。例如:PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com
    • 作为执行部署的用户,您必须在已预配 Apigee 组织的 Google Cloud 项目中拥有或被授予 iam.serviceAccounts.actAs 权限。请参阅授予、更改和撤消对资源的访问权限
  10. 部署包含您实现的 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(与组织名称相同)。
  11. 部署完成后,测试您的 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。请参阅管理对服务账号的访问权限