IAM ベースの API 認証の概要

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

Apigee は、API プロキシの IAM ベースの認証と認可をサポートしています。このソリューションでは、API を呼び出すためのアクセス権は複数の要素に基づいています。たとえば、リクエストフローに VerifyIAM ポリシーが含まれているかどうか、API コンシューマーに Apigee API を呼び出すために必要な Google Cloud IAM ロールまたは権限があるかどうかなどです。認可は任意の Google Cloud プリンシパルに付与することが可能で、個々のユーザーに限定されません。

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

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

アクセス管理を追加する

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

リクエストフローの一環として、Apigee API プロキシに VerifyIAM ポリシーを追加します。
Apigee プロジェクトのクラウド管理者が、次の手順を実施します。
1. プロジェクトレベルで API コンシューマーの Google Cloud プリンシパルに deploymentInvoker IAM ロール（または apigee.deployments.invoke IAM 権限を持つカスタムロール）を付与します。これにより、API コンシューマーは、関連付けられた Apigee 組織内のホストされているすべての API を呼び出すことができるようになります。
  
  または
2. SetIamPolicy アクションを使用して、特定のデプロイで、または複数のデプロイで反復して、API コンシューマーの Google Cloud プリンシパルにロールまたは権限を付与します。デプロイリソースでリストオペレーションを使用すると、API プロキシや共有フローなど環境内のすべてのデプロイを確認できます。デプロイ名は、API プロキシまたは共有フローの名前です。
  注: 共有フローのデプロイにロールまたは権限を追加しても、共有フローに対する VerifyIAM ポリシーチェックは作成されません。権限はプロキシにのみ適用されます。共有フローを呼び出すプロキシでは、プロキシに権限を適用する必要があります。プロキシチェーンでは、ポリシーが適用されたプロキシに権限が付与されます。チェーン内の他のプロキシに権限は必要ありません。
アクセストークンを生成するよう 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 プリンシパルのロールまたは権限を管理します。例の $Project は Google Cloud プロジェクトです。

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

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

gcloud projects add-iam-policy-binding {$Project} --member={$user} --role='roles/apigee.deploymentInvoker'

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

gcloud projects remove-iam-policy-binding {$Project} --member={$user} --role='roles/apigee.deploymentInvoker'

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

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

curl 'https://apigee.googleapis.com/v1/organizations/{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"
        ]
      }
    ]
  }

追加したポリシーオブジェクトが正しく保持されていることを確認します（省略可）。

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:getIamPolicy' \
  --header 'Authorization: Bearer $TOKEN'

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

ユーザーが指定されたデプロイにアクセスできるかどうか（指定されたデプロイの指定されたユーザーに apigee.deployments.invoke 権限が設定されているかどうか）を確認するには、以前に生成したアクセストークンを使用してこのリクエストを送信するようユーザーに指示します。

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

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

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

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:getIamPolicy' \
  --header 'Authorization: Bearer $TOKEN'

次のような成功のレスポンスが表示されます。他のバインディングが表示される場合もあります。

{
  "version": 1,
  "etag": "BwYT8i40Vwo=",
  "bindings": [
      {
        "role": "roles/apigee.deploymentInvoker",
        "members": [
          "user:$user"
        ]
      }
    ]
  }

バインディングを削除するには:

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

空のペイロードを指定すると、すべてのユーザーのアクセス権が削除されますが、この例ではアクセス権を持つユーザーが 1 人だけであるため適切です。他のユーザーのアクセス権を継続した状態でユーザーのアクセス権を削除する場合は、他のユーザーの初期アクセス権を設定したときと同様にペイロードでアクセス権を継続するユーザーを指定します。

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

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:testIamPermissions' \
  --header 'Authorization: Bearer $USER_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"permissions":["apigee.deployments.invoke"]}'

権限を持つユーザーがいない場合は、空の出力が返されます。