Google Authentication 拡張機能

バージョン: 1.0.2

指定した Google API へのアクセスを Google を使用して認証します。

この拡張機能を使用すると、Google Cloud サービス用のトークン(OAuth または JWT)を取得し、次にこのトークンで ServiceCallout ポリシーの使用などで後続の Google API を呼び出します。

たとえば、API プロキシでこの拡張機能を使用してトークンを取得し、PopulateCache ポリシーでこのトークンをキャッシュに保存したら、API プロキシフロー内から Google Cloud サービスにアクセスできるように ServiceCallout ポリシーを経由してトークンを渡します。

前提条件

ここでは、この拡張機能を構成して使用する方法についてのリファレンスを提供します。ExtensionCallout ポリシーで API プロキシ経由で拡張機能を使用する前に、次のことを行う必要があります。

  1. 拡張機能が使用するアカウント(認証情報に使用するサービス アカウント)に、拡張機能が認証に使用する Google Cloud サービスへのアクセス権があることを確認します。

  2. GCP Console でサービス アカウントキーを作成します

  3. 拡張機能の追加と構成を行うときに構成リファレンスを使用して、生成されたサービス アカウント キーの JSON ファイルのコンテンツを使用します。

Google Cloud による認証について

この拡張機能は、特定のメンバー(Google Cloud プロジェクトで定義)を表すことで、Google Cloud からの認証をリクエストします。拡張機能の構成の際に、プロジェクト メンバーが所有するサービス アカウントの JSON ファイルを使用します。

この拡張機能からアクセスできるのは、メンバーがアクセスできるリソースに限定されます。つまり認証が成功するのは、Google Cloud コンソールで収集された権限と、拡張機能が実行時に(scope または audience 経由で)リクエストしたアクセス権が一致するかどうかによります。

通常、次の手順でこの拡張機能から 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 をトークンの scope に指定します。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 ポリシーで新たなトークンが得られたら、この後 API プロキシのポリシーで使用できるように、PopulateCache ポリシーでキャッシュに保存されます。

      <?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 プロキシと Google API の間で two-legged OAuth をサポートできます。

two-legged OAuth では、この拡張機能のアクションで OAuth トークンが得られます。トークンの取得には、サービス アカウントの JSON(この拡張機能を構成する際に追加)を使用した Google による認証が必要です。このアクションで 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>
    

リクエスト パラメータ

パラメータ 説明 デフォルト 必須
scope 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 トークンタイプ。 Bearer
expiresInSec トークンの期限が切れるまでの秒数。 3600

getJWTAccessToken

JSON ウェブトークン(JWT)のアクセス トークンを取得します。呼び出す API に Google API GitHub リポジトリで公開されているサービス定義がある場合、このトークンを Google API による認証に使用できます。

一部の Google API では、OAuth 2.0 アクセス トークンではなく署名付き JWT を署名なしトークンとして直接使用する認証済み API を呼び出すことができます。こちらが使用できる場合、API を呼び出す前に Google の認証サーバーへのネットワーク リクエストを作成する必要がなくなります。

JWT アクセス トークンによる認証の詳細については、サーバー間アプリケーションに OAuth 2.0 を使用するをご覧ください。

構文

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

例: Cloud Function URL

次の例では、拡張機能の 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 URL などが使用されます。 なし

レスポンス

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

レスポンス プロパティ

パラメータ 説明 デフォルト 必須
accessToken アクセス トークン。 なし
tokenType トークンタイプ。 Bearer
expiresInSec 有効期限を秒数で示します。 3600

構成リファレンス

API プロキシで使用するためにこの拡張機能を構成およびデプロイする場合は、次の項目を参照してください。Apigee Console で拡張機能を構成する手順については、拡張機能の追加と構成をご覧ください。

拡張機能の共通プロパティ

以下のプロパティはすべての拡張機能に存在します。

プロパティ 説明 デフォルト 必須
name この拡張機能の構成に指定する名前。 なし
packageName Apigee Edge によって指定された、拡張機能パッケージの名前。 なし
version 構成する拡張機能が含まれる拡張機能パッケージのバージョン番号。 なし
configuration 追加する拡張機能に固有の構成値。こちらの拡張機能パッケージのプロパティをご覧ください。 なし

この拡張機能パッケージのプロパティ

この拡張機能に固有の以下の構成プロパティに値を指定します。

プロパティ 説明 デフォルト 必須
credentials Apigee Edge コンソールで入力する場合は、サービス アカウント キーの JSON ファイルのコンテンツ全体となります。Management API を使用して設定する場合は、サービス アカウント キーの JSON ファイル全体から生成された、base64 でエンコード済みの値です。 なし