このページでは、カスタムロールを作成および管理する方法について説明します。
始める前に
- カスタムロールの作成に必要な権限とベスト プラクティスに関する情報を含む IAM のカスタムロールについてをお読みください。
gcloud
コマンドライン ユーティリティを使用する場合は、バージョン 188.0.0 以降を使用していることを確認してください。gcloud
をバージョン 188.0.0 に更新するには、gcloud components update --version 188.0.0
コマンドを実行します。
リソースで使用可能な権限の表示
カスタムロールを作成する前に、リソースに適用できる権限を確認する必要がある場合があります。リソースとその下位にあるリソースに適用可能な権限を確認するには、gcloud
コマンドライン ツール、Google Cloud Console または Identity and Access Management API を使用します。たとえば、組織と組織内のプロジェクトに適用できるすべての権限を確認できます。
Console
Cloud Console で、[ロール] ページに移動します。
ページの上部にあるプルダウンからプロジェクトを選択します。
リソースの管理者ロールのチェックボックスを選択して、このリソースに適用可能なすべての権限を表示します。たとえば、Compute インスタンス管理者ロールを選択すると、Compute Engine インスタンスに適用可能なすべての権限が右側のパネルに表示されます。
gcloud
gcloud iam list-testable-permissions
コマンドを使用して、対象のリソースに適用可能な権限のリストを取得します。返される権限は、このリソースおよび階層内でそれより下のリソースに対してカスタムロールを作成するのに使用できる権限です。
次の例では、プロジェクト リソースに対してテスト可能な権限を一覧表示する方法を示します。
gcloud iam list-testable-permissions project-id
project-id
はプロジェクトの ID です。リソース名の完全名(//cloudresourcemanager.googleapis.com/projects/project-id
)の形式で指定します。(例: //cloudresourcemanager.googleapis.com/projects/my-project-id
)
list-testable-permissions
コマンドから何百もの結果が返されることがあります。結果数を制限するために、フィルタ式を指定することもできます。次に、結果が短縮された例を示します。
---
name: appengine.applications.create
stage: GA
---
customRolesSupportLevel: TESTING
name: appengine.applications.disable
stage: GA
---
name: appengine.applications.get
stage: GA
---
customRolesSupportLevel: NOT_SUPPORTED
name: appengine.applications.list
onlyInPredefinedRoles: true
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" }
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "permissions": [ { "name": "iam.serviceAccountKeys.create", "stage": "GA" }, { "name": "iam.serviceAccountKeys.delete", "stage": "GA" }, { "name": "iam.serviceAccountKeys.get", "stage": "GA" } ], "nextPageToken": "CgoHBajEfjUDQyABEPaIv5vIiMDTVhgDIhtpYW0uc2VydmljZUFjY291bnRLZXlzLmxpc3Q" }
C#
このサンプルを試す前に、IAM クイックスタート: クライアント ライブラリの使用の C# の設定手順を実施してください。詳細については、IAM C# API のリファレンス ドキュメントをご覧ください。
Go
このサンプルを試す前に、IAM クイックスタート: クライアント ライブラリの使用の Go の手順に従って設定を行ってください。詳細については、IAM Go API のリファレンス ドキュメントをご覧ください。
Python
このサンプルを試す前に、IAM クイックスタート: クライアント ライブラリの使用の Python の手順に従って設定を行ってください。詳細については、IAM Python API のリファレンス ドキュメントをご覧ください。
ロール メタデータの取得
カスタムロールを作成する前に、事前定義ロールとカスタムロールの両方のメタデータを取得する必要がある場合があります。ロール メタデータには、そのロールの ID と権限が含まれます。メタデータを表示するには、Cloud Console または IAM API を使用します。
ロール メタデータを表示するには、次のいずれかの方法で行います。
Console
Cloud Console で、[ロール] ページに移動します。
ページの上部にあるプルダウン リストから組織またはプロジェクトを選択します。
1 つ以上のロールのチェックボックスを選択して、ロールの権限を表示します。ロールに含まれている権限があれば、右側のパネルに表示されます。
タイプ列のアイコンは、カスタムロール
か、事前定義ロール かを示しています。
特定の権限を含むロールをすべて検索するには、[ロール] リストの上部にある [フィルタ] ボックスに権限名を入力します。
gcloud
gcloud iam roles describe
コマンドを使用して、事前定義ロールとカスタムロールのメタデータを表示します。
事前定義ロールのメタデータを表示するには、gcloud
コマンドを実行します。
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
コマンドを実行します。
組織レベルで作成されたカスタムロールのメタデータを表示するには、次のコマンドを実行します。
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
メソッドはロールの定義を取得します。
後述のリクエストのデータを使用する前に、次のように置き換えます。
-
full-role-id
:organizations/
、projects/
、またはroles/
接頭辞を含む完全なロール ID。例: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 クイックスタート: クライアント ライブラリの使用の C# の設定手順を実施してください。詳細については、IAM C# API のリファレンス ドキュメントをご覧ください。
Go
このサンプルを試す前に、IAM クイックスタート: クライアント ライブラリの使用の Go の手順に従って設定を行ってください。詳細については、IAM Go API のリファレンス ドキュメントをご覧ください。
Python
このサンプルを試す前に、IAM クイックスタート: クライアント ライブラリの使用の Python の手順に従って設定を行ってください。詳細については、IAM Python API のリファレンス ドキュメントをご覧ください。
カスタムロールの作成
カスタムロールは、プロジェクト レベルまたは組織レベルで作成できます。
カスタムロールを作成するには、呼び出し元が iam.roles.create
権限を所有している必要があります。デフォルトでは、プロジェクトや組織のオーナーがこの権限を持ち、カスタムロールを作成および管理できます。
オーナー以外のユーザー(組織管理者を含む)には、組織ロールの管理者ロールまたは IAM ロールの管理者ロールのいずれかを割り当てる必要があります。
カスタムロールのタイトル、説明、権限名の合計サイズは 64 KB に制限されています。より大きなカスタムロールを作成する必要がある場合は、権限を複数のカスタムロールに分割できます。Custom
Admin (1 of 2)
や Custom Admin (2 of 2)
など、カスタムロール間の関係を示すロールタイトルを選択します。
Console
最初から新しいカスタムロールを作成するには:
Cloud Console で、[ロール] ページに移動します。
ページの上部にあるプルダウン リストを使用して、ロールを作成する組織またはプロジェクトを選択します。
[ロールの作成] をクリックします。
ロールの [名前]、[タイトル]、[説明] を入力します。
[権限を追加] をクリックします。
ロールに含める権限を選択し、[権限を追加] をクリックします。[すべてのサービス] と [すべてのタイプ] プルダウンを使用して、サービスとタイプ別に権限をフィルタリングして選択します。
既存のキュレートされたロールに基づいてカスタムロールを作成するには:
- Cloud Console で、[ロール] ページに移動します。
- ロールを作成する組織またはプロジェクトを選択します。
- 新しいカスタムロールのベースにするロールを選択します。
- [選択からロールを作成] をクリックします。
- ロールの [名前]、[タイトル]、[説明] を入力します。
- ロールから除外する権限のチェックボックスをオフにします。
- [権限を追加] をクリックして権限を追加します。
- [作成] をクリックします。
gcloud
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。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 クイックスタート: クライアント ライブラリの使用の C# の設定手順を実施してください。詳細については、IAM C# API のリファレンス ドキュメントをご覧ください。
Go
このサンプルを試す前に、IAM クイックスタート: クライアント ライブラリの使用の Go の手順に従って設定を行ってください。詳細については、IAM Go API のリファレンス ドキュメントをご覧ください。
Python
このサンプルを試す前に、IAM クイックスタート: クライアント ライブラリの使用の Python の手順に従って設定を行ってください。詳細については、IAM Python API のリファレンス ドキュメントをご覧ください。
既存のカスタムロールの編集
読み取り-修正-書き込み
カスタムロールなどのリソースのメタデータの更新では、一般にリソースの現在の状態の読み取り、ローカルでのデータの更新、変更されたデータの送信と書き込みが行われます。このような処理では、2 つ以上の独立したプロセスが一連の操作を同時に試行する場合に競合が発生することがあります。たとえば、プロジェクトの 2 人のオーナーが、1 つのロールに対して相反する変更を同時に行うと、一部の変更が失敗する可能性があります。IAM では、カスタムロールの etag
プロパティを使用してこの問題を解決します。このプロパティは、カスタムロールが最後のリクエスト以降に変更されているかどうかを確認するために使用されます。etag 値を使用して IAM にリクエストを送信すると、IAM はリクエスト内の etag 値をカスタムロールに関連付けられた既存の etag 値と比較します。etag 値が一致した場合にのみ変更を書き込みます。
ロールを更新する場合は、roles.get()
でロールを取得して更新します。その後、roles.patch()
を使用して、更新されたロールを書き込みます。ロールを設定するときに etag 値を使用するのは、roles.get()
内の対応するロールに etag 値が含まれている場合のみです。
Console
Cloud Console で、[ロール] ページに移動します。
ページの上部にあるプルダウン リストを使用して、編集するロールを含むプロジェクトまたは組織を選択します。
カスタムロールをクリックします。
[ロールを編集] をクリックします。
ロールに新しい権限を追加するには、[権限を追加] をクリックします。
ロールから権限を削除する権限のチェックボックスをオフにします。
[更新] をクリックして、編集したロールを保存します。
gcloud
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: full-role-id stage: launch-stage title: role-title
各プレースホルダ値についての説明は次のとおりです。
role-description
は、ロールに関する簡単な説明です("My custom role description"
など)。etag-value
は、ロールの現在のバージョンの一意の識別子です(BwVkBkbfr70=
など)。permission-1
とpermission-2
は、iam.roles.get
などのカスタムロールに含める権限です。full-role-id
は、organizations/
、projects/
、またはroles/
接頭辞を含む完全なロール ID です。(例: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。-
full-role-id
:organizations/
、projects/
、またはroles/
接頭辞を含む完全なロール ID。例: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 クイックスタート: クライアント ライブラリの使用の C# の設定手順を実施してください。詳細については、IAM C# API のリファレンス ドキュメントをご覧ください。
Go
このサンプルを試す前に、IAM クイックスタート: クライアント ライブラリの使用の Go の手順に従って設定を行ってください。詳細については、IAM Go API のリファレンス ドキュメントをご覧ください。
Python
このサンプルを試す前に、IAM クイックスタート: クライアント ライブラリの使用の Python の手順に従って設定を行ってください。詳細については、IAM Python API のリファレンス ドキュメントをご覧ください。
カスタムロールの無効化
カスタムロールを無効にできます。ロールを無効にすると、そのロールに関連するポリシー バインディングはすべて無効になります。つまり、ユーザーにロールを付与しても効果はありません。
Console
Cloud Console で、[ロール] ページに移動します。
ページの上部にある [プロジェクトを選択] プルダウンをクリックします。
組織またはプロジェクトを選択します。
カスタムロールを選択し、[無効] をクリックします。
gcloud
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。-
full-role-id
:organizations/
、projects/
、またはroles/
接頭辞を含む完全なロール ID。例: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
に更新します。
Go
ロールの stage
フィールドを DISABLED
に更新します。
Python
ロールの stage
フィールドを DISABLED
に更新します。
ロールの一覧表示
プロジェクトまたは組織で作成されたすべてのカスタムロールを一覧表示できます。
Console
Cloud Console で、[ロール] ページに移動します。
選択した組織またはプロジェクトのすべてのカスタムロールが一覧表示されます。
gcloud
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
コマンドを実行して、事前定義ロールを一覧表示します。
gcloud iam roles list
REST
roles.list
メソッドを使用すると、プロジェクトまたは組織内のすべてのカスタムロールを一覧表示できます。
後述のリクエストのデータを使用する前に、次のように置き換えます。
resource-type
: カスタムロールを管理するリソースタイプ。値projects
またはorganizations
を使用します。resource-id
: カスタムロールを管理するプロジェクト ID または組織 ID。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 クイックスタート: クライアント ライブラリの使用の C# の設定手順を実施してください。詳細については、IAM C# API のリファレンス ドキュメントをご覧ください。
Go
このサンプルを試す前に、IAM クイックスタート: クライアント ライブラリの使用の Go の手順に従って設定を行ってください。詳細については、IAM Go API のリファレンス ドキュメントをご覧ください。
Python
このサンプルを試す前に、IAM クイックスタート: クライアント ライブラリの使用の Python の手順に従って設定を行ってください。詳細については、IAM Python API のリファレンス ドキュメントをご覧ください。
カスタムロールの削除
プロジェクトまたは組織内のカスタムロールを削除できます。
Console
Cloud Console で、[ロール] ページに移動します。
削除するロールを選択して、ページの上部にある delete(削除)をクリックします。
gcloud
gcloud iam roles delete
コマンドを使用して、カスタムロールを削除します。ロールは停止され、新しい IAM ポリシー バインディングの作成には使用できません。
カスタムロールを削除するには、次のいずれかのコマンドを実行します。
組織レベルのカスタムロールを削除するには、次のコマンドを実行します。
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
メソッドを使用すると、プロジェクトまたは組織内のカスタムロールを削除できます。
後述のリクエストのデータを使用する前に、次のように置き換えます。
-
full-role-id
:organizations/
、projects/
、またはroles/
接頭辞を含む完全なロール ID。例: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 クイックスタート: クライアント ライブラリの使用の C# の設定手順を実施してください。詳細については、IAM C# API のリファレンス ドキュメントをご覧ください。
Go
このサンプルを試す前に、IAM クイックスタート: クライアント ライブラリの使用の Go の手順に従って設定を行ってください。詳細については、IAM Go API のリファレンス ドキュメントをご覧ください。
Python
このサンプルを試す前に、IAM クイックスタート: クライアント ライブラリの使用の Python の手順に従って設定を行ってください。詳細については、IAM Python API のリファレンス ドキュメントをご覧ください。
ロールが削除されると、そのバインディングは残りますが、非アクティブです。ロールは 7 日以内であれば削除を取り消すことができます。この 7 日間、ロールは Cloud Console で [削除済み] と表示され、プログラムの list
コマンドでは表示されません(リクエストで showDeleted
が設定されている場合を除く)。
ロールは 7 日後に完全削除が予定されます。この時点で、ロールは組織あたり 300 個のカスタムロールまたはプロジェクトあたり 300 個のカスタムロールの上限にカウントされなくなります。
完全に削除するには 30 日かかります。この 30 日間の間に、ロールと、そのロールに関連付けられているすべてのバインディングが完全に削除されます。同じロール ID を使用して新しいロールを作成することはできません。
最初の削除リクエストの 37 日後にロールが完全に削除された後は、同じロール ID を使用して新しいロールを作成できるようになります。
カスタムロールの削除の取り消し
ロールの削除を取り消すと、以前の状態に戻ります。
ロールの削除は、削除から 7 日以内に限って取り消すことができます。7 日が経過すると、ロールは完全に削除され、ロールに関連付けられたすべてのバインドが除去されます。
Console
Cloud Console で、[ロール] ページに移動します。
削除を取り消すロールを見つけ、行の最後にあるその他アイコンをクリックして [削除を取り消す] をクリックします。
gcloud
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
メソッドを使用すると、プロジェクトまたは組織内のカスタムロールの削除を取り消すことができます。
後述のリクエストのデータを使用する前に、次のように置き換えます。
-
full-role-id
:organizations/
、projects/
、またはroles/
接頭辞を含む完全なロール ID。例: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 クイックスタート: クライアント ライブラリの使用の C# の設定手順を実施してください。詳細については、IAM C# API のリファレンス ドキュメントをご覧ください。
Go
このサンプルを試す前に、IAM クイックスタート: クライアント ライブラリの使用の Go の手順に従って設定を行ってください。詳細については、IAM Go API のリファレンス ドキュメントをご覧ください。
Python
このサンプルを試す前に、IAM クイックスタート: クライアント ライブラリの使用の Python の手順に従って設定を行ってください。詳細については、IAM Python API のリファレンス ドキュメントをご覧ください。
次のステップ
- メンバーにロールを付与する方法を確認する。
- 特定の条件を満たす場合にのみロールを付与する条件付きロールの付与について学習する。