統合アクセス ポリシーを編集する

統合アクセス ポリシー(UAP)を使用すると、プリンシパルにGoogle Cloud リソースへのアクセス権を付与したり、アクセスを拒否したりできます。このドキュメントでは、既存の UAP を編集する方法と、UAP の適用対象となるリソースを変更する方法について説明します。

始める前に

  1. 認証を設定する。

    このページのサンプルをどのように使うかに応じて、タブを選択してください。

    コンソール

    Google Cloud コンソールを使用して Google Cloud サービスと API にアクセスする場合、認証を設定する必要はありません。

    gcloud

    Google Cloud コンソールで Cloud Shell をアクティブにします。

    Cloud Shell をアクティブにする

    Google Cloud コンソールの下部で Cloud Shell セッションが開始し、コマンドライン プロンプトが表示されます。Cloud Shell はシェル環境です。Google Cloud CLI がすでにインストールされており、現在のプロジェクトの値もすでに設定されています。セッションが初期化されるまで数秒かかることがあります。

    REST

    このページの REST API サンプルをローカル開発環境で使用するには、gcloud CLI に指定した認証情報を使用します。

      Google Cloud CLI をインストールします。

      外部 ID プロバイダ(IdP)を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

    詳細については、 Google Cloud 認証ドキュメントの REST を使用して認証するをご覧ください。

  2. Google Cloud プロジェクトで課金が有効になっていることを確認します。

  3. 省略可。UAP の概要を確認する。

必要なロール

UAP の編集に必要な権限を取得するには、編集する UAP を所有するプロジェクト、フォルダ、または組織に対するアクセス ポリシー管理者(roles/iam.accessPolicyAdmin)IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

この事前定義ロールには、UAP の編集に必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

UAP を編集するには、次の権限が必要です。

  • iam.accesspolicies.update
  • Google Cloud コンソールで UAP を編集します。
    • iam.accesspolicies.get
    • iam.accessPolicies.list

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

既存の統合アクセス ポリシーを編集する

UAP を編集して、表示名またはルールを更新できます。

UAP は、 Google Cloud コンソール、gcloud CLI、または IAM REST API を使用して編集できます。

コンソール

  1. Google Cloud コンソールで、[統合アクセス ポリシー] ページに移動します。

    [統合アクセス ポリシー] に移動
  2. 編集する UAP を所有するプロジェクト、フォルダ、または組織を選択します。
  3. 編集する UAP のポリシー ID をクリックします。
  4. ルールを追加するには、[ 広告ルールを追加] をクリックして、ルールの詳細を追加します。ルールを保存するには、[ルールを追加] をクリックします。

    ルールのフィールドの詳細については、UAP を作成するをご覧ください。

  5. UAP の他のフィールドを編集するには、[ ポリシーを編集] をクリックします。
  6. 次のいずれかのフィールドを編集します。

    • ポリシー名: UAP の新しい表示名を入力します。
    • ルール: UAP のルールを更新、追加、削除します。
  7. UAP の編集が完了したら、[ポリシーを更新] をクリックします。

gcloud

gcloud iam access-policies update コマンドは、既存の UAP を更新します。

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

  • UAP_ID: 更新する UAP の ID(例: example-policy)。
  • UAP_PARENT_RESOURCE_TYPE: 更新する UAP を所有する Resource Manager リソース(プロジェクト、フォルダ、組織)のタイプ。値 project、folder、または organization を使用します。
  • UAP_PARENT_RESOURCE_ID: 更新する UAP を所有するプロジェクト、フォルダ、または組織の ID。プロジェクト ID は英数字からなる文字列です(例: my-project)。フォルダ ID と組織 ID は数値です(例: 123456789012)。
  • FIELD_TO_UPDATE=UPDATED_VALUE: 更新するフィールドと、それに対応する更新後の値。

    ポリシーのフィールドを更新するために使用できるフラグの例を次に示します。

    • --display-name=DISPLAY_NAME: UAP の表示名を指定した名前に置き換えます。
    • --details-rules=RULES_FILE: UAP ルールを、指定されたファイルのルールに置き換えます。ファイル内の各ルールは、次の形式にする必要があります。

      {
        "description": "DESCRIPTION",
        "effect": "EFFECT",
        "principals": [
          INCLUDED_PRINCIPALS
        ],
        "excludedPrincipals": [
          EXCLUDED_PRINCIPALS
        ],
        "operation": {
          "permissions": [
            INCLUDED_PERMISSIONS
          ],
          "excludedPermissions": [
            EXCLUDED_PERMISSIONS
          ]
        },
        CONDITIONS
      }

      次の値を置き換えます。

      • DESCRIPTION: 人が読める形式のルールの説明。
      • EFFECT: ルールがアクセスにどのように影響するか。サポートされている値は ALLOW と DENY です。

        • ALLOW: 指定されたプリンシパルに指定された権限を付与します。
        • DENY: 指定されたプリンシパルが指定された権限を使用できないようにします。
      • 次の値を置き換えて、ルールに含まれるプリンシパルを指定します。

        • INCLUDED_PRINCIPALS: ルールに含めるプリンシパル。
        • EXCLUDED_PRINCIPALS: 省略可。含まれるプリンシパルのリストに含まれている場合でも、ルールから除外するプリンシパル。たとえば、含まれるプリンシパルのリストに Google グループを追加し、そのグループに属する特定のユーザーを除外できます。

        サポートされているプリンシパル ID の一覧については、UAP のプリンシパル タイプをご覧ください。

      • 次の値を置き換えて、ルールに含める権限を指定します。

        • INCLUDED_PERMISSIONS: ルールに含める権限。
        • EXCLUDED_PERMISSIONS: 省略可。ルールから除外する権限。含まれる権限のリストに含まれている場合でも除外されます。たとえば、含まれる権限のリストにロールを追加してから、そのロールの特定の権限を除外できます。

        これらの権限リストを作成する際には、権限名、ロール名、権限グループを参照できます。詳細については、UAP ルールのロールと権限をご覧ください。

      • CONDITIONS: 省略可。ルールが適用される条件。形式は次のようにします。

        "conditions": {
          "SERVICE": {
            "title": "CONDITION_TITLE",
            "description": "CONDITION_DESCRIPTION",
            "expression": "CONDITION_EXPRESSION"
          }
        }
            

        次の値を置き換えます。

        • SERVICE: 条件式で使用される属性を提供するサービス。
        • CONDITION_TITLE: 省略可。条件の目的の概要。
        • CONDITION_DESCRIPTION: 省略可。条件の詳しい説明。
        • CONDITION_EXPRESSION: アクセス試行の属性(アクセス試行でリソースに適用されたタグなど)を参照するブール式。式が true と評価された場合、アクセス試行にルールが適用されます。false と評価された場合、ルールはアクセス試行に適用されません。

        サポート属性とそのサービスの一覧については、サポートされている条件属性をご覧ください。

    • --add-details-rules=RULES_FILE: 指定されたファイルのルールを UAP の既存のルールに追加します。

    • --remove-details-rules=RULES_FILE: 指定されたファイルのルールを UAP の既存のルールから削除します。指定したファイルのルールのいずれかに完全に一致するルールのみが削除されます。

    • --clear-details-rules: UAP からすべてのルールを消去します。

    UAP の更新に使用できるフラグの完全なリストについては、gcloud iam access-policies update コマンド リファレンスをご覧ください。一部のフラグは相互に排他的です。

  • FORMAT: レスポンスの形式。json または yaml を使用します。

次のコマンドを実行します。

Linux、macOS、Cloud Shell

gcloud iam access-policies update UAP_ID \
    --UAP_PARENT_RESOURCE_TYPE=UAP_PARENT_RESOURCE_ID \
    --location=global --FIELD_TO_UPDATE=UPDATED_VALUE \
    --format=FORMAT

Windows(PowerShell)

gcloud iam access-policies update UAP_ID `
    --UAP_PARENT_RESOURCE_TYPE=UAP_PARENT_RESOURCE_ID `
    --location=global --FIELD_TO_UPDATE=UPDATED_VALUE `
    --format=FORMAT

Windows(cmd.exe)

gcloud iam access-policies update UAP_ID ^
    --UAP_PARENT_RESOURCE_TYPE=UAP_PARENT_RESOURCE_ID ^
    --location=global --FIELD_TO_UPDATE=UPDATED_VALUE ^
    --format=FORMAT

レスポンスには、リクエストを表す長時間実行オペレーションが含まれます。オペレーションが完了すると、更新された UAP がレスポンスに出力されます。

Request issued for: [example-policy]
Waiting for operation [organizations/123456789012/locations/global/operations/operation-1715374208720-6181fae5e2034-2d8a712b-5c92e5b9] to complete...done.
Updated accessPolicy [example-policy].
{
  "createTime": "2026-08-31T21:43:39.822441Z",
  "details": {
    "rules": [
      {
        "conditions": {
          "iam.googleapis.com": {
            "expression": "resource.matchTag('environment', 'prod')"
          }
        },
        "description": "Grant non-delete compute permissions to compute admins in prod",
        "effect": "ALLOW",
        "excludedPrincipals": [
          "principal://goog/subject/access-restricted@example.com"
        ],
        "operation": {
          "excludedPermissions": [
            "*/*.delete"
          ],
          "permissions": [
            "role:roles/compute.admin"
          ]
        },
        "principals": [
          "principalSet://goog/group/compute-admins@example.com"
        ]
      }
    ]
  },
  "displayName": "Updated display name",
  "etag": "W/\"YZtdQgtulCVzvTwlBTFjPQ==\"",
  "name": "projects/0123456789012/locations/global/accessPolicies/example-policy",
  "uid": "puid_0123456789012345678",
  "updateTime": "2026-08-31T21:43:39.822441Z"
}

REST

accessPolicies.patch メソッドは、既存の UAP を更新します。

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

  • UAP_PARENT_RESOURCE_TYPE: 更新する UAP を所有する Resource Manager リソース(プロジェクト、フォルダ、組織)のタイプ。値 projects、folders、または organizations を使用します。
  • UAP_PARENT_RESOURCE_ID: 更新する UAP を所有するプロジェクト、フォルダ、または組織の ID。プロジェクト ID は英数字からなる文字列です(例: my-project)。フォルダ ID と組織 ID は数値です(例: 123456789012)。
  • UAP_ID: 更新する UAP の ID(例: example-policy)。
  • DISPLAY_NAME: 省略可。人が読める形式の UAP の説明(例: Example policy)。表示名は 63 文字以内にしてください。
  • UAP_RULES: UAP ルールのリスト。許可または拒否するアクセス権と、アクセス権を許可または拒否するプリンシパルを定義します。UAP には最大 100 個のルールを設定できます。各ルールの形式は次のとおりです。

    {
      "description": "DESCRIPTION",
      "effect": "EFFECT",
      "principals": [
        INCLUDED_PRINCIPALS
      ],
      "excludedPrincipals": [
        EXCLUDED_PRINCIPALS
      ],
      "operation": {
        "permissions": [
          INCLUDED_PERMISSIONS
        ],
        "excludedPermissions": [
          EXCLUDED_PERMISSIONS
        ]
      },
      CONDITIONS
    }

    次の値を置き換えます。

    • DESCRIPTION: 人が読める形式のルールの説明。
    • EFFECT: ルールがアクセスにどのように影響するか。サポートされている値は ALLOW と DENY です。

      • ALLOW: 指定されたプリンシパルに指定された権限を付与します。
      • DENY: 指定されたプリンシパルが指定された権限を使用できないようにします。
    • 次の値を置き換えて、ルールに含まれるプリンシパルを指定します。

      • INCLUDED_PRINCIPALS: ルールに含めるプリンシパル。
      • EXCLUDED_PRINCIPALS: 省略可。含まれるプリンシパルのリストに含まれている場合でも、ルールから除外するプリンシパル。たとえば、含まれるプリンシパルのリストに Google グループを追加し、そのグループに属する特定のユーザーを除外できます。

      サポートされているプリンシパル ID の一覧については、UAP のプリンシパル タイプをご覧ください。

    • 次の値を置き換えて、ルールに含める権限を指定します。

      • INCLUDED_PERMISSIONS: ルールに含める権限。
      • EXCLUDED_PERMISSIONS: 省略可。ルールから除外する権限。含まれる権限のリストに含まれている場合でも除外されます。たとえば、含まれる権限のリストにロールを追加してから、そのロールの特定の権限を除外できます。

      これらの権限リストを作成する際には、権限名、ロール名、権限グループを参照できます。詳細については、UAP ルールのロールと権限をご覧ください。

    • CONDITIONS: 省略可。ルールが適用される条件。形式は次のようにします。

      "conditions": {
        "SERVICE": {
          "title": "CONDITION_TITLE",
          "description": "CONDITION_DESCRIPTION",
          "expression": "CONDITION_EXPRESSION"
        }
      }
          

      次の値を置き換えます。

      • SERVICE: 条件式で使用される属性を提供するサービス。
      • CONDITION_TITLE: 省略可。条件の目的の概要。
      • CONDITION_DESCRIPTION: 省略可。条件の詳しい説明。
      • CONDITION_EXPRESSION: アクセス試行の属性(アクセス試行でリソースに適用されたタグなど)を参照するブール式。式が true と評価された場合、アクセス試行にルールが適用されます。false と評価された場合、ルールはアクセス試行に適用されません。

      サポート属性とそのサービスの一覧については、サポートされている条件属性をご覧ください。

HTTP メソッドと URL:

PATCH https://iam.googleapis.com/v3/UAP_PARENT_RESOURCE_TYPE/UAP_PARENT_RESOURCE_ID/locations/global/accessPolicies/UAP_ID

リクエストの本文(JSON):

{
  "displayName": "DISPLAY_NAME",
  "details": {
    "rules": [
      UAP_RULES
    ]
  }
}

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

レスポンスには、リクエストを表す長時間実行オペレーションが含まれます。長時間実行オペレーションのステータスを取得する方法については、このページの長時間実行オペレーションのステータスを確認するをご覧ください。

{
  "name": "organizations/123456789012/locations/global/operations/operation-1715626721931-6185a7953ef76-76f80ee4-19cd1bf7",
  "metadata": {
    "@type": "type.googleapis.com/google.iam.v3.OperationMetadata",
    "createTime": "2026-05-13T18:58:43.721277235Z",
    "target": "organizations/123456789012/locations/global/accessPolicies/example-policy",
    "verb": "update",
    "requestedCancellation": false,
    "apiVersion": "v3"
  },
  "done": false
}

ポリシーが適用されるリソースを変更する

UAP のバインディングを作成した後、バインディングのポリシー ID やリソースは変更できません。そのため、UAP の適用対象となるリソースを変更する場合は、次のいずれかを行う必要があります。

長時間実行オペレーションのステータスを確認する

REST API またはクライアント ライブラリを使用する場合、ポリシーまたはバインディングを変更するメソッドで長時間実行オペレーション(LRO)が返されます。長時間実行オペレーションは、リクエストのステータスを追跡し、ポリシーまたはバインディングの変更が完了したかどうかを示します。

REST

operations.get メソッドは、長時間実行オペレーションのステータスを返します。

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

  • OPERATION_NAME: オペレーションの完全な名前。この名前は、元のリクエストに対するレスポンスで受け取ります。

    オペレーション名の形式は次のとおりです。

    RESOURCE_TYPE/RESOURCE_ID/locations/global/operations/OPERATION_ID
        

HTTP メソッドと URL:

GET https://iam.googleapis.com/v3/OPERATION_NAME

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

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

{
  "name": "organizations/314340013352/locations/global/operations/operation-1732752311821-627edd607a3df-9a62cdea-2a7d9f07",
  "metadata": {
    "@type": "type.googleapis.com/google.iam.v3.OperationMetadata",
    "createTime": "2024-11-28T00:05:12.006289686Z",
    "endTime": "2024-11-28T00:05:12.192141801Z",
    "target": "organizations/314340013352/locations/global/POLICY_TYPE/POLICY_ID",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v3"
  },
  "done": true,
  "response": {
    POLICY
  }
}

オペレーションの done フィールドが存在しない場合は、オペレーションを繰り返し取得して、ステータスのモニタリングを続行します。各リクエストの間には、切り捨て型指数バックオフを使用して遅延時間を設けてください。done フィールドが true に設定されている場合、オペレーションは完了しており、オペレーションの取得を停止できます。

次のステップ