IAM ベースの API 認証の概要

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

Apigee は、API プロキシの IAM ベースの認証と認可をサポートしています。この機能を使用するには、プロキシのリクエスト フローに VerifyIAM ポリシーを含め、Apigee API を呼び出すために必要な Google Cloud IAM ロールまたは権限を持つように API コンシューマのユーザー ID（通常はメールアドレス）を構成します。API リクエストは、そのユーザーの有効な Google Cloud アクセス トークンを渡します。

管理者は、個々のユーザーだけでなく、任意の Google Cloud プリンシパルに認可を付与できます。

IAM ベースのアクセス制御を使用する

このセクションでは、IAM ベースの認証と認可を設定するエンドツーエンドのプロセス、アクセス権を設定した後にリクエストを評価する方法、以前にアクセス権を持っていた API コンシューマーのアクセス権を取り消す方法について説明します。

アクセス管理を追加する

API プロキシのアクセス管理を設定するには:

  1. リクエスト フローの一環として、Apigee API プロキシに VerifyIAM ポリシーを追加します。
  2. Apigee プロジェクトのクラウド管理者が、次の手順を実施します。
    1. プロジェクト レベルで API コンシューマーの Google Cloud プリンシパルに deploymentInvoker IAM ロール（または apigee.deployments.invoke IAM 権限を持つカスタムロール）を付与します。これにより、API コンシューマーは、関連付けられた Apigee 組織内のホストされているすべての API を呼び出すことができるようになります。

      または

    2. SetIamPolicy アクションを使用して、特定のデプロイで、または複数のデプロイで反復して、API コンシューマーの Google Cloud プリンシパルにロールまたは権限を付与します。デプロイ リソースでリスト オペレーションを使用すると、API プロキシや共有フローなど環境内のすべてのデプロイを確認できます。デプロイ名は、API プロキシまたは共有フローの名前です。
  3. アクセス トークンを生成するよう API コンシューマーに指示します。このトークンは、権限チェックのために Apigee API リクエスト内に渡されます。生成されたトークンには、https://www.googleapis.com/auth/cloud-platform 認証スコープが必要です。

管理オペレーション

このセクションでは、IAM ベースの権限を管理する際に API 管理者（API プロデューサー）が実行するアクションについて説明します。

IAM ベースのアクセス権を管理する際に使用される API ベースのオペレーションに関するドキュメントは、organizations.environments および organizations.environments.deployments API リファレンス ドキュメントにあります。これには、SetIamPolicy、GetIamPolicy、TestIamPermissions、GetDeployment のオペレーションの説明が記載されています。

次の表に、オペレーションと必要な権限の対応関係を示します。

管理操作 アクション 必要な IAM 権限 権限に必要な IAM リソース*
GetDeployment Apigee 環境のデプロイに関する情報を取得する apigee.deployments.get Google Cloud プロジェクトまたは Apigee 環境
ListDeployments Apigee 環境のデプロイを一覧表示する apigee.deployments.list プロジェクトまたは Apigee 環境
SetIamPolicy 特定の API デプロイにおける API コンシューマーの呼び出しアクセス権を設定する apigee.deployments.setIamPolicy Google Cloud プロジェクトまたは Apigee 環境
GetIamPolicy API デプロイの一連の呼び出しアクセス権設定を取得する apigee.deployments.getIamPolicy Google Cloud プロジェクトまたは Apigee 環境
TestIamPermissions この API を呼び出すユーザーに、ペイロードに記載されている権限があるかどうかを確認する IAM 権限は不要 なし
* Google Cloud プロジェクトは、Apigee のプロビジョニングに使用されるプロジェクトです。Apigee 環境レベルの権限は、setIAMPolicy を使用して環境に設定されます。

ランタイム アクセス チェック

API コンシューマーが IAM ベースのアクセス制御を使用して API にアクセスしようとすると、プロジェクト レベルまたはデプロイレベルで必要なアクセス トークンと適切なロールまたは権限があるかどうかがチェックされます。ある場合は、引き続きプロキシにアクセスできます。ない場合はブロックされます。

アクセス権を削除する

プロジェクト レベルでアクセス権を削除するには: プロジェクト レベルで管理されている API コンシューマーのアクセス権を削除するには、Apigee プロジェクトのクラウド管理者が、API コンシューマーの Google Cloud プロジェクトの Google Cloud プリンシパルから deploymentInvoker IAM ロール（または apigee.deployments.invoke IAM 権限を持つカスタムロール）を取り消します。

setIamPolicy を使用して個々のデプロイにアクセス権が付与されている場合は、別の setIamPolicy オペレーションを使用してデプロイからロールまたは権限を削除します。

IAM ベースのアクセス制御の特性と制限事項

IAM ベースの認証と認可を使用する場合は、次の特性と制限事項に注意してください。

  • 通常、VerifyIAM によるポリシーの実行には 10～50 ミリ秒かかります。ただし、一部の呼び出しではレイテンシが増加することがあります。たとえば、asia-east2 リージョンでは平均レイテンシが 50 ミリ秒に増加し、一部の呼び出しでは完了までに 100 ミリ秒ほどかかることがあります。

    次のレイテンシの数値は保証されていないため、注意してください。

  • プロキシに VerifyIAM ポリシーを含めると、検証済み / 未検証のチェックのみが行われます。API コンシューマー固有のロールと権限は、リクエスト フローまたはレスポンス フローの後続のプロセスでは考慮されません。
  • 認可のチェックは VerifyIAM ポリシーの実行時にのみ行われるため、トラフィック管理ポリシーの後のリクエスト フローで VerifyIAM を最初のポリシーにする必要があります。
  • 権限の検証が成功した場合、または API プロデューサーがエラー発生時に処理を続行するよう VerifyIAM ポリシーにマークを付けている場合、リクエスト フローは他のポリシー（存在する場合）の実行を継続し、最終的にターゲット サーバーに到達します。権限チェックが失敗し、API プロデューサーがエラー発生時に処理を続行するようポリシーにマークを付けていない場合、ユーザーはエラーを受け取ります。
  • 環境レベルで呼び出しアクセス権（apigee.deployments.invoke）を追加しても、環境内のすべての API デプロイに呼び出しアクセス権が付与されるわけではありません。
  • IAM 条件はデプロイ リソースでサポートされていません。また、呼び出しアクセス権の制御には使用できません。詳細については、Apigee IAM 条件をポリシーに追加するをご覧ください。
  • IAM ベースのアクセス制御では、1 つのポリシー内で最大 1,500 個のロール バインディングをサポートし、その他にも制約事項があります。IAM の割り当てと上限をご覧ください。
  • IAM ベースのアクセス制御は、IAM の伝播遅延の影響を受けます。
  • デプロイレベルの setIAMPolicy を介して apigee.deployments.delete などその他の apigee.deployments オペレーションを管理しようとしても効果はありませんが、エラーも返されません。apigee.deployements.invoke のみ有効です。
  • デプロイに対するアクセス権は、対応するプロキシが環境からデプロイ解除されるか削除されると削除されます。再デプロイする場合は、アクセス権を再度追加する必要があります。
  • 現在、ハイブリッドでは IAM ベースの認証と認可を使用できません。

例

このセクションでは、API への IAM ベースのアクセス権の付与と取り消しの例を示します。これらの例はすべて、VerifyIAM が適切な API プロキシにすでに追加されていることを前提としています。

これらの例では、Cloud コンソールまたは gcloud（以下に示す）を使用して、API コンシューマーの Google Cloud プリンシパルのロールまたは権限を管理します。

Apigee 組織内のすべての API を呼び出すためのユーザー アクセス権の付与および取り消し

アクセス権を追加するには、deploymentInvoker ロールを追加します。

APIGEE_ORG=GCP_PROJECT
USER=USER_EMAIL_HERE
gcloud projects add-iam-policy-binding "${APIGEE_ORG}" --member="${USER}" \
    --role='roles/apigee.deploymentInvoker'

アクセス権を取り消すには、deploymentInvoker ロールを削除します。

APIGEE_ORG=GCP_PROJECT
USER=USER_EMAIL_HERE
gcloud projects remove-iam-policy-binding "${APIGEE_ORG}" --member="${USER}" \
    --role='roles/apigee.deploymentInvoker'

環境内の特定のデプロイに対するユーザー アクセス権の付与および取り消し

単一ユーザーの呼び出し元のロールを特定のデプロイに追加するには:

APIGEE_ORG=GCP_PROJECT
ENV=APIGEE_ENVIRONMENT
API=APIPROXY_NAME
USER=USER_EMAIL_HERE
TOKEN=$(gcloud auth print-access-token)
curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:setIamPolicy" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "policy": {
    "bindings": [
      {
        "members": [
          "user:'"$USER"'"
        ],
        "role": "roles/apigee.deploymentInvoker"
      }
    ]
  }
}'

次のような成功のレスポンスが表示されます。

{
    "version": 1,
    "etag": "BwYT8i40Vwo=",
    "bindings": [
      {
        "role": "roles/apigee.deploymentInvoker",
        "members": [
          "user:user-email@example.com"
        ]
      }
    ]
  }

複数のユーザーの呼び出し元のロールを特定のデプロイに追加するには:

APIGEE_ORG=GCP_PROJECT
ENV=APIGEE_ENVIRONMENT
API=APIPROXY_NAME
USER1=EMAIL_FOR_USER1
USER2=EMAIL_FOR_USER2
USER3=EMAIL_FOR_USER3
TOKEN=$(gcloud auth print-access-token)
curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:setIamPolicy" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "policy": {
    "bindings": [
      {
        "members": [
        "user:'"$USER1"'",
        "user:'"$USER2"'",
        "user:'"$USER3"'"
        ],
        "role": "roles/apigee.deploymentInvoker"
      }
    ]
  }
}'

以前に設定したポリシー オブジェクトをクエリするには:

curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:getIamPolicy" \
  --header "Authorization: Bearer $TOKEN"

上のような成功のレスポンスが表示されます。

ユーザーは、指定されたデプロイにアクセスできるかどうか（指定されたデプロイに対する apigee.deployments.invoke 権限が設定されているかどうか）を確認できます。デプロイされた API を直接呼び出す必要はありません。ユーザーは、生成したアクセス トークンを使用して、自身でこのリクエストを送信します。

APIGEE_ORG=GCP_PROJECT
ENV=APIGEE_ENVIRONMENT
API=APIPROXY_NAME
USER=USER_EMAIL_HERE
TOKEN=$(gcloud auth print-access-token)
curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:testIamPermissions" \
    --header "Authorization: Bearer $TOKEN" \
    --header 'Content-Type: application/json' \
    --data '{"permissions":["apigee.deployments.invoke"]}'

レスポンスには、ユーザーの apigee.deployments.invoke 権限が含まれている必要があります。

単一ユーザーに対する特定のデプロイへのアクセス権を取り消すには、そのユーザーの deploymentInvoker ロールを削除します。これを行うには、まず、現在デプロイに関連付けられているポリシー オブジェクトを取得します。

curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:getIamPolicy" \
  --header "Authorization: Bearer $TOKEN"

次のような成功のレスポンスが表示されます。

{
  "version": 1,
  "etag": "BwYT8i40Vwo=",
  "bindings": [
      {
        "role": "roles/apigee.deploymentInvoker",
        "members": [
          "user:user1-email@example.com",
          "user:user2-email@example.com",
          "user:user3-email@example.com"
        ]
      }
    ]
  }

単一ユーザーのバインディングを削除するには、ユーザーの初期アクセス権を設定するときと同様に、setIamPolicy を使用して引き続きアクセス権を持たせるユーザーをペイロードで指定します。上の例に沿って、USER1 のアクセス権を削除し、USER2 と USER3 のアクセス権を保持する場合は、次のコマンドを使用します。

curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:setIamPolicy" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "policy": {
    "bindings": [
      {
        "members": [
        "user:'"$USER2"'",
        "user:'"$USER3"'"
        ],
        "role": "roles/apigee.deploymentInvoker"
      }
    ]
  }
}'

特定のデプロイのすべてのユーザーのバインディングを削除するには、空のペイロードを指定します。

  curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:setIamPolicy" \
    --header "Authorization: Bearer $TOKEN" \
    --header 'Content-Type: application/json' \
    --data '{}'

バインディングが削除されたことを確認するには、ユーザーがデプロイに対する apigee.deployments.invoke 権限を持っていないことを確認します。

curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:testIamPermissions" \
    --header "Authorization: Bearer $TOKEN" \
    --header 'Content-Type: application/json' \
    --data '{"permissions":["apigee.deployments.invoke"]}'

これにより、適切なレスポンスが返されます。たとえば、API を呼び出す権限を持つユーザーがいない場合は、空の出力が返されます。