このページでは、Identity and Access Management(IAM)カスタムロールを作成および管理する方法について説明します。ロールの管理には、ロールの変更、無効化、一覧表示、削除、削除の取り消しが含まれます。
始める前に
IAM API を有効にします。
Google Cloud のリソース階層について理解する。
IAM のカスタムロールについてを読む。
必要なロール
カスタムロールを作成して管理するために必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。
-
プロジェクトのロールを管理する: ロールを管理するプロジェクトに対してロール管理者(
roles/iam.roleAdmin
) -
組織のロールを管理する: ロールを管理する組織に対して組織管理者(
roles/iam.organizationRoleAdmin
)
ロールの付与の詳細については、アクセスの管理をご覧ください。
プロジェクト、フォルダ、組織の利用可能な権限を表示する
カスタムロールは、組織全体、または組織内の特定のプロジェクトに対して作成できます。
カスタムロールには、すべてではありませんが、多くの IAM 権限を含めることができます。各権限には、カスタムロールで使用する次のいずれかのサポートレベルがあります。
サポートレベル | 説明 |
---|---|
SUPPORTED |
この権限は、カスタムロールで完全にサポートされます。 |
TESTING |
Google では、カスタムロールとの互換性を確認する権限をテストしています。カスタムロールに権限を含めることはできますが、予期しない動作が発生することがあります。本番環境での使用は推奨されていません。 |
NOT_SUPPORTED |
この権限は、カスタムロールではサポートされません。 |
組織レベルのカスタムロールには、カスタムロールでサポートされる任意の IAM 権限を含めることができます。プロジェクト レベルのカスタムロールには、サポートされている任意の権限を含めることができます。ただし、resourcemanager.organizations.get
など、組織レベルまたはフォルダレベルだけに関連する権限は除きます。
組織レベルとプロジェクト レベルのカスタムロールで使用できる権限を確認するには、gcloud CLI または Identity and Access Management API を使用して、具体的な組織やプロジェクトで使用可能な権限のリストを出力します。たとえば、プロジェクトで作成したカスタムロールで使用可能なすべての権限を取得できます。
カスタムロールでサポートされている場合でも、カスタムロールで一部の権限が表示されない場合や、使用できない場合があります。たとえば、サービスで API を有効にしていない場合は、カスタムロールで権限を使用できないことがあります。
gcloud CLI
gcloud iam list-testable-permissions
コマンドを使用して、具体的なプロジェクトや組織内のカスタムロールで使用可能な権限のリストを取得します。レスポンスには、そのプロジェクトや組織のカスタムロールで使用できる権限がリスト出力されます。
プロジェクトや組織のカスタムロールで使用可能な権限をリスト出力するには、次のコマンドを実行します。
gcloud iam list-testable-permissions full-resource-name \ --filter="customRolesSupportLevel!=NOT_SUPPORTED"
full-resource-name
は、次のいずれかの値に置き換えます。
- プロジェクト:
//cloudresourcemanager.googleapis.com/projects/project-id
(例://cloudresourcemanager.googleapis.com/projects/my-project-id
) - 組織:
//cloudresourcemanager.googleapis.com/organizations/numeric-id
(例://cloudresourcemanager.googleapis.com/organizations/123456789012
)
結果には、各権限がカスタムロールでサポートされているかどうかが示されます。customRolesSupportLevel
フィールドがない権限は、完全にサポートされている権限です。
list-testable-permissions
コマンドから非常に多くの結果が返されることがあります。出力の一部を抜粋した次の例では、各結果の形式を示します。
---
name: appengine.applications.create
stage: GA
---
customRolesSupportLevel: TESTING
name: appengine.applications.disable
stage: GA
---
name: appengine.applications.get
stage: GA
---
name: appengine.applications.update
stage: GA
---
name: appengine.instances.delete
stage: GA
---
name: appengine.instances.get
stage: GA
---
REST
permissions.queryTestablePermissions
メソッドを使用すると、組織やプロジェクトで使用可能な権限をリスト出力できます。
リクエストのデータを使用する前に、次のように置き換えます。
full-resource-name
: サービス名とリソースへのパスで構成される URI。例については、完全なリソース名をご覧ください。page-size
: 省略可。レスポンスに含める権限の数。デフォルト値は 100、最大値は 1,000 です。権限の数がページサイズよりも大きい場合、レスポンスには、次の結果ページを取得するために使用するページ設定トークンが含まれます。next-page-token
: 省略可。以前のレスポンスでこのメソッドから返されたページ設定トークン。指定すると、前のレスポンスが終了した時点から、テスト可能な権限のリストが開始します。
HTTP メソッドと URL:
POST https://iam.googleapis.com/v1/permissions:queryTestablePermissions
JSON 本文のリクエスト:
{ "fullResourceName": "full-resource-name" "pageSize": page-size, "pageToken": "next-page-token" }
リクエストを送信するには、次のいずれかのオプションを展開します。
レスポンスには、権限のリストが含まれます。
{ "permissions": [ { "name": "iam.serviceAccountKeys.create", "stage": "GA" }, { "name": "iam.serviceAccountKeys.delete", "stage": "GA" }, { "name": "iam.serviceAccountKeys.get", "stage": "GA" } ], "nextPageToken": "CgoHBajEfjUDQyABEPaIv5vIiMDTVhgDIhtpYW0uc2VydmljZUFjY291bnRLZXlzLmxpc3Q" }
C++
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM C++ API のリファレンス ドキュメントをご覧ください。
C#
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM C# API のリファレンス ドキュメントをご覧ください。
Go
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM Go API のリファレンス ドキュメントをご覧ください。
Python
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM Python API のリファレンス ドキュメントをご覧ください。
ロール メタデータの取得
カスタムロールを作成する前に、事前定義ロールとカスタムロールの両方のメタデータを取得する必要がある場合があります。ロール メタデータには、そのロールの ID と権限が含まれます。メタデータを表示するには、Google Cloud コンソールまたは IAM API を使用します。
ロール メタデータを表示するには、次のいずれかの方法で行います。
コンソール
Google Cloud コンソールで、[ロール] ページに移動します。
ページの上部にあるプルダウン リストから組織またはプロジェクトを選択します。
1 つ以上のロールのチェックボックスを選択して、ロールの権限を表示します。ロールに含まれている権限があれば、右側のパネルに表示されます。
タイプ列のアイコンは、カスタムロール
か、事前定義ロール かを示しています。
特定の権限を含むロールをすべて検索するには、[ロール] リストの上部にある [フィルタ] ボックスに権限名を入力します。
gcloud CLI
gcloud iam roles describe
コマンドを使用して、事前定義ロールとカスタムロールのメタデータを表示します。
事前定義ロールのメタデータを表示するには、次のコマンドを実行します。
gcloud iam roles describe role-id
role-id
はロールの ID です。事前定義ロールの ID には role
接頭辞が含まれます(roles/iam.roleViewer
など)。
次の例に、describe
が事前定義ロール roles/iam.roleViewer
で実行された場合の出力の例を示します。
gcloud iam roles describe roles/iam.roleViewer
description: Read access to all custom roles in the project. etag: AA== includedPermissions: - iam.roles.get - iam.roles.list - resourcemanager.projects.get - resourcemanager.projects.getIamPolicy name: roles/iam.roleViewer stage: GA title: Role Viewer
カスタムロールのメタデータを表示するには、次のいずれかのコマンドを実行します。
組織レベルで作成されたカスタムロールのメタデータを表示するには、次のコマンドを実行します。
gcloud iam roles describe --organization=organization-id role-id
プロジェクト レベルで作成されたカスタムロールのメタデータを表示するには、次のコマンドを実行します。
gcloud iam roles describe --project=project-id role-id
各プレースホルダ値についての説明は次のとおりです。
organization-id
は組織の数値 ID です(123456789012
など)。project-id
はプロジェクトの名前です(my-project-id
など)。role-id
はロールの ID です。projects/
、organizations/
、roles/
などの接頭辞は含まれません。例:myCompanyAdmin
。
詳細については、gcloud iam roles describe
のリファレンス ドキュメントをご覧ください。
REST
roles.get
メソッドはロールの定義を取得します。
リクエストのデータを使用する前に、次のように置き換えます。
role-name
:organizations/
、projects/
、roles/
のいずれかの接頭辞を含む完全なロール名。たとえば、organizations/123456789012/roles/myCompanyAdmin
。
HTTP メソッドと URL:
GET https://iam.googleapis.com/v1/full-role-id
リクエストを送信するには、次のいずれかのオプションを展開します。
レスポンスにはロールの定義が含まれます。
{ "name": "projects/my-project/roles/customRole", "title": "My Custom Role", "description": "My custom role description.", "includedPermissions": [ "storage.buckets.get", "storage.buckets.list" ], "etag": "BwWiPg2fmDE=" }
C++
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM C++ API のリファレンス ドキュメントをご覧ください。
C#
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM C# API のリファレンス ドキュメントをご覧ください。
Go
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM Go API のリファレンス ドキュメントをご覧ください。
Python
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM Python API のリファレンス ドキュメントをご覧ください。
カスタムロールの作成
カスタムロールは、プロジェクト レベルまたは組織レベルで作成できます。
カスタムロールを作成するには、呼び出し側に iam.roles.create
権限が必要です。デフォルトでは、プロジェクトや組織のオーナーがこの権限を持ち、カスタムロールを作成して管理できます。
オーナー以外のユーザー(組織管理者を含む)には、「組織のロールの管理者」ロールまたは「IAM ロールの管理者」ロールのいずれかを割り当てる必要があります。
カスタムロールには、最大 3,000 個の権限を含めることができます。また、カスタムロールのタイトル、説明、権限名の最大合計サイズは 64 KB です。より大きなカスタムロールを作成する必要がある場合は、権限を複数のカスタムロールに分割できます。Custom Admin (1 of 2)
や Custom Admin (2 of 2)
など、カスタムロール間の関係を示すロールタイトルを選択します。
カスタムロールにはリリース ステージを設定できます。リリース ステージのほとんどは情報提供を目的としています。これにより、各ロールを広く使用できるかどうかをトラッキングできます。さらに、DISABLED
リリース ステージでは、カスタムロールを無効にすることができます。リリース ステージの詳細については、テストとデプロイをご覧ください。
コンソール
一部の事前定義ロールには、サポートが終了した権限や、カスタムロールでは許可されない権限が含まれています。そのような事前定義ロールをに基づいてカスタムロールを作成する場合、サポートが終了した権限、制限されている権限はカスタムロールから省略されます。
最初から新しいカスタムロールを作成するには:
Google Cloud コンソールで、[ロール] ページに移動します。
ページの上部にあるプルダウン リストを使用して、ロールを作成する組織またはプロジェクトを選択します。
[ロールの作成] をクリックします。
ロールの名前、タイトル、説明、ロールのリリース ステージを入力します。ロールの作成後にロール名を変更することはできません。
[権限を追加] をクリックします。
ロールに含める権限を選択し、[権限を追加] をクリックします。[すべてのサービス] と [すべての種類] プルダウン リストを使用して、サービスと種類別に権限をフィルタリングして選択します。
既存の事前定義ロールに基づいてカスタムロールを作成するには:
- Google Cloud コンソールで、[ロール] ページに移動します。
- ロールを作成する組織またはプロジェクトを選択します。
- 新しいカスタムロールのベースにするロールを選択します。
- [選択内容からロールを作成] をクリックします。
- ロールの名前、タイトル、説明、ロールのリリース ステージを入力します。ロールの作成後にロール名を変更することはできません。
- ロールから除外する権限のチェックボックスをオフにします。
- [権限を追加] をクリックして権限を追加します。
- [作成] をクリックします。
gcloud CLI
gcloud iam roles create
を使用して、新しいカスタムロールを作成します。このコマンドは次の 2 つの方法で使用できます。
- ロール定義が含まれる YAML ファイルを使用する
- フラグを使用してロール定義を指定する
カスタムロールを作成するには、--organization=organization-id
または --project=project-id
フラグを指定して、ロールを組織レベルとプロジェクト レベルのどちらで適用するかを指定する必要があります。以下の各例では、プロジェクト レベルでカスタムロールを作成します。
カスタムロールには、カスタムロールでサポートされる権限のみを含めることができます。カスタムロールに他の権限が含まれている場合、コマンドは失敗します。
YAML ファイルを使用してカスタムロールを作成するには:
カスタムロール定義が含まれる YAML ファイルを作成します。このファイルは次のような構造にする必要があります。
title: role-title description: role-description stage: launch-stage includedPermissions: - permission-1 - permission-2
各プレースホルダ値についての説明は次のとおりです。
role-title
は、ロールのわかりやすいタイトルです("My Company Admin"
など)。role-description
は、ロールに関する簡単な説明です("My custom role description"
など)。launch-stage
は、リリースのライフサイクルにおけるロールの段階を示します(ALPHA
、BETA
、GA
など)。permission-1
とpermission-2
は、iam.roles.get
などのカスタムロールに含める権限です。権限名にワイルドカード文字(*
)は使用できません。
YAML ファイルを保存し、次のいずれかのコマンドを実行します。
組織レベルでカスタムロールを作成するには、次のコマンドを実行します。
gcloud iam roles create role-id --organization=organization-id \ --file=yaml-file-path
プロジェクト レベルでカスタムロールを作成するには、次のコマンドを実行します。
gcloud iam roles create role-id --project=project-id \ --file=yaml-file-path
各プレースホルダ値についての説明は次のとおりです。
role-id
はロールの名前です(myCompanyAdmin
など)。organization-id
は組織の数値 ID です(123456789012
など)。project-id
はプロジェクトの名前です(my-project-id
など)。yaml-file-path
は、カスタムロール定義が含まれる YAML ファイルの場所へのパスです。
例
次の YAML ファイルの例では、ロール定義を作成する方法を示します。
title: "My Company Admin" description: "My custom role description." stage: "ALPHA" includedPermissions: - iam.roles.get - iam.roles.list
次の例は、YAML ファイルを使用して組織レベルでロールを作成する方法を示しています。
gcloud iam roles create myCompanyAdmin --organization=123456789012 \ --file=my-role-definition.yaml
ロールが正常に作成された場合、コマンドの出力は次のようになります。
Created role [myCompanyAdmin]. description: My custom role description. etag: BwVkBX0sQD0= includedPermissions: - iam.roles.get - iam.roles.list name: organizations/123456789012/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
次の例は、YAML ファイルを使用してプロジェクト レベルでロールを作成する方法を示しています。
gcloud iam roles create myCompanyAdmin --project=my-project-id \ --file=my-role-definition.yaml
ロールが正常に作成された場合、コマンドの出力は次のようになります。
Created role [myCompanyAdmin]. description: My custom role description. etag: BwVkBX0sQD0= includedPermissions: - iam.roles.get - iam.roles.list name: projects/my-project-id/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
フラグを使用してカスタムロールを作成するには:
次のいずれかのコマンドを実行します。
組織レベルでカスタムロールを作成するには、次のコマンドを実行します。
gcloud iam roles create role-id --organization=organization-id \ --title=role-title --description=role-description \ --permissions="permissions-list" --stage=launch-stage
プロジェクト レベルでカスタムロールを作成するには、次のコマンドを実行します。
gcloud iam roles create role-id --project=project-id \ --title=role-title --description=role-description \ --permissions="permissions-list" --stage=launch-stage
各プレースホルダ値についての説明は次のとおりです。
role-id
はロールの名前です(myCompanyAdmin
など)。organization-id
は組織の数値 ID です(123456789012
など)。project-id
はプロジェクトの名前です(my-project-id
など)。role-title
は、ロールのわかりやすいタイトルです("My Company Admin"
など)。role-description
は、ロールに関する簡単な説明です("My custom role description."
など)。permissions-list
には、カスタムロールに含める権限のカンマ区切りのリストが含まれます。例:iam.roles.get,iam.roles.list
。権限名にワイルドカード文字(*
)は使用できません。launch-stage
は、リリースのライフサイクルにおけるロールの段階を示します(ALPHA
、BETA
、GA
など)。
例
次の例は、フラグを使用して組織レベルでロールを作成する方法を示しています。
gcloud iam roles create myCompanyAdmin --organization=123456789012\ --title="My Company Admin" --description="My custom role description." \ --permissions="iam.roles.get,iam.roles.list" --stage=ALPHA
ロールが正常に作成された場合、コマンドの出力は次のようになります。
Created role [myCompanyAdmin]. description: My custom role description. etag: BwVkBX0sQD0= includedPermissions: - iam.roles.get - iam.roles.list name: organizations/123456789012/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
次の例は、フラグを使用してプロジェクト レベルでロールを作成する方法を示しています。
gcloud iam roles create myCompanyAdmin --project=my-project-id \ --title="My Company Admin" --description="My custom role description." \ --permissions="iam.roles.get,iam.roles.list" --stage=ALPHA
ロールが正常に作成された場合、コマンドの出力は次のようになります。
Created role [myCompanyAdmin]. description: My custom role description. etag: BwVkBX0sQD0= includedPermissions: - iam.roles.get - iam.roles.list name: projects/my-project-id/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
REST
roles.create
メソッドを使用すると、プロジェクトまたは組織にカスタムロールを作成できます。
リクエストのデータを使用する前に、次のように置き換えます。
resource-type
: カスタムロールを管理するリソースタイプ。値projects
またはorganizations
を使用します。resource-id
: カスタムロールを管理するプロジェクト ID または組織 ID。プロジェクト ID は英数字からなる文字列です(例:my-project
)。組織 ID は数値で指定します(例:123456789012
)。role-id
: ロールの名前(myCompanyAdmin
など)。role-title
: 人が読める形式のロールタイトル。例:My Company Admin
role-description
: ロールの説明。例:"The company admin role allows company admins to access important resources"
-
permission-1
とpermission-2
: ロールに含める権限。例:storage.objects.update
。権限名にワイルドカード文字(*
)は使用できません。カスタムロールには、カスタムロールでサポートされる権限のみを含めることができます。カスタムロールに他のロールが含まれている場合、リクエストは失敗します。
launch-stage
: ロールの現在のリリース ステージ。このフィールドの値は、EAP
、ALPHA
、BETA
、GA
、DEPRECATED
、DISABLED
のいずれかになります。
HTTP メソッドと URL:
POST https://iam.googleapis.com/v1/resource-type/resource-id/roles
JSON 本文のリクエスト:
{ "roleId": "role-id", "role": { "title": "role-title", "description": "role-description", "includedPermissions": [ "permission-1", "permission-2" ], "stage": "launch-stage" } }
リクエストを送信するには、次のいずれかのオプションを展開します。
作成したロールがレスポンスに含まれます。
{ "name": "projects/myProject/roles/myCompanyAdmin", "title": "My Company Admin", "description": "My custom role description.", "includedPermissions": [ "iam.roles.get", "iam.roles.list" ], "etag": "BwWox/JbaZw=" }
C++
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM C++ API のリファレンス ドキュメントをご覧ください。
C#
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM C# API のリファレンス ドキュメントをご覧ください。
Go
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM Go API のリファレンス ドキュメントをご覧ください。
Python
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM Python API のリファレンス ドキュメントをご覧ください。
既存のカスタムロールの編集
カスタムロールなどのリソースのメタデータの更新では、一般に「読み取り - 変更 - 書き込み」のパターンが使用されます。このパターンでは、ロールの現在の状態を読み取り、データをローカルに更新した後、変更したデータを送信して書き込みます。
読み取り - 変更 - 書き込みパターンでは、2 つ以上の独立したプロセスが一連の操作を同時に試行する場合に競合が発生することがあります。たとえば、プロジェクトの 2 人のオーナーが、1 つのロールに対して相反する変更を同時に行うと、一部の変更が失敗する可能性があります。IAM では、カスタムロールの etag
プロパティを使用してこの問題を解決します。このプロパティは、カスタムロールが最後のリクエスト以降に変更されているかどうかを確認するために使用されます。etag 値を使用して IAM にリクエストを送信すると、IAM はリクエスト内の etag 値をカスタムロールに関連付けられた既存の etag 値と比較します。etag 値が一致した場合にのみ変更を書き込みます。
ロールを更新する場合は、roles.get()
でロールを取得して更新します。その後、roles.patch()
を使用して、更新されたロールを書き込みます。ロールを設定するときに etag 値を使用するのは、roles.get()
内の対応するロールに etag 値が含まれている場合のみです。
コンソール
Google Cloud コンソールで、[ロール] ページに移動します。
ページの上部にあるプルダウン リストを使用して、編集するロールを含むプロジェクトまたは組織を選択します。
カスタムロールをクリックします。
[ロールを編集] をクリックします。
ロールのメタデータを更新するには、ロールのタイトル、説明、またはロールのリリース ステージを編集します。
ロールの権限を更新するには、次の手順を行います。
- ロールに新しい権限を追加するには、[権限を追加] をクリックします。
- ロールから権限を削除する権限のチェックボックスをオフにします。
[更新] をクリックして、編集したロールを保存します。
gcloud CLI
gcloud iam roles update
を使用して、カスタムロールを更新します。このコマンドは次の 2 つの方法で使用できます。
- 更新されたロール定義が含まれる YAML ファイルを使用する
- フラグを使用して、更新されたロール定義を指定する
カスタムロールを更新する場合は、--organization=organization-id
フラグまたは --project=project-id
フラグを使用して、組織レベルとプロジェクト レベルのどちらでロールを適用するのかを指定する必要があります。以下の各例では、プロジェクト レベルでカスタムロールを作成します。
YAML ファイルを使用してカスタムロールを更新するには:
次のいずれかのコマンドを実行して、ロールの現在の定義を取得します。
組織レベルのカスタムロールのロール定義を取得するには、次のコマンドを実行します。
gcloud iam roles describe role-id --organization=organization-id
プロジェクト レベルのカスタムロールのロール定義を取得するには、次のコマンドを実行します。
gcloud iam roles describe role-id --project=project-id
各プレースホルダ値についての説明は次のとおりです。
role-id
は、更新するロールの名前です(myCompanyAdmin
など)。organization-id
は組織の数値 ID です(123456789012
など)。project-id
はプロジェクトの名前です(my-project-id
など)。
describe
コマンドはロール定義を返し、その定義にはロールの現在のバージョンを一意に特定する etag
値が含まれます。ロールの同時変更が上書きされないように、更新されたロール定義に etag
値を指定する必要があります。
describe
コマンドは、次の出力を返します。
description: role-description etag: etag-value includedPermissions: - permission-1 - permission-2 name: role-name stage: launch-stage title: role-title
各プレースホルダ値についての説明は次のとおりです。
role-description
は、ロールに関する簡単な説明です("My custom role description"
など)。etag-value
は、ロールの現在のバージョンの一意の識別子です(BwVkBkbfr70=
など)。permission-1
とpermission-2
は、iam.roles.get
などのカスタムロールに含める権限です。権限名にワイルドカード文字(*
)は使用できません。role-name
は、organizations/
、projects/
、roles/
のいずれかの接頭辞を含む完全なロール名です。(例:organizations/123456789012/roles/myCompanyAdmin.
)launch-stage
は、リリースのライフサイクルにおけるロールの段階を示します(ALPHA
、BETA
、GA
など)。role-title
は、ロールのわかりやすいタイトルです("My Company Admin"
など)。
ロールを更新するには、出力されたロール定義を YAML ファイルに含めるか、または元の YAML ファイルを出力された etag
値で更新します。
次の YAML ファイルの例では、プロジェクト レベルのロールの describe
コマンドからの出力が含まれ、2 つの Cloud Storage 権限が追加されています。
description: My custom role description. etag: BwVkBkbfr70= includedPermissions: - iam.roles.get - iam.roles.list - storage.buckets.get - storage.buckets.list name: projects/my-project-id/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
YAML ファイルを保存し、次のいずれかのコマンドを実行します。
組織レベルのロールを更新するには、次のコマンドを実行します。
gcloud iam roles update role-id --organization=organization-id \ --file=yaml-file-path
プロジェクト レベルのロールを更新するには、次のコマンドを実行します。
gcloud iam roles update role-id --project=project-id \ --file=yaml-file-path
各プレースホルダ値についての説明は次のとおりです。
role-id
は、更新するロールの名前です(myCompanyAdmin
など)。organization-id
は組織の数値 ID です(123456789012
など)。project-id
はプロジェクトの名前です(my-project-id
など)。yaml-file-path
は、更新されたカスタムロール定義が含まれる YAML ファイルの場所のパスです。
例
次の例は、YAML ファイルを使用して組織レベルのロールを更新する方法を示しています。
gcloud iam roles update myCompanyAdmin --organization=123456789012 \ --file=my-role-definition.yaml
ロールが正常に更新された場合、コマンドの出力は次のようになります。
description: My custom role description. etag: BwVkBwDN0lg= includedPermissions: - iam.roles.get - iam.roles.list - storage.buckets.get - storage.buckets.list name: organizations/123456789012/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
次の例は、YAML ファイルを使用してプロジェクト レベルのロールを更新する方法を示しています。
gcloud iam roles update myCompanyAdmin --project=my-project-id \ --file=my-role-definition.yaml
ロールが正常に更新された場合、コマンドの出力は次のようになります。
description: My custom role description. etag: BwVkBwDN0lg= includedPermissions: - iam.roles.get - iam.roles.list - storage.buckets.get - storage.buckets.list name: projects/my-project-id/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
フラグを使用してカスタムロールを更新するには:
ロール定義の各部分は、対応するフラグを使用して更新できます。使用可能なフラグの一覧については、gcloud iam roles update
トピックをご覧ください。
次のフラグを使用して、権限を追加または削除できます。
--add-permissions=permissions
: 権限をロールに追加します。複数の権限を追加する場合は権限をカンマで区切ります。権限名にワイルドカード文字(*
)は使用できません。--remove-permissions=permissions
: 権限(複数の場合はカンマで区切る)をロールから削除します。権限名にワイルドカード文字(*
)は使用できません。
または、--permissions=permissions
フラグを使用して新しい権限を指定することもできます。権限のカンマ区切りのリストを指定すると、既存の権限のリストが置き換えられます。
ロール定義の他の部分を更新するには、次のいずれかのコマンドを実行します。
組織レベルのロールを更新するには、次のコマンドを実行します。
gcloud iam roles update role-id --organization=organization-id \ --title=role-title --description=role-description \ --stage=launch-stage
プロジェクト レベルのロールを更新するには、次のコマンドを実行します。
gcloud iam roles update role-id --project=project-id \ --title=role-title --description=role-description \ --stage=launch-stage
各プレースホルダ値についての説明は次のとおりです。
role-id
はロールの名前です(myCompanyAdmin
など)。organization-id
は組織の数値 ID です(123456789012
など)。project-id
はプロジェクトの名前です(my-project-id
など)。role-title
は、ロールのわかりやすいタイトルです("My Company Admin"
など)。role-description
は、ロールに関する簡単な説明です("My custom role description."
など)。launch-stage
は、リリースのライフサイクルにおけるロールの段階を示します(ALPHA
、BETA
、GA
など)。
例
次の例は、フラグを使用して組織レベルのロールに権限を追加する方法を示しています。
gcloud iam roles update myCompanyAdmin --organization=123456789012 \ --add-permissions="storage.buckets.get,storage.buckets.list"
ロールが正常に更新された場合、コマンドの出力は次のようになります。
description: My custom role description. etag: BwVkBwDN0lg= includedPermissions: - iam.roles.get - iam.roles.list - storage.buckets.get - storage.buckets.list name: organization/123456789012/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
次の例は、フラグを使用してプロジェクト レベルのロールに権限を追加する方法を示しています。
gcloud iam roles update myCompanyAdmin --project=my-project-id \ --add-permissions="storage.buckets.get,storage.buckets.list"
ロールが正常に更新された場合、コマンドの出力は次のようになります。
description: My custom role description. etag: BwVkBwDN0lg= includedPermissions: - iam.roles.get - iam.roles.list - storage.buckets.get - storage.buckets.list name: projects/my-project-id/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
REST
roles.patch
メソッドを使用すると、プロジェクトまたは組織内のカスタムロールを更新できます。
リクエストのデータを使用する前に、次のように置き換えます。
必須:
resource-type
: カスタムロールを管理するリソースタイプ。値projects
またはorganizations
を使用します。resource-id
: カスタムロールを管理するプロジェクト ID または組織 ID。プロジェクト ID は英数字からなる文字列です(例:my-project
)。組織 ID は数値で指定します(例:123456789012
)。role-name
:organizations/
、projects/
、roles/
のいずれかの接頭辞を含む完全なロール名。たとえば、organizations/123456789012/roles/myCompanyAdmin
。
推奨:
etag
: ロールのバージョンの識別子。他のロールの変更を上書きしないようにするには、このフィールドを指定します。
省略可(以下の値を 1 つ以上定義します):
role-title
: 人が読める形式のロールタイトル。例:My Company Admin
role-description
: ロールの説明。例:"The company admin role allows company admins to access important resources"
permission-1
とpermission-2
: ロールに含める権限。例:storage.objects.update
。権限名にワイルドカード文字(*
)は使用できません。launch-stage
: ロールの現在のリリース ステージ。このフィールドの値は、EAP
、ALPHA
、BETA
、GA
、DEPRECATED
、DISABLED
のいずれかになります。
HTTP メソッドと URL:
PATCH https://iam.googleapis.com/v1/resource-type/resource-id/roles
JSON 本文のリクエスト:
{ "roleId": "full-role-id", "title": "role-title", "description": "role-description", "includedPermissions": [ "permission-1", "permission-2" ], "stage": "launch-stage", "etag": "etag" }
リクエストを送信するには、次のいずれかのオプションを展開します。
レスポンスには省略されたロール定義が含まれます。この定義には、ロール名、更新したフィールド、ロールの現在のバージョンを識別する ETag が含まれます。
{ "name": "projects/test-project-1000092/roles/myCompanyAdmin", "title": "My Updated Company Admin", "includedPermissions": [ "storage.buckets.get", "storage.buckets.list" ], "stage": "BETA", "etag": "BwWoyDpAxBc=" }
C++
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM C++ API のリファレンス ドキュメントをご覧ください。
C#
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM C# API のリファレンス ドキュメントをご覧ください。
Go
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM Go API のリファレンス ドキュメントをご覧ください。
Python
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM Python API のリファレンス ドキュメントをご覧ください。
カスタムロールの無効化
カスタムロールを無効にするには、リリース ステージを DISABLED
に変更します。ロールを無効にすると、そのロールに関連するロール バインディングはすべて無効になります。つまり、ユーザーにロールを付与しても効果はありません。
コンソール
Google Cloud コンソールで、[ロール] ページに移動します。
ページの上部にある [プロジェクトを選択] プルダウン リストをクリックします。
組織またはプロジェクトを選択します。
カスタムロールを選択し、[無効] をクリックします。
gcloud CLI
gcloud iam roles update
コマンドを使用して、開始ステージを DISABLED
に設定し、カスタムロールを無効にします。既存のカスタムロールの編集の gcloud タブで説明されているように、次の 2 つの方法で既存のカスタムロールを更新できます。
- 更新されたロール定義が含まれる YAML ファイルを使用する
- フラグを使用して、更新されたロール定義を指定する
既存のカスタムロールを無効にする最も簡単な方法は、--stage
フラグを DISABLED
に設定する方法です。次のいずれかのコマンドを実行します。
組織レベルのロールを無効にするには、次のコマンドを実行します。
gcloud iam roles update role-id --organization=organization-id \ --stage=DISABLED
プロジェクト レベルのロールを無効にするには、次のコマンドを実行します。
gcloud iam roles update role-id --project=project-id \ --stage=DISABLED
各プレースホルダ値についての説明は次のとおりです。
role-id
はロールの名前です(myCompanyAdmin
など)。organization-id
は組織の数値 ID です(123456789012
など)。project-id
はプロジェクトの名前です(my-project-id
など)。
例
次の例は、組織レベルのロールを無効にする方法を示しています。
gcloud iam roles update myCompanyAdmin --organization=123456789012 \ --stage=DISABLED
ロールが正常に更新された場合、コマンドの出力は次のようになります。
description: My custom role description. etag: BwVkB5NLIQw= includedPermissions: - iam.roles.get - iam.roles.list name: organization/123456789012/roles/myCompanyAdmin stage: DISABLED title: My Company Admin
次の例は、プロジェクト レベルのロールを無効にする方法を示しています。
gcloud iam roles update myCompanyAdmin --project=my-project-id \ --stage=DISABLED
ロールが正常に更新された場合、コマンドの出力は次のようになります。
description: My custom role description. etag: BwVkB5NLIQw= includedPermissions: - iam.roles.get - iam.roles.list name: projects/my-project-id/roles/myCompanyAdmin stage: DISABLED title: My Company Admin
REST
roles.patch
メソッドを使用すると、カスタムロールのリリース ステージを DISABLED
に変更し、ロールを無効にすることができます。
リクエストのデータを使用する前に、次のように置き換えます。
resource-type
: カスタムロールを管理するリソースタイプ。値projects
またはorganizations
を使用します。resource-id
: カスタムロールを管理するプロジェクト ID または組織 ID。プロジェクト ID は英数字からなる文字列です(例:my-project
)。組織 ID は数値で指定します(例:123456789012
)。role-name
:organizations/
、projects/
、roles/
のいずれかの接頭辞を含む完全なロール名。たとえば、organizations/123456789012/roles/myCompanyAdmin
。etag
: ロールのバージョンの識別子。他のロールの変更を上書きしないようにするには、このフィールドを指定します。
HTTP メソッドと URL:
PATCH https://iam.googleapis.com/v1/resource/resource-id/roles
JSON 本文のリクエスト:
{ "roleId": "full-role-id", "stage": DISABLED, "etag": "etag" }
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "name": "projects/test-project-1000092/roles/myCompanyAdmin", "stage": "DISABLED", "etag": "BwWoyDpAxBc=" }
C++
ロールの stage
フィールドを DISABLED
に更新します。
C#
ロールの stage
フィールドを DISABLED
に更新します。
Go
ロールの stage
フィールドを DISABLED
に更新します。
Python
ロールの stage
フィールドを DISABLED
に更新します。
ロールの一覧表示
プロジェクトまたは組織で作成されたすべてのカスタムロールを一覧表示できます。
コンソール
Google Cloud コンソールで、[ロール] ページに移動します。
選択した組織またはプロジェクトのすべてのカスタムロールが一覧表示されます。
gcloud CLI
gcloud iam roles list
コマンドを使用して、プロジェクトまたは組織のカスタムロールと事前定義ロールを一覧表示します。
組織レベルのカスタムロールを一覧表示するには、次のコマンドを実行します。
gcloud iam roles list --organization=organization-id
プロジェクト レベルのカスタムロールを一覧表示するには、次のコマンドを実行します。
gcloud iam roles list --project=project-id
各プレースホルダ値についての説明は次のとおりです。
organization-id
は組織の数値 ID です(123456789012
など)。project-id
はプロジェクトの名前です(my-project-id
など)。
削除されたロールを一覧表示するには、--show-deleted
フラグを指定します。
次のコマンドを実行して、事前定義ロールを一覧表示します。
gcloud iam roles list
REST
roles.list
メソッドを使用すると、プロジェクトまたは組織内のすべてのカスタムロールを一覧表示できます。
リクエストのデータを使用する前に、次のように置き換えます。
resource-type
: カスタムロールを管理するリソースタイプ。値projects
またはorganizations
を使用します。resource-id
: カスタムロールを管理するプロジェクト ID または組織 ID。プロジェクト ID は英数字からなる文字列です(例:my-project
)。組織 ID は数値で指定します(例:123456789012
)。role-view
: 省略可。返されるロールに含める情報。ロールの権限を含めるには、このフィールドをFULL
に設定します。ロールの権限を除外するには、このフィールドをBASIC
に設定します。デフォルト値はBASIC
です。page-size
: 省略可。レスポンスに含めるロールの数。デフォルト値は 300、最大値は 1,000 です。ロールの数がページサイズよりも大きい場合、レスポンスには、次の結果ページを取得するために使用するページ設定トークンが含まれます。next-page-token
: 省略可。以前のレスポンスでこのメソッドから返されたページ設定トークン。指定すると、前のリクエストが終了した時点からロールのリストが開始します。
HTTP メソッドと URL:
GET https://iam.googleapis.com/v1/resource-type/resource-id/roles?view=role-view&pageSize=page-size&pageToken=next-page-token
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "roles": [ { "name": "projects/my-project/roles/customRole1", "title": "First Custom Role", "description": "Created on: 2020-06-01", "etag": "BwWiPg2fmDE=" }, { "name": "projects/my-project/roles/customRole2", "title": "Second Custom Role", "description": "Created on: 2020-06-07", "etag": "BwWiuX53Wi0=" } ] }
C++
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM C++ API のリファレンス ドキュメントをご覧ください。
C#
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM C# API のリファレンス ドキュメントをご覧ください。
Go
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM Go API のリファレンス ドキュメントをご覧ください。
Python
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM Python API のリファレンス ドキュメントをご覧ください。
カスタムロールの削除
プロジェクトまたは組織内のカスタムロールを削除できます。
コンソール
Google Cloud コンソールで、[ロール] ページに移動します。
削除するロールを選択して、ページの上部にある delete(削除)をクリックします。
gcloud CLI
gcloud iam roles delete
コマンドを使用して、カスタムロールを削除します。
組織レベルのカスタムロールを削除するには、次のコマンドを実行します。
gcloud iam roles delete role-id --organization=organization-id
プロジェクト レベルのカスタムロールを削除するには、次のコマンドを実行します。
gcloud iam roles delete role-id --project=project-id
各プレースホルダ値についての説明は次のとおりです。
role-id
はロールの名前です(myCompanyAdmin
など)。organization-id
は組織の数値 ID です(123456789012
など)。project-id
はプロジェクトの名前です(my-project-id
など)。
--show-deleted
フラグが含まれていない場合は、gcloud iam roles list
にロールが含まれません。削除されたロールは、次のように、list
レスポンスの deleted: true
ブロックに示されます。
--- deleted: true description: My custom role description. etag: BwVkB5NLIQw= name: projects/my-project-id/roles/myCompanyAdmin title: My Company Admin ---
REST
roles.delete
メソッドを使用すると、プロジェクトまたは組織内のカスタムロールを削除できます。
リクエストのデータを使用する前に、次のように置き換えます。
role-name
:organizations/
、projects/
、roles/
のいずれかの接頭辞を含む完全なロール名。たとえば、organizations/123456789012/roles/myCompanyAdmin
。
HTTP メソッドと URL:
DELETE https://iam.googleapis.com/v1/full-role-id
リクエストを送信するには、次のいずれかのオプションを展開します。
レスポンスには、削除されたロールの定義が含まれます。
{ "name": "projects/my-project/roles/myCompanyAdmin", "title": "My Company Admin", "description": "My custom role description.", "includedPermissions": [ "iam.roles.get", "iam.roles.list" ], "etag": "BwWiPg2fmDE=", "deleted": true }
C++
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM C++ API のリファレンス ドキュメントをご覧ください。
C#
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM C# API のリファレンス ドキュメントをご覧ください。
Go
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM Go API のリファレンス ドキュメントをご覧ください。
Python
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM Python API のリファレンス ドキュメントをご覧ください。
ロールを削除しても、そのロールを参照するロール バインディングは許可ポリシーに残りますが、効果はありません。ロールは 7 日以内であれば削除を取り消すことができます。この 7 日間、Google Cloud コンソールにはロールが削除されたことが表示されます。削除されたロールはプログラムで一覧表示することもできますが、デフォルトでは省略されています。
削除されたロールは 7~14 日後に完全に削除されます。その時点で、このロールは組織あたり 300 個のカスタムロールの上限、またはプロジェクトあたり 300 個のカスタムロールの上限にカウントされなくなります。
完全に削除するには 30 日かかります。この 30 日間の間に、ロールと、そのロールに関連付けられているすべてのバインディングが完全に削除されます。同じロール ID を使用して新しいロールを作成することはできません。
最初の削除リクエストの発行からロールが完全に削除された後 44 日以内であれば、同じロール ID を使用して新しいロールを作成できます。
カスタムロールの削除の取り消し
ロールの削除を取り消すと、以前の状態に戻ります。
ロールの削除は、削除から 7 日以内に限って取り消すことができます。7 日が経過すると、ロールは完全に削除され、そのロールを参照するすべてのロール バインディングが削除されます。
コンソール
Google Cloud コンソールで、[ロール] ページに移動します。
削除を取り消すロールを見つけ、行の最後にあるその他アイコンをクリックして [削除を取り消す] をクリックします。
gcloud CLI
gcloud iam roles undelete
を使用して、カスタムロールの削除を取り消します。
組織レベルのカスタムロールの削除を取り消すには、次のコマンドを実行します。
gcloud iam roles undelete role-id --organization=organization-id
プロジェクト レベルのカスタムロールの削除を取り消すには、次のコマンドを実行します。
gcloud iam roles undelete role-id --project=project-id
各プレースホルダ値についての説明は次のとおりです。
role-id
はロールの名前です(myCompanyAdmin
など)。organization-id
は組織の数値 ID です(123456789012
など)。project-id
はプロジェクトの名前です(my-project-id
など)。
例
次の例は、組織レベルのカスタムロールの削除を取り消す方法を示しています。
gcloud iam roles undelete myCompanyAdmin --organization=123456789012
ロールの削除が正常に取り消された場合、コマンドの出力は次のようになります。
description: My custom role description. etag: BwVkCAx9W6w= includedPermissions: - iam.roles.get - iam.roles.list name: organization/123456789012/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
次の例は、プロジェクト レベルのカスタムロールの削除を取り消す方法を示しています。
gcloud iam roles undelete myCompanyAdmin --project=my-project-id
ロールの削除が正常に取り消された場合、コマンドの出力は次のようになります。
description: My custom role description. etag: BwVkCAx9W6w= includedPermissions: - iam.roles.get - iam.roles.list name: projects/my-project-id/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
REST
roles.undelete
メソッドを使用すると、プロジェクトまたは組織内のカスタムロールの削除を取り消すことができます。
リクエストのデータを使用する前に、次のように置き換えます。
role-name
:organizations/
、projects/
、roles/
のいずれかの接頭辞を含む完全なロール名。たとえば、organizations/123456789012/roles/myCompanyAdmin
。etag
: ロールのバージョンの識別子。他のロールの変更を上書きしないようにするには、このフィールドを指定します。
HTTP メソッドと URL:
POST https://iam.googleapis.com/v1/full-role-id:undelete
JSON 本文のリクエスト:
{ "etag": "etag" }
リクエストを送信するには、次のいずれかのオプションを展開します。
レスポンスには、削除を取り消したロールの定義が含まれます。
{ "name": "projects/my-project/roles/myCompanyAdmin", "title": "My Company Admin", "description": "My custom role description.", "includedPermissions": [ "iam.roles.get", "iam.roles.list" ], "etag": "BwWiPg2fmDE=" }
C++
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM C++ API のリファレンス ドキュメントをご覧ください。
C#
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM C# API のリファレンス ドキュメントをご覧ください。
Go
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM Go API のリファレンス ドキュメントをご覧ください。
Python
IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM Python API のリファレンス ドキュメントをご覧ください。
次のステップ
- プリンシパルにロールを付与する方法を確認する。
- ロールの推奨事項を使用してプリンシパルの権限の範囲を限定する方法を確認する。
- 特定の条件を満たす場合にのみロールを付与する条件付きロールの付与について学習する。