Google 認証システムの使用

このページは Apigee と Apigee ハイブリッドに適用されます。

Apigee Edge のドキュメントはこちら をご覧ください。

このトピックでは、Google 認証を使用するよう構成した API プロキシを設定してデプロイする方法について説明します。

はじめに

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 プロキシ構成オプション

このセクションでは、Google OAuth トークンや OpenID Connect 認証を有効にするために <Authentication> XML 要素を使用する場所について説明します。

構成オプション 説明
ServiceCallout ポリシー ServiceCallout ポリシーを使用して、API プロキシから他の内部サービスや外部サービスを呼び出すことができます。たとえば、ServiceCallout を使用して、外部の Google サービスやカスタム ホスト サービスを呼び出せます。使用の詳細と例については、ServiceCallout ポリシーをご覧ください。
ExternalCallout ポリシー ExternalCallout ポリシーを使用すると、gRPC サーバーに gRPC リクエストを送信し、Apigee ポリシーでサポートされていないカスタム動作を実装できます。使用法の詳細と例については、ExternalCallout ポリシーをご覧ください。
TargetEndpoint Google サービスまたはカスタム ホスト サービスを API プロキシ ターゲット エンドポイントとして指定します。使用方法の詳細と例については、API プロキシ構成リファレンスをご覧ください。

Google 認証トークンでサポートされているコンテキスト

<Authentication> 要素には、<GoogleAccessToken> または <GoogleIDToken> の 2 つのサブ要素構成があります。次の表に、これらの要素がサポートされているコンテキストを示します。

次の中で使用: GoogleAccessToken GoogleIDToken
ServiceCallout ポリシー サポート対象 サポート対象
ExternalCallout ポリシー 非対応 サポート対象
TargetEndpoint サポート対象 サポート対象

デプロイ手順

このセクションでは、Google 認証を使用して、対象の Google サービスやカスタム ホスト サービスを呼び出す API プロキシをデプロイする方法について説明します。Apigee と Apigee ハイブリッドのデプロイ手順を個別に説明します。

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:email または domain:domain にする必要があります。
  3. 対象の Google サービスとの通信に必要な権限をプロキシ サービス アカウントに付与します。たとえば、Google Logging サービスを呼び出したい場合、同サービスとの通信に必要な権限をプロキシ サービス アカウントが保有していなければなりません。ロールについてもご覧ください。
  4. Google 認証を使用するように構成された API プロキシをデプロイする前に、以下の準備が必要です。
    • 事前に作成したプロキシ サービス アカウントの名前。例: SA_NAME@PROJECT_ID.iam.gserviceaccount.com
    • デプロイを行うユーザー（デプロイ担当者）に、サービス アカウントに対する iam.serviceAccounts.actAs 権限がすでに付与されているか、付与する必要があります。リソースに対するアクセス権の付与、変更、取り消しをご覧ください。
  5. 実装した Google 認証構成を含む API プロキシをデプロイします。Apigee UI または API を使用してプロキシをデプロイできます。詳細については、API プロキシのデプロイをご覧ください。
    • UI を使用している場合は、サービス アカウント名を指定するように求められます。ステップ 1 で作成したプロキシ サービス アカウントの名前を使用します。例: SA_NAME@PROJECT_ID.iam.gserviceaccount.com。

    • Apigee Deployment 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 ハイブリッドにデプロイする

次の手順では、Google サービスに対して認証された呼び出しを行うように構成された API プロキシを Apigee ハイブリッドにデプロイする方法を説明します。この手順では、プロキシがすでに作成され、サポートされているコンテキストのリストのいずれかに <Authentication> 要素が含まれていることを前提としています。

  1. 次のいずれかの方法で Apigee ハイブリッド ランタイム コンポーネントのサービス アカウントとキーを作成します。
    • Apigee ハイブリッドに付属の create-service-account ツールを使用して、apigee-runtime サービス アカウントを作成します。このツールはサービス アカウントを作成し、サービス アカウント キーを返します。詳細については、create-service-account をご覧ください。
    • Google Cloud コンソールまたは gcloud コマンドを使用してサービス アカウントを作成します。サービス アカウントの作成と管理をご覧ください。サービス アカウント キーを取得する方法は、サービス アカウント キーの作成と管理をご覧ください。
  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. 2 つ目のサービス アカウントを作成します。これをプロキシ サービス アカウントと呼びます。このサービス アカウントは、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 にする必要があります。
  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 UI または API を使用してプロキシをデプロイできます。詳細については、API プロキシのデプロイをご覧ください。
    • UI を使用している場合は、サービス アカウント名を指定するように求められます。以前に作成したプロキシ サービス アカウントの名前を使用します。例: PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com。

    • Apigee Deployment 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 サービスによって返されることを確認します。

サービス アカウントの権限について

Google 認証を使用するように API プロキシを構成するには、次の表の説明に従ってサービス アカウントを作成する必要があります。サービス アカウントの作成と管理もご覧ください。

サービス アカウント 必須となる対象 説明
プロキシ Apigee と Apigee ハイブリッド

対象となる Google サービスに API プロキシが認証済み呼び出しを行うために必要な権限があります。

  • Apigee 組織と同じ Google Cloud プロジェクトに作成する必要があります。
  • デプロイを行うユーザー（デプロイ担当者）に、プロキシ サービス アカウントに対する iam.serviceAccounts.actAs 権限がすでに付与されているか、付与する必要があります。
  • 対象となる特定の Google サービスと通信するために必要な権限を保有している必要があります。たとえば、Google Logging サービスを呼び出したい場合、同サービスとの通信に必要な権限をプロキシ サービス アカウントが保有していなければなりません。ロールについてもご覧ください。
  • サービス アカウントの名前は、Google 認証を使用するプロキシをデプロイするときに指定する必要があります。
ランタイム Apigee ハイブリッドのみ

Apigee ランタイムで、API プロキシによってリクエストされた Google サービスで認証するトークンを生成できるようにします。このサービス アカウントは、プロキシ固有のサービス アカウントの「権限を借用し」、代理で認証済みの呼び出しを行います。

  • プロキシ サービス アカウントの権限を借用してトークンを作成できるようにするには、ランタイム サービス アカウントにプロキシ サービス アカウントのロール roles/iam.serviceAccountTokenCreator を付与する必要があります。サービス アカウントへのアクセス権を管理するをご覧ください。