Google 驗證擴充功能

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件
資訊

版本:1.3.1

透過 Google 驗證存取您指定的 Google API

使用這個擴充功能取得 Google Cloud 服務的憑證 (OAuth 或 JWT),然後使用該憑證向 Google API 呼叫 Google API,例如透過 Service callout 政策

舉例來說,在 API Proxy 中,您可以使用這項擴充功能取得權杖,請使用 PopulateCache 政策快取權杖,然後透過 Service callout 政策傳送權杖,即可從 API Proxy 流程中存取 Google Cloud 服務。

必要條件

本文提供設定和使用這個擴充功能的參考資料。透過 Extension callout 政策透過 API Proxy 使用擴充功能前,您必須:

  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. 設定 Extension callout 政策時,請只針對你的專案成員有權存取的資源要求驗證。

範例

以下範例說明如何使用 Extension callout 政策透過 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 政策會從上述 Extension callout 政策擷取回應值,並在回應酬載中複製該值。這對於偵錯非常實用。實際上,您可能不會想要將權杖傳回用戶端。

<?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 Proxy 範例的程式碼,說明如何設定及使用快取憑證,透過 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 Proxy 使用。

      <?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. 如果快取查詢未擷取快取權杖,則以下 Extension callout 政策會擷取新的 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. Extension callout 政策擷取新權杖後,PopulateCache 政策會快取新權杖,以供 API Proxy 中的政策日後使用。

      <?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>
    

動作

getOauth2AccessToken

取得 OAuth 2.0 存取權杖。當 Google API 需要 OAuth 權杖時,這項操作即可在 API Proxy 和 Google API 之間支援雙足式 OAuth。

在雙足式 OAuth 中,這項擴充功能動作會使用服務帳戶 JSON 向 Google 進行驗證,藉此擷取 OAuth 權杖 (設定這項擴充功能時須加入該 JSON)。這個動作擷取 OAuth 權杖後,您的 API Proxy 即可使用該憑證呼叫 Google API,有效地代表 Google 服務帳戶呼叫 API。

系統會按照 Google API 適用的 OAuth 2.0 範圍一文所列的範圍,篩選 Google Cloud API 的存取權。

如要進一步瞭解如何與 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 Token (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 函式網址

在以下範例中,擴充功能的 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>

要求參數

參數 說明 預設 需要
目標對象 權杖的適用收件者。包括受 Cloud IAP 保護的用戶端 ID、Cloud Functions 網址等。

回應

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

回應屬性

參數 說明 預設 需要
accessToken 存取權杖。
tokenType 權杖類型。 承載系統
expiresInSec 會在幾秒內失效。 3600

設定參考資料

如果您要設定及部署這個擴充功能,以便用於 API Proxy,請按照下列指示操作。如需使用 Apigee 控制台設定擴充功能的相關步驟,請參閱「新增及設定擴充功能」。

常見擴充功能屬性

每個擴充功能都有下列屬性。

屬性 說明 預設 必要
name 您要為這項擴充功能設定的名稱。 相容
packageName Apigee Edge 指定的擴充功能套件名稱。 相容
version 擴充功能的擴充功能套件版本號碼。 相容
configuration 您要新增的擴充功能專屬的設定值。請參閱「這個擴充功能套件的屬性」一文 相容

這個擴充功能套件的屬性

指定這個擴充功能的下列設定屬性值。

屬性 說明 預設 需要
憑證 在 Apigee Edge 控制台中輸入時,這是服務帳戶金鑰 JSON 檔案的所有內容。透過 Management API 傳送時,是由整個服務帳戶金鑰 JSON 檔案產生的 Base64 編碼值。