Google Authentication 扩展程序

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档
信息

版本:1.3.1

向 Google 进行身份验证,以便访问您指定的 Google API

使用此扩展程序获取 Google Cloud 服务的令牌(OAuth 或 JWT),然后使用该令牌对 Google API 进行后续调用,例如通过使用 ServiceCallout 政策

例如,在 API 代理中,您可能会获得具有此扩展程序的令牌,使用 PopulateCache 政策缓存令牌,然后通过 ServiceCallout 政策传递令牌,以便从 API 代理流中访问 Google Cloud 服务。

前提条件

本文内容提供了有关配置和使用此扩展程序的参考信息。在采用 ExtensionCallout 政策通过 API 代理使用扩展程序之前,您必须:

  1. 确保扩展程序使用的帐号(即您要用于凭据的服务帐号所代表的帐号)可以访问扩展程序将用来进行身份验证的 Google Cloud 服务。

  2. 使用 Google Cloud 控制台为服务帐号生成密钥

  3. 在通过配置参考添加和配置扩展程序时,使用所生成的服务帐号密钥 JSON 文件的内容。

关于使用 Google Cloud 进行身份验证

此扩展程序会代表您的 Google Cloud 项目中定义的特定成员,向 Google Cloud 请求身份验证。配置此扩展程序时,您将使用该项目成员的服务账号 JSON 文件。

因此,此扩展程序只能访问该成员有权访问的资源。换句话说,此扩展程序能否成功进行身份验证取决于 Google Cloud 控制台中授予的权限与扩展程序在运行时请求的访问权限(通过范围或受众群体)是否匹配。

一般来说,针对从此扩展程序访问 API 进行身份验证的步骤如下:

  1. 确保此扩展程序代表的成员服务账号有权访问您要访问的 Google 资源。您可以使用 Google Cloud 控制台中的 Cloud Identity and Access Management (Cloud IAM) 页面向此扩展程序所代表的项目成员授予角色

  2. 配置此扩展程序时,请使用该成员的服务帐号密钥 JSON。

  3. 配置 ExtensionCallout 政策以使用此扩展程序时,请仅对项目成员有权访问的资源进行身份验证。

示例

以下示例说明了如何使用 ExtensionCallout 政策进行 Google Cloud 身份验证。

获取访问令牌

在以下示例中,扩展程序的 getOauth2AccessToken 操作会检索令牌,以用于向 Cloud Translation API 发出的请求。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Get-Access-Token">
    <DisplayName>Get Access Token</DisplayName>
    <Connector>google-auth</Connector>
    <Action>getOauth2AccessToken</Action>
    <Input><![CDATA[{
      "scope" : [
        "https://www.googleapis.com/auth/cloud-translation"
      ]
    }]]></Input>
    <Output>google.credentials</Output>
</ConnectorCallout>

响应值如下所示:

{
  "access_token":"ya29.c.ElpSB...BMgkALBJ0kou-8",
  "token_type":"Bearer",
  "expiresInSec": 3600
}

以下 assignMessage 政策会从上述 ExtensionCallout 政策中检索响应值,并将其复制到响应载荷中。这对于调试可能很有用。在实际操作中,您可能不想将令牌返回给客户端。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage async="false" continueOnError="false" enabled="true" name="Retrieve-Auth-Token">
    <DisplayName>Retrieve Auth Token</DisplayName>
    <AssignTo type="response" createNew="false"/>
    <Set>
        <Payload contentType="application/json">{google.credentials.access_token}</Payload>
    </Set>
</AssignMessage>

缓存访问令牌

为避免进行不必要的调用来检索令牌,请考虑缓存您收到的令牌。对于需要令牌的后续调用,从 Apigee Edge 缓存中检索令牌比获取新令牌更快。当缓存的令牌过期后,检索新令牌并用其刷新缓存。

以下示例 API 代理中的以下代码说明了如何设置和使用缓存令牌,以通过 ServiceCallout 政策调用 Google Translation API。此处的每个代码示例都适用于流程中的不同政策。

以下政策按以下流程 XML 所述的顺序执行:

  <Request>
    <!-- Attempt to get a token from the cache. -->
    <Step>
        <Name>Get-Cached-Auth-Token</Name>
    </Step>
    <!-- Only execute the following ExtensionCallout policy if the call to the
      cache couldn't retrieve a cached token. -->
    <Step>
        <Name>Google-Auth-Callout</Name>
        <Condition>lookupcache.Get-Cached-Auth-Token.cachehit is false</Condition>
    </Step>
    <!-- Only execute the following PopulateCache policy if the call to the
      cache couldn't retrieve a cached token. -->
    <Step>
        <Name>Cache-Auth-Token</Name>
        <Condition>lookupcache.Get-Cached-Auth-Token.cachehit is false</Condition>
    </Step>
    <!-- Use the ServiceCallout policy to call the translate API. -->
    <Step>
        <Name>Translate-Text</Name>
    </Step>
</Request>
  1. 以下 LookupCache 政策会尝试从缓存中获取令牌。如果令牌已经获取并缓存,此政策将会获取该令牌,以供 API 代理使用。

      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
      <LookupCache async="false" continueOnError="false" enabled="true" name="Get-Cached-Auth-Token">
          <DisplayName>Get Cached Auth Token</DisplayName>
          <!-- Give cache key and scope to specify the entry for the cached token. -->
          <CacheKey>
              <Prefix/>
              <KeyFragment>gcp_translate_token_</KeyFragment>
          </CacheKey>
          <Scope>Exclusive</Scope>
          <!-- Assign the retrieved token (if any) to a variable, where it
           can be retrieved by policies. -->
          <AssignTo>cloud.translation.auth.token</AssignTo>
      </LookupCache>
    
  2. 如果在缓存查询过程中没有检索到缓存的令牌,以下 ExtensionCallout 政策会检索新的 OAuth 令牌,并将 Google Cloud Translation API 指定为该令牌的范围。如果在配置 Google-Auth-Callout 扩展程序时使用的服务帐号凭据代表有权访问该 API 的项目成员,Google Cloud 会返回有效令牌。

      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
      <ConnectorCallout async="false" continueOnError="true" enabled="true" name="Google-Auth-Callout">
          <DisplayName>Google-Auth-Callout</DisplayName>
          <Connector>example-auth-extension</Connector>
          <Action>getOauth2AccessToken</Action>
          <Input><![CDATA[{
            "scope" : ["https://www.googleapis.com/auth/cloud-translation"]
          }]]></Input>
          <Output parsed="false">cloud.translation.auth.token</Output>
      </ConnectorCallout>
    
  3. ExtensionCallout 政策检索到新令牌之后,PopulateCache 政策会将其缓存起来,以供 API 代理中的政策使用。

      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
      <PopulateCache async="false" continueOnError="false" enabled="true" name="Cache-Auth-Token">
          <DisplayName>Cache Auth Token</DisplayName>
          <Properties/>
          <!-- Set cache key information to specify a unique key for this entry. -->
          <CacheKey>
              <Prefix/>
              <KeyFragment>gcp_translate_token_</KeyFragment>
          </CacheKey>
          <Scope>Exclusive</Scope>
          <ExpirySettings>
              <TimeoutInSec>5</TimeoutInSec>
          </ExpirySettings>
          <!-- Get the token to cache from the variable where the ExtensionCallout put it. -->
          <Source>cloud.translation.auth.token</Source>
      </PopulateCache>
    

Action

getOauth2AccessToken

获取 OAuth 2.0 访问令牌。当 Google API 需要 OAuth 令牌时,使用此操作支持 API 代理和 Google API 之间的两方模式 OAuth。

在两方模式 OAuth 中,此扩展程序操作通过使用服务帐号 JSON(您可以在配置此扩展程序时添加该 JSON)进行 Google 身份验证来检索 OAuth 令牌。在此操作检索 OAuth 令牌之后,您的 API 代理可以使用该令牌调用 Google API,代表 Google 服务帐号有效地调用 API。

对 Google Cloud API 的访问权限根据 Google API 的 OAuth 2.0 范围中列出的范围进行过滤。

如需详细了解 OAuth 2.0 的服务器到服务器互动,请参阅针对服务器到服务器应用使用 OAuth 2.0

语法

<Action>getOauth2AccessToken</Action>
<Input><![CDATA[{
  "scope" : [
    "scope1",
    "scope2"
  ]
}]]></Input>

示例

在以下示例中,扩展程序的 getOauth2AccessToken 操作会检索令牌,以用于向 Cloud Translation API 发出的请求。

<Action>getOauth2AccessToken</Action>
<Input><![CDATA[{
    "scope" : [
      "https://www.googleapis.com/auth/cloud-translation"
  ]
}]]></Input>

请求参数

参数 说明 类型 默认 必需
范围 OAuth 2.0 范围的数组。要详细了解范围,请参阅 Google API 的 OAuth 2.0 范围 数组 ["https://www.googleapis.com/auth/cloud-platform"]:用于授予对服务帐号有权访问的所有 API 的访问权限。 没有。

响应

一个对象,其中包含访问令牌、其类型和到期日期,格式如下:

{
  "accessToken": "ewogICJ0eXB...C5jb20iCn0K",
  "token_type": "Bearer",
  "expiresInSec": 3600
}

响应属性

参数 说明 默认 必需
accessToken OAuth 2.0 访问令牌。
tokenType 令牌类型。 不记名
expiresInSec 距离令牌过期的秒数。 3600

getJWTAccessToken

获取 JSON Web 令牌 (JWT) 访问令牌。如果您要调用的 API 有在 Google API GitHub 代码库中发布的服务定义,则可以使用此令牌向 Google API 进行身份验证。

对于某些 Google API,您可以将已签名的 JWT 直接作为不记名令牌(而不是 OAuth 2.0 访问令牌)进行已获授权的 API 调用。如果能够做到这一点,您就不必在进行 API 调用前向 Google 的授权服务器发出网络请求。

如需详细了解如何使用 JWT 访问令牌进行身份验证,请参阅针对“服务器到服务器”应用使用 OAuth 2.0

语法

<Action>getJWTAccessToken</Action>
<Input><![CDATA[{
    "audience" : "audience"
}]]></Input>

示例:Cloud Functions 函数网址

在以下示例中,扩展程序的 getOauth2AccessToken 操作会检索令牌,以用于向 Cloud Translation API 发出的请求。

<Action>getJWTAccessToken</Action>
<Input><![CDATA[{
  "audience" : "https://YOUR_REGION-YOUR_PROJECT_ID.cloudfunctions.net/FUNCTION_NAME"
}]]></Input>

示例:受 Cloud IAP 保护的客户端 ID

在以下示例中,扩展程序的 getOauth2AccessToken 操作会检索令牌,以用于向 Cloud Translation API 发出的请求。

<Action>getJWTAccessToken</Action>
<Input><![CDATA[{
  "audience" : "Cloud-IAP-secured-client-ID"
}]]></Input>

请求参数

参数 说明 默认 必需
audience 令牌的预期接收者。这可能包括受 Cloud IAP 保护的客户端 ID、Cloud Functions 网址等。

响应

{
  "accessToken": "token",
  "tokenType": "Bearer",
  "expiresInSec": 3600
}

响应属性

参数 说明 默认 必需
accessToken 访问令牌。
tokenType 令牌类型。 不记名
expiresInSec 到期时间(以秒为单位)。 3600

配置参考文档

在配置和部署此扩展程序以在 API 代理中使用时,请使用以下代码。如需了解使用 Apigee 控制台配置扩展程序的步骤,请参阅添加和配置扩展程序

通用扩展属性

每个扩展程序都有以下属性。

属性 说明 默认 必需
name 您为扩展程序配置此名称。
packageName Apigee Edge 提供的扩展包的名称。
version 配置扩展程序所用的扩展程序软件包的版本号。
configuration 特定于您要添加的附加信息的配置值。请参阅此扩展程序软件包的属性

此扩展程序软件包的属性

为此扩展程序的以下配置属性指定值。

媒体资源 说明 默认 必需
凭据 在 Apigee Edge 控制台中输入时,这是服务帐号密钥 JSON 文件的全部内容。通过 Management API 发送时,它是从整个服务帐号密钥 JSON 文件生成的 base64 编码值。