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

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

始める前に

Enable the Cloud Asset API.

Enable the 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 にエクスポートするには、次の権限が必要です。

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 の権限が必要です。この権限は、グループ読み取り管理者のロールだけでなく、グループ管理者や特権管理者のロールなどのより強力なロールに含まれています。詳しくは、特定の管理者ロールを割り当てるをご覧ください。

ポリシーを分析して結果をエクスポートする

Console

Google Cloud コンソールで、[Policy Analyzer] ページに移動します。

Policy Analyzer に移動
[ポリシーの分析] セクションで、使用するクエリテンプレートを見つけて、[クエリを作成] をクリックします。カスタムクエリを作成する場合は、[カスタムクエリを作成] をクリックします。
[クエリスコープを選択] フィールドで、クエリを調査するプロジェクト、フォルダ、組織を選択します。ポリシーアナライザは、プロジェクト、フォルダ、組織へのアクセスと、そのプロジェクト、フォルダ、組織内のリソースを分析します。
クエリパラメータが設定されていることを確認します。
- クエリテンプレートを使用している場合は、事前入力されたクエリパラメータを確認します。
- カスタムクエリを作成する場合は、クエリを実行するリソース、プリンシパル、ロール、権限を設定します。
作成できるクエリの種類の詳細については、IAM ポリシーを分析するをご覧ください。
クエリの名前が表示されているペインで、[Analyze] > [Export full result only] をクリックします。[結果のエクスポート] ペインが開きます。
[エクスポート先の設定] セクションに、次の情報を入力します。
- プロジェクト: BigQuery データセットが配置されているプロジェクト。
- データセット: 結果のエクスポート先の BigQuery データセット。
- テーブル: 分析結果を書き込む BigQuery テーブルの接頭辞。指定した接頭辞を持つテーブルが存在しない場合は、BigQuery によって新しいテーブルが作成されます。
[続行] をクリックします。
省略可: [追加設定の構成] セクションで、必要なオプションを選択します。
- パーティショニング: テーブルをパーティショニングするかどうか。パーティション分割テーブルの詳細については、パーティション分割テーブルの概要をご覧ください。
- 書き込み設定: 宛先テーブルまたはパーティションがすでに存在する場合に実施するアクションを指定します。デフォルトでは、テーブルまたはパーティションがすでに存在する場合、BigQuery はデータをテーブルまたは最新のパーティションに追加します。
[エクスポート] をクリックします。

Policy Analyzer はクエリを実行し、その結果を指定されたテーブルにエクスポートします。

gcloud

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

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

RESOURCE_TYPE: 検索の対象範囲に設定するリソースのタイプ。このリソースとその子孫に添付された IAM 許可ポリシーのみが分析されます。値 project、folder、または 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: projects/PROJECT_ID/datasets/DATASET_ID 形式の BigQuery データセット。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

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

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

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

RESOURCE_TYPE: 検索の対象範囲に設定するリソースのタイプ。このリソースとその子孫に添付された IAM 許可ポリシーのみが分析されます。値 projects、folders、または 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_1、PERMISSION_2、PERMISSION_N: 省略可。確認する権限（例: compute.instances.get）。複数の権限を一覧表示すると、Policy Analyzer は一覧表示された中から任意の権限を確認します。
DATASET: projects/PROJECT_ID/datasets/DATASET_ID 形式の BigQuery データセット。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"
    }
  }
}

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

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://cloudasset.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID:analyzeIamPolicyLongrunning"

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザーアカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://cloudasset.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID:analyzeIamPolicyLongrunning" | Select-Object -Expand Content

API Explorer（ブラウザ）

リクエスト本文をコピーして、メソッドのリファレンスページを開きます。ページの右側に [API Explorer] パネルが開きます。このツールを操作してリクエストを送信できます。このツールにリクエスト本文を貼り付け、その他の必須フィールドに入力して、[Execute] をクリックします。

次のような 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 ポリシー分析を表示するには:

コンソール

Google Cloud コンソールで [BigQuery] ページに移動します。

BigQuery に移動
データセット内のテーブルとビューを表示するには、ナビゲーションパネルを開きます。[エクスプローラ] セクションでプロジェクトを展開し、データセットを選択します。
リストから、接頭辞付きのテーブルを選択します。analysis 接頭辞付きのテーブルには、クエリとメタデータ（オペレーション名、リクエスト時刻、重大でないエラーなど）が含まれます。analysis_result 接頭辞付きのテーブルは、{identity, role(s)/permission(s), resource} のタプルを、それらのタプルを生成する IAM ポリシーとともに一覧表示した結果です。
データのサンプルセットを表示するには、[プレビュー] タブを選択します。

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_ID は 123456 になります。

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

テーブルには、複数の 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
;