ポリシー分析を BigQuery に書き込む

このページでは、Identity and Access Management(IAM)ポリシーを非同期で分析し、結果を BigQuery に書き込む方法について説明します。プロセスは、分析結果が BigQuery テーブルに書き込まれる点以外は、IAM ポリシーの分析と似ています。

始める前に

Cloud Asset API を有効にします。

API を有効にする

クエリの送信に使用するプロジェクトまたは組織で API を有効にする必要があります。クエリのスコープと同じリソースにする必要はありません。

必要なロールと権限

ポリシー分析を実行して結果を BigQuery にエクスポートするには、次のロールと権限が必要です。

必要な IAM のロール

ポリシーを分析して結果を BigQuery にエクスポートするために必要な権限を取得するには、クエリのスコープであるプロジェクト、フォルダ、または組織に対する次の IAM ロールの付与を管理者に依頼してください。

  • BigQuery データ編集者(roles/bigquery.dataEditor
  • Cloud Asset 閲覧者(roles/cloudasset.viewer
  • カスタム IAM ロールでポリシーを分析するには: ロール閲覧者(roles/iam.roleViewer
  • Google Cloud CLI を使用してポリシーを分析するには: Service Usage ユーザー(roles/serviceusage.serviceUsageConsumer

ロールの付与の詳細については、アクセスの管理をご覧ください。

これらの事前定義ロールには、ポリシーを分析して結果を BigQuery にエクスポートするために必要な権限が含まれています。必要な権限を正確に確認するには、[必要な権限] セクションを開いてください。

必要な権限

  • bigquery.datasets.create
  • bigquery.jobs.create
  • bigquery.tables.create
  • bigquery.tables.get
  • bigquery.tables.updateData
  • bigquery.tables.update
  • cloudasset.assets.analyzeIamPolicy
  • cloudasset.assets.searchAllResources
  • cloudasset.assets.searchAllIamPolicies
  • IAM のカスタムロールでポリシーを分析するには: iam.roles.get
  • Google Cloud CLI を使用してポリシーを分析するには: serviceusage.services.use

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

必要な Google Workspace 権限

Google Workspace グループのメンバーシップの結果としてプリンシパルが特定のロールまたは権限を持つかどうかを確認するには、groups.read Google Workspace 権限が必要です。この権限は、グループ読み取り管理者のロールと、グループ管理者や特権管理者のロールなどのより強力なロールに含まれています。詳細については、特定の管理者ロールを割り当てるをご覧ください。

AnalyzeIamPolicyLongrunning を呼び出しています

AnalyzeIamPolicyLongrunning メソッドを使用すると、分析リクエストを発行して、指定された BigQuery の宛先で結果を取得できます。

gcloud

後述のコマンドデータを使用する前に、次のように置き換えます。

  • RESOURCE_TYPE: 検索の対象範囲のリソースのタイプ。このリソースとその子孫に添付された IAM 許可ポリシーのみが分析されます。値 projectfolder、または organization を使用します。
  • RESOURCE_ID: 検索の対象範囲の Google Cloud プロジェクト、フォルダ、または組織の ID。このリソースとその子孫に添付された IAM 許可ポリシーのみが分析されます。プロジェクト ID は英数字からなる文字列です(例: my-project)。フォルダ ID と組織 ID は数値です(例: 123456789012)。
  • PRINCIPAL: アクセスを分析するプリンシパル。PRINCIPAL_TYPE:ID の形式(例: user:my-user@example.com )。プリンシパル タイプの完全なリストについては、プリンシパル識別子をご覧ください。
  • PERMISSIONS: 確認する権限のカンマ区切りのリスト(compute.instances.get,compute.instances.start など)。複数の権限を一覧表示すると、Policy Analyzer はリストされた権限を確認します。
  • DATASET: BigQuery データセット。形式は projects/PROJECT_ID/datasets/DATASET_ID です。PROJECT_ID は Google Cloud プロジェクトの英数字 ID で、DATASET_ID はデータセットの ID です。 。
  • TABLE_PREFIX: 分析結果を書き込む BigQuery テーブルの接頭辞。指定した接頭辞を持つテーブルが存在しない場合、BigQuery は新しいテーブルを作成します。
  • PARTITION_KEY: 省略可。BigQuery パーティション分割テーブルのパーティション キー。Policy Analyzer では、REQUEST_TIME パーティション キーのみがサポートされています。
  • WRITE_DISPOSITION: 省略可。宛先テーブルまたはパーティションがすでに存在する場合に実施するアクションを指定します。有効な値については、writeDisposition をご覧ください。デフォルトでは、テーブルまたはパーティションがすでに存在する場合、BigQuery はテーブルまたは最新のパーティションにデータを追加します。

gcloud asset analyze-iam-policy-longrunningコマンドを実行します。

Linux、macOS、Cloud Shell

gcloud asset analyze-iam-policy-longrunning --RESOURCE_TYPE=RESOURCE_ID \
    --full-resource-name=FULL_RESOURCE_NAME \
    --identity=PRINCIPAL \
    --permissions='PERMISSIONS' \
    --bigquery-dataset=DATASET \
    --bigquery-table-prefix=TABLE_PREFIX \
    --bigquery-partition-key=PARTITION_KEY \
    --bigquery-write-disposition=WRITE_DISPOSITION

Windows(PowerShell)

gcloud asset analyze-iam-policy-longrunning --RESOURCE_TYPE=RESOURCE_ID `
    --full-resource-name=FULL_RESOURCE_NAME `
    --identity=PRINCIPAL `
    --permissions='PERMISSIONS' `
    --bigquery-dataset=DATASET `
    --bigquery-table-prefix=TABLE_PREFIX `
    --bigquery-partition-key=PARTITION_KEY `
    --bigquery-write-disposition=WRITE_DISPOSITION

Windows(cmd.exe)

gcloud asset analyze-iam-policy-longrunning --RESOURCE_TYPE=RESOURCE_ID ^
    --full-resource-name=FULL_RESOURCE_NAME ^
    --identity=PRINCIPAL ^
    --permissions='PERMISSIONS' ^
    --bigquery-dataset=DATASET ^
    --bigquery-table-prefix=TABLE_PREFIX ^
    --bigquery-partition-key=PARTITION_KEY ^
    --bigquery-write-disposition=WRITE_DISPOSITION

次のようなレスポンスが返されます。

Analyze IAM Policy in progress.
Use [gcloud asset operations describe projects/my-project/operations/AnalyzeIamPolicyLongrunning/1195028485971902504711950280359719028666] to check the status of the operation.

REST

IAM 許可ポリシーを分析し、結果を BigQuery にエクスポートするには、Cloud Asset Inventory API の analyzeIamPolicyLongrunning メソッドを使用します。

リクエストのデータを使用する前に、次のように置き換えます。

  • RESOURCE_TYPE: 検索の対象範囲のリソースのタイプ。このリソースとその子孫に添付された IAM 許可ポリシーのみが分析されます。値 projectsfolders、または organizations を使用します。
  • RESOURCE_ID: 検索の対象範囲の Google Cloud プロジェクト、フォルダ、または組織の ID。このリソースとその子孫に添付された IAM 許可ポリシーのみが分析されます。プロジェクト ID は英数字からなる文字列です(例: my-project)。フォルダ ID と組織 ID は数値です(例: 123456789012)。
  • FULL_RESOURCE_NAME: 省略可。アクセスを分析するリソースの完全なリソース名。完全なリソース名の形式の一覧については、リソース名の形式をご覧ください。
  • PRINCIPAL: 省略可。アクセスを分析するプリンシパル。PRINCIPAL_TYPE:ID の形式。(例: user:my-user@example.com)プリンシパル タイプの完全なリストについては、プリンシパル識別子をご覧ください。
  • PERMISSION_1PERMISSION_2、...PERMISSION_N:省略可。確認する権限(compute.instances.get など)。複数の権限を一覧表示すると、Policy Analyzer はリストされた権限を確認します。
  • DATASET: BigQuery データセット。形式は projects/PROJECT_ID/datasets/DATASET_ID です。PROJECT_ID は Google Cloud プロジェクトの英数字 ID で、DATASET_ID はデータセットの ID です。 。
  • TABLE_PREFIX: 分析結果を書き込む BigQuery テーブルの接頭辞。指定した接頭辞を持つテーブルが存在しない場合、BigQuery は新しいテーブルを作成します。
  • PARTITION_KEY: 省略可。BigQuery パーティション分割テーブルのパーティション キー。Policy Analyzer では、REQUEST_TIME パーティション キーのみがサポートされています。
  • WRITE_DISPOSITION: 省略可。宛先テーブルまたはパーティションがすでに存在する場合に実施するアクションを指定します。有効な値については、writeDisposition をご覧ください。デフォルトでは、テーブルまたはパーティションがすでに存在する場合、BigQuery はテーブルまたは最新のパーティションにデータを追加します。

HTTP メソッドと URL:

POST https://cloudasset.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID:analyzeIamPolicyLongrunning

JSON 本文のリクエスト:

{
  "analysisQuery": {
    "resourceSelector": {
      "fullResourceName": "FULL_RESOURCE_NAME"
    },
    "identitySelector": {
      "identity": "PRINCIPAL"
    },
    "accessSelector": {
      "permissions": [
        "PERMISSION_1",
        "PERMISSION_2",
        "PERMISSION_N"
      ]
    }
  },
  "outputConfig": {
    "bigqueryDestination": {
      "dataset": "DATASET",
      "tablePrefix": "TABLE_PREFIX",
      "partitionKey": "PARTITION_KEY",
      "writeDisposition": "WRITE_DISPOSITION"
    }
  }
}

リクエストを送信するには、次のいずれかのオプションを展開します。

次のような JSON レスポンスが返されます。

{
  "name": "projects/my-project/operations/AnalyzeIamPolicyLongrunning/1206385342502762515812063858425027606003",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.asset.v1.AnalyzeIamPolicyLongrunningMetadata",
    "createTime": "2022-04-12T21:31:10.753173929Z"
  }
}

IAM ポリシー分析結果の表示

IAM ポリシー分析を表示するには:

コンソール

  1. コンソールの [BigQuery] ページに移動します。
    BigQuery ページに移動

  2. データセット内のテーブルとビューを表示するには、ナビゲーション パネルを開きます。[リソース] セクションでプロジェクトを展開し、データセットを選択します。

  3. リストから、接頭辞付きのテーブルを選択します。analysis 接頭辞付きのテーブルには、クエリとメタデータ(オペレーション名、リクエスト時刻、重大でないエラーなど)が含まれます。analysis_result 接頭辞付きのテーブルは、{identity, role(s)/permission(s), resource} のタプルを、それらのタプルを生成する IAM ポリシーとともに一覧表示した結果です。

  4. データのサンプルセットを表示するには、[プレビュー] を選択します。

API

テーブルのデータを閲覧するには、tabledata.list を呼び出します。tableId パラメータで、テーブルの名前を指定します。

次の省略可能パラメータを構成すると、出力を制御できます。

  • maxResults は返される結果の最大数です。
  • selectedFields は返される列のカンマ区切りのリストです。指定しなければ、すべての列が返されます。
  • startIndex は、読み取りを開始する行を指し示す、ゼロから始まるインデックスです。

値は 1 つの JSON オブジェクトにラップされて返されます。このオブジェクトは、tabledata.list リファレンス ドキュメントに記載されている手順に沿って解析する必要があります。

BigQuery のクエリ

このセクションでは、AnalyzeIamPolicyLongrunning によって書き込まれた BigQuery テーブルの使用法を示す SQL クエリの例を示します。BigQuery の構文の詳細については、標準 SQL クエリ構文をご覧ください。

ほとんどのクエリには OP_ID が必要であり、AnalyzeIamPolicyLongrunning レスポンスから取得できます。たとえば gcloud では、「[gcloud asset operations describe organizations/123456789/operations/AnalyzeIamPolicyLongrunning/123456] を使用してオペレーションのステータスを確認します」の OP_ID123456 になります。

オペレーションの一覧表示

テーブルには、複数の AnalyzeIamPolicyLongrunning オペレーションの結果を格納できます。次のクエリを使用して、それらすべてを一覧表示できます。

SELECT DISTINCT
  requestTime,
  opName
FROM `BQ_PROJECT_ID.BQ_DATASET_NAME.BQ_TABLE_PREFIX_analysis`
ORDER BY 1 DESC
;

1 つのオペレーションにおける分析の一覧表示

1 つの AnalyzeIamPolicyLongrunning オペレーションで、複数の分析レコードが生成される可能性があります。たとえば、リクエストで analyze_service_account_impersonation オプションを有効にすると、結果には 1 つのメイン分析(analysisId 0)と複数のサービス アカウントなりすまし分析が含まれる可能性があります。

次のクエリを使用して、オペレーション名を指定すると、すべての分析を確認できます。

DECLARE _opName STRING DEFAULT "organizations/ORG_ID/operations/AnalyzeIamPolicyLongrunning/OP_ID";

SELECT
  analysisId,
  requestTime,
  TO_JSON_STRING(analysis.analysisQuery, true) as analysisQuery,
  analysis.fullyExplored,
  TO_JSON_STRING(analysis.nonCriticalErrors, true) as nonCriticalErrors
FROM `BQ_PROJECT_ID.BQ_DATASET_NAME.BQ_TABLE_PREFIX_analysis`
WHERE opName=_opName
ORDER BY 1
;

1 つの分析における ACE(アクセス制御エントリ)の一覧表示

ACE はアクセス制御エントリ {identity, role(s)/permission(s), resource} です。次のクエリを使用して、1 つの分析で ACE を一覧表示できます。

DECLARE _opName STRING DEFAULT "organizations/ORG_ID/operations/AnalyzeIamPolicyLongrunning/OP_ID";

SELECT DISTINCT
  ids.name AS identity,
  resources.fullResourceName AS resource,
  accesses.role AS role,
  accesses.permission AS permission
FROM `BQ_PROJECT_ID.BQ_DATASET_NAME.BQ_TABLE_PREFIX_analysis_result`,
  UNNEST(analysisResult.identityList.identities) AS ids,
  UNNEST(analysisResult.accessControlLists) AS acls,
  UNNEST(acls.accesses) AS accesses,
  UNNEST(acls.resources) AS resources
WHERE opName=_opName
AND analysisId = 0
ORDER BY 1,2,3,4
;

1 つの分析における IAM ポリシー バインディングを使用した ACE(アクセス制御エントリ)の一覧表示

このクエリでは、ACE および 1 つの分析用にこの ACE を生成する IAM ポリシー バインディングの両方を一覧表示しています。

DECLARE _opName STRING DEFAULT "organizations/ORG_ID/operations/AnalyzeIamPolicyLongrunning/OP_ID";

SELECT
  ids.name AS identity,
  resources.fullResourceName AS resource,
  accesses.role AS role,
  accesses.permission AS permission,
  analysisResult.attachedResourceFullName as iam_policy_attached_resource,
  TO_JSON_STRING(analysisResult.iamBinding, true) as iam_policy_binding
FROM `BQ_PROJECT_ID.BQ_DATASET_NAME.BQ_TABLE_PREFIX_analysis_result`,
  UNNEST(analysisResult.identityList.identities) AS ids,
  UNNEST(analysisResult.accessControlLists) AS acls,
  UNNEST(acls.accesses) AS accesses,
  UNNEST(acls.resources) AS resources
WHERE opName=_opName AND analysisId = 0
ORDER BY 1,2,3,4
;

1 つの分析における IAM ポリシー バインディングの一覧表示

このクエリでは、1 つの分析に表示された IAM ポリシー バインディングを一覧表示します。

DECLARE _opName STRING DEFAULT "organizations/ORG_ID/operations/AnalyzeIamPolicyLongrunning/OP_ID";

SELECT DISTINCT
  analysisResult.attachedResourceFullName as iam_policy_attached_resource,
  TO_JSON_STRING(analysisResult.iamBinding, true) as iam_policy_binding
FROM `BQ_PROJECT_ID.BQ_DATASET_NAME.BQ_TABLE_PREFIX_analysis_result`
WHERE opName=_opName AND analysisId = 0
ORDER BY 1, 2
;

1 つの分析における ACE(アクセス制御エントリ)の IAM ポリシー バインディングの一覧表示

このクエリでは、1 つの分析における IAM ポリシー バインディングとその派生した ACE を一覧表示します。

DECLARE _opName STRING DEFAULT "organizations/ORG_ID/operations/AnalyzeIamPolicyLongrunning/OP_ID";

SELECT
  analysisResult.attachedResourceFullName as iam_policy_attached_resource,
  TO_JSON_STRING(analysisResult.iamBinding, true) as iam_policy_binding,
  TO_JSON_STRING(analysisResult.identityList.identities, true) as identities,
  TO_JSON_STRING(acls.accesses, true) as accesses,
  TO_JSON_STRING(acls.resources, true) as resources
FROM `BQ_PROJECT_ID.BQ_DATASET_NAME.BQ_TABLE_PREFIX_analysis_result`,
  UNNEST(analysisResult.accessControlLists) AS acls
WHERE opName=_opName AND analysisId = 0
ORDER BY 1,2
;