このページでは、カスタムの役割を作成し、管理する方法について説明します。
始める前に
- カスタムの役割の作成に必要な権限とベスト プラクティスに関する情報を含む IAM のカスタムの役割についてをお読みください。
リソースで使用可能な権限の表示
カスタムの役割を作成する前に、リソースに適用できる権限を確認したい場合があります。Cloud Console または IAM API を使用して、リソースに適用できるすべての権限とその下の階層に含まれるリソースを取得できます。たとえば、組織とその組織のプロジェクトに適用できるすべての権限を取得できます。
Console
- GCP Console の [役割] ページに移動します。
- ページの上部にあるプルダウンからプロジェクトを選択します。
- リソースの管理者役割のチェックボックスを選択して、このリソースに適用可能な権限を表示します。たとえば、Compute インスタンス管理者役割を選択すると、Compute Engine インスタンスに適用可能なすべての権限が右側のパネルに表示されます。
API
QueryTestablePermissions は、リソースに適用できるすべての権限を返します。返される権限は、このリソースおよびその下の階層内のリソースでカスタムの役割を作成するのに使用できる権限です。このリクエストには、//cloudresourcemanager.googleapis.com/projects/my-project のように完全なリソース名のみを入力します。
リソースに権限の長いリストが含まれる場合、呼び出し元は、必要に応じてページ設定のサポートを提供できます。
例
full_resource_name: '//cloudresourcemanager.googleapis.com/projects/my-project/buckets/bucket1'`
エラーコード
| エラーコード | ステータス メッセージ |
|---|---|
INVALID_ARGUMENT | 0〜100 の値にする必要があります。 |
INVALID_ARGUMENT | ページ設定トークンのエンコードが無効です。 |
INVALID_ARGUMENT | ページ設定トークンが無効です。 |
INVALID_ARGUMENT | ページ設定トークンが、指定されたコンテナ用ではありません。 |
INVALID_ARGUMENT | ページ設定トークンの開始点が無効です。 |
INVALID_ARGUMENT | ページ設定トークンの Cookie が無効です。 |
INVALID_ARGUMENT | ページ設定トークンの期限が切れています。 |
INVALID_ARGUMENT | {full_resource_name} を指定する必要があります。 |
INVALID_ARGUMENT | {full_resource_name} が //[a-z0-9.-]/.a-z0-9.-]/ と一致しません。 |
役割メタデータの取得
カスタムの役割を作成する前に、事前定義済みの役割とカスタムの役割の両方のメタデータを取得したい場合があります。役割メタデータには、その役割の ID と権限が含まれます。メタデータを表示するには、Google Cloud Platform Console または IAM API を使用します。
役割メタデータを表示するには、次のいずれかの方法で行います。
Console
- GCP Console の [役割] ページに移動します。
- ページの上部にあるプルダウンから組織またはプロジェクトを選択します。
- 1 つ以上の役割のチェックボックスを選択して、役割の権限を表示します。役割に含まれている権限があれば、右側のパネルに表示されます。
役割の横にあるアイコンは役割の種類を表します。カスタム役割の場合には、工場のアイコンが、事前定義済み役割の場合には六角形のアイコンが表示されます。
特定の権限に含まれる役割をすべて検索するには、[役割] リストの上部にある [フィルタ] ボックスに権限名を入力します。
API
表示する役割の役割名がわかっている場合は、roles.get メソッドを使用してカスタムの役割を取得します。役割名がわからない場合は、roles.list メソッドを使用して、組織やプロジェクト内のすべてのカスタムの役割を一覧表示します。
GetRole(), を呼び出すには、GetRoleRequest に次のフィールドを設定します。
roles/{ROLE_NAME}やorganizations/{ORGANIZATION_ID}/roles/{ROLE_NAME}などの役割の名前。
ListRoles() を呼び出すには、次のフィールドを ListRolesRequest に設定します。
organizations/{ORGANIZATION_ID}やprojects/{PROJECT_ID}など、すべてのカスタムの役割を取得する親。
エラーコード
| エラーコード | ステータス メッセージ |
|---|---|
PERMISSION_DENIED | {path} で役割を取得する権限がありません。 |
NOT_FOUND | {role} という名前の役割が見つかりませんでした。 |
INVALID_ARGUMENT | 役割名は roles/{role}、または organizations/{organization_id}/roles/{role} の形式である必要があります。 |
PERMISSION_DENIED | {path} の役割を一覧表示する権限がありません。 |
INVALID_ARGUMENT | 親 {path} が無効です。親は organizations/{organization_id} の形式か空である必要があります。 |
INVALID_ARGUMENT | 役割ビューが無効です。 |
カスタムの役割の作成
カスタムの役割を作成するには、呼び出し元に iam.roles.create 権限が必要です。デフォルトでは、プロジェクトや組織のオーナーがこの権限を持ち、カスタムの役割を作成し、管理できます。
オーナー以外のユーザー（組織管理者を含む）には、組織の役割の管理者の役割または IAM 役割の管理者の役割のいずれかを割り当てる必要があります。
Console
新しいカスタムの役割を最初から作成するには:
- GCP Console の [役割] ページに移動します。
- [組織] プルダウンから組織を選択します。
- [役割の作成] をクリックします。
- 役割の [名前]、[タイトル]、[説明] を入力します。
- [権限を追加] をクリックします。
- 役割に含める権限を選択し、[権限を追加] をクリックします。[すべてのサービス] と [すべてのタイプ] プルダウンを使用して、サービスとタイプ別に権限をフィルタリングして選択します。
既存のキュレートされた役割に基づいてカスタムの役割を作成するには:
- GCP Console の [役割] ページに移動します。
- [組織] プルダウンから組織を選択します。
- 新しいカスタムの役割を作成する基礎となる役割を選択します。
- [選択から役割を作成] をクリックします。
- 役割の [名前]、[タイトル]、[説明] を入力します。
- 役割から除外する権限のチェックボックスをオフにします。
- [権限を追加] をクリックして権限を追加します。
- [作成] をクリックします。
API
新しいカスタムの役割を作成するには、create メソッドを使用します。
リクエストに次の必須パラメータを設定します。
- 新しいカスタムの役割に使用する role_id（
appengine.myCustomStorageAuditorなど）。 - 「この役割は、ストレージ リソース、その容量、アクセス ポリシーを一覧表示できるよう権限を付与します」といったカスタムの役割の説明。
- この役割に関連付ける権限のリスト。
- 役割に名前フィールドを設定すると、エラーが発生することに注意してください。
次のオプション パラメータも設定することをおすすめします。
- 「カスタムの役割編集者の例」などのカスタムの役割のタイトル。
stageの値をGAなどに設定します。
stage は、ALPHA、BETA、GA、DEPRECATED、DISABLED のいずれかの値をとります。
一部の事前定義済みの役割には、サポートが終了した権限や、カスタムの役割では許可されない権限が含まれています。サポートが終了した権限や制限された権限を含む事前定義済みの役割に基づくカスタムの役割の作成は失敗します。
例
parent: '[PARENT_NAME]'
role_id: '[ROLE_ID]'
role {
name: ''
title: '[ROLE_TITLE]'
description: '[ROLE_DESCRIPTION]'
included_permissions: '[PERMISSION]'
included_permissions: '[PERMISSION]'
})",
ここで:
[PARENT_NAME]は、カスタムの役割を作成する組織の名前（organizations/0000000000000001など）か、カスタムの役割を作成するプロジェクト ID（projects/my-projectなど）です。[ROLE_ID]はカスタムの役割の ID です。例:appengine.myCustomStorageAuditor.[ROLE_TITLE]は役割のタイトルです。例:Storage Auditor[ROLE_DESCRIPTION]は、役割の果たす内容の説明です。[PERMISSION]は、カスタムの役割に含める権限です。
エラーコード
| エラーコード | ステータス メッセージ |
|---|---|
PERMISSION_DENIED | {parent} で役割を作成する権限がありません。 |
ALREADY_EXISTS | {parent} に {role_id} という名前の役割がすでに存在します。 |
INVALID_ARGUMENT | 親 {parent} が無効です。親は organizations/{organization_id} の形式である必要があります。 |
INVALID_ARGUMENT | role_id {role_id} は無効です。パターン {pattern} と一致しません。 |
INVALID_ARGUMENT | 役割内の権限の数が {max} の最大数を超えています。 |
INVALID_ARGUMENT | role.stage {stage} が無効です。 |
既存のカスタムの役割の編集
Read-Modify-Write
カスタムの役割などのリソースのメタデータの更新では一般に、リソースの現在の状態の読み取り、ローカルでのデータの更新、変更されたデータの送信と書き込みが行われます。このような処理は、2 つ以上の独立したプロセスが一連の操作を同時に試行する場合に競合を引き起こすことがあります。たとえば、プロジェクトの 2 人のオーナーが、1 つの役割に対して相反する変更を同時に行うと、一部の変更が失敗する可能性があります。Cloud IAM では、この問題をカスタムの役割の etag プロパティを使用して解決します。このプロパティは、カスタムの役割が最後のリクエスト以降に変更されているかどうかを確認するために使用されます。etag 値を保持している Cloud IAM にリクエストを出すと、Cloud IAM はリクエスト内の etag 値と、カスタムの役割に関連付けられている既存の etag 値を比較します。etag 値が一致した場合にのみ変更を書き込みます。
役割を更新するときには、最初に roles.get() を使用して役割を取得し、役割を更新してから roles.patch() を使用してその更新した役割を書き込みます。役割を設定するときに etag 値を使用するのは、roles.get() 内の対応する役割に etag 値が含まれている場合のみです。
Console
- GCP Console の [役割] ページに移動します。
- [組織] プルダウンから組織を選択します。
- カスタムの役割をクリックします。
- [役割を編集] をクリックします。
- 役割に新しい権限を追加するには、[権限を追加] をクリックします。
- 役割から権限を削除する権限のチェックボックスをオフにします。
- [更新] をクリックして、編集した役割を保存します。
API
既存のカスタムの役割を編集するには、Role UpdateRole(UpdateRoleRequest) メソッドを使用します。
編集するカスタムの役割の役割 ID がわかっている場合は、roles.get() メソッドを使用して役割を取得し、roles.patch() を使用して役割を更新します。
編集するカスタムの役割の役割 ID がわからない場合は、ListRoles() を使用してすべての役割を一覧表示し、役割を識別します。roles.list() は、リソースを参照するすべての役割の一覧を返します。次に、roles.patch() を使用して役割を更新します。
roles.patch() で次の必須パラメータを設定します。
organizations/{ORGANIZATION_ID}/roles/{ROLE_ID}などの役割の名前。
必要に応じて update_mask フィールドを設定し、将来更新できるフィールドを指定します。
例
name: '[ROLE_NAME]'
role {
name: '[ROLE_NAME]'
title: '[ROLE_TITLE]'`
description: '[ROLE_DESCRIPTION]'
included_permissions: '[PERMISSION]'
included_permissions: '[PERMISSION]'
})"
ここで、
[ROLE_NAME]は役割の名前です。例:organizations/123456/roles/appengine.customRoleEditor.形式はroles/{ROLE_NAME}、organizations/{ORGANIZATION_ID}/roles/{ROLE_NAME}、projects/{PROJECT_ID}/roles/{ROLE_NAME}のいずれかです。
注: 役割の中にある [ROLE_NAME] は空のままにすることをおすすめします。2 つの名前が同じでなく、役割内の名前が空でない場合、メソッドはエラーを返します。
[ROLE_TITLE]は役割のタイトルです。例:New custom editor.[ROLE_DESCRIPTION]は役割の説明です。例: 「編集者の新しい詳細な説明」。[PERMISSION]は役割に含める権限です。例:storage.objects.update
エラーコード
| エラーコード | ステータス メッセージ |
|---|---|
PERMISSION_DENIED | 役割を更新する権限がありません。 |
INVALID_ARGUMENT | 定義済みの役割は更新できません。 |
INVALID_ARGUMENT | リクエスト内の名前（[ROLE_NAME]）と役割内の名前（[ROLE_NAME]）は一致する必要があります。 |
INVALID_ARGUMENT | 権限 [PERMISSION] が無効です。 |
ABORTED | etag が一致しなかったため、同時ポリシーが変更されました。読み取り-修正-書き込み全体を指数バックオフで再試行してください。 |
一部の事前定義済みの役割には、サポートが終了した権限や、カスタムの役割では許可されない権限が含まれています。サポートが終了した権限や制限された権限を含む事前定義済みの役割に基づくカスタムの役割の作成は失敗します。
カスタムの役割の無効化
カスタムの役割を無効にすることができます。役割を無効にすると、その役割に関連するポリシー バインディングはすべて無効になります。つまり、ユーザーに役割を付与しても、その役割の権限は付与されません。
Console
- GCP Console の [役割] ページに移動します。
- ページの上部にある [プロジェクトを選択] プルダウンをクリックします。
- 組織またはプロジェクトを選択します。
- カスタムの役割を選択し、[無効] をクリックします。
API
カスタムの役割を無効にするには roles.patch() メソッドを使用します。
無効にするカスタムの役割の役割 ID がわかっている場合は、roles.get() メソッドを使用して役割を取得します。役割の stage プロパティを DISABLED に変更し、roles.patch() メソッドを呼び出して役割を更新します。
無効にするカスタムの役割の ID がわからない場合は、roles.list() を使用してすべての役割を一覧表示し、役割を見つけます。roles.list() は、リソースを参照するすべての役割のリストを返します。無効にする役割を特定し、その rolelaunchstage プロパティを DISABLED, に変更してから、roles.patch() メソッドを呼び出して役割を更新します。
役割を無効にするには、次のフィールドを設定します。
- 名前を役割のフルネームに設定します（
organizations/{organization-id}/roles/{role}.）。 Role,でstageをDISABLED.に設定します。update_maskを「paths: stage」に設定します。
役割を再度有効にするには、上記の役割の無効化と同じプロセスを行いますが、役割の stage プロパティを ALPHA、BETA、GA のいずれかに設定します。
例
name: 'organizations/123456/roles/appengine.customRoleEditor'
role {
name: 'organizations/123456/roles/appengine.customRoleEditor'`
stage: 'DISABLED'
}
update_mask {
paths: stage
}
エラーコード
| エラーコード | ステータス メッセージ |
|---|---|
PERMISSION_DENIED | 役割を更新する権限がありません。 |
INVALID_ARGUMENT | キュレートされた役割を更新できません。 |
INVALID_ARGUMENT | リクエスト内の名前（[ROLE_NAME]）と役割内の名前（[ROLE_NAME]）は一致する必要があります。 |
INVALID_ARGUMENT | 権限 [PERMISSION] が無効です。 |
ABORTED | 同時ポリシーが変更されました。読み取り-修正-書き込みを指数バックオフで再試行してください。 |
役割の一覧表示
Console
- GCP Console の [役割] ページに移動します。
プロジェクトのすべてのカスタムの役割がページに一覧表示されます。
API
組織やプロジェクトで定義されているすべてのカスタム役割を一覧表示するには、roles.list() メソッドを使用します。また、このメソッドを使用し、リクエストの親フィールドを "" に設定することで、事前定義済みの役割を一覧表示することもできます。
roles.list() を呼び出すには、リクエストに次のフィールドを設定します。
- すべてのカスタムの役割を取得するために使用する次のような親。
projects/{PROJECT_ID}organizations/{ORGANIZATION_ID}
結果に各役割の権限が含まれるようにするには、view フィールドを RoleView::FULL に設定します。
結果に最近削除された役割を含めるには、show_deleted フィールドを true に設定します。
すべてのキュレートされた役割の一覧を表示する場合は、親を ''（空文字列）に設定します。
エラーコード
| エラーコード | ステータス メッセージ |
|---|---|
PERMISSION_DENIED | {path} の役割を一覧表示する権限がありません。 |
INVALID_ARGUMENT | 親 {path} が無効です。親は organizations/{organization_id}、projects/{project_id} の形式か空である必要があります。 |
INVALID_ARGUMENT | 役割ビューが無効です。 |
リソースに対して付与可能な役割の表示
Console
- GCP Console で [IAM] ページを開きます。
- ページの上部にある [プロジェクトを選択] プルダウンをクリックします。
- 役割を表示するプロジェクトまたは組織を選択します。
- [追加] をクリックします。
- [メンバー] にメンバーのメールアドレスを入力します。
[役割] プルダウンには、メンバーに付与できるすべての役割（カスタムの役割を含む）が表示されます。
API
QueryGrantableRoles は、リソースが参照できるすべての役割のリストを返します。権限のない役割は含まれません。リクエストに必要なパラメータは、完全なリソース名だけです（たとえば //cloudresourcemanager.googleapis.com/projects/my-project）。必要に応じて、呼び出し元は RoleView を提供できます。これは、役割に含まれるすべての権限をレスポンスで Role に含めるかどうかを判別します。
例
full_resource_name: '//automatedtests.googleapis.com/projects/my-project/buckets/bucket1'`
エラーコード
| エラーコード | ステータス メッセージ |
|---|---|
INVALID_ARGUMENT | {full_resource_name} を指定する必要があります。 |
INVALID_ARGUMENT | {full_resource_name} が //[a-z0-9.-]/ と一致しません。 |
カスタムの役割の削除
Console
- GCP Console の [役割] ページに移動します。
- 削除する役割を選択し、ページ上部のゴミ箱アイコンをクリックします。
役割は停止され、新しい IAM ポリシー バインドの作成には使用できません。既存のバインドは残りますが、非アクティブです。役割は 7 日以内であれば削除を取り消すことができます。7 日間が経過した後、役割の完全削除プロセスが開始され、これが 30 日間続きます。
このプロセスでは、役割と、その役割に関連付けられているすべてのバインディングが完全に削除されます。同じ役割 ID を使用して新しい役割を作成することはできません。役割が完全に削除されるまでには、最初の削除リクエストから 37 日かかります。削除後に、削除された役割の ID を使用して新しい役割を作成できます。
API
roles.delete は役割を削除します。役割は停止され、新しい IAM ポリシー バインドの作成には使用できません。
name の形式は次のとおりです。
organizations/{ORGANIZATION_ID}/roles/{ROLE_NAME}projects/{PROJECT_ID}/roles/{ROLE_NAME}
リクエストに show_deleted が設定されていない限り、役割は list に含まれません。役割がこの状態にある場合、役割には true に設定された deleted ブール値が含まれます。
既存のバインドは残りますが、非アクティブです。役割は 7 日以内であれば削除を取り消すことができます。7 日間が経過した後、役割の完全削除プロセスが開始され、これが 30 日間続きます。
このプロセスでは、役割と、その役割に関連付けられているすべてのバインディングが完全に削除されます。同じ役割 ID を使用して新しい役割を作成することはできません。役割が完全に削除されるまでには、最初の削除リクエストから 37 日かかります。削除後に、削除された役割の ID を使用して新しい役割を作成できます。
エラーコード
| エラーコード | ステータス メッセージ |
|---|---|
PERMISSION_DENIED | {path} で役割を削除する権限がありません。 |
FAILED_PRECONDITION | すでに削除されているため、{ROLE_NAME} は削除できません。 |
FAILED_PRECONDITION | 役割 {ROLE_NAME} は予約されているため削除できません。 |
INVALID_ARGUMENT | キュレートされた役割は削除状態にはできません。 |
カスタムの役割の削除の取り消し
Console
- GCP Console の [役割] ページに移動します。
- 削除を取り消す役割を見つけ、行の最後にあるその他アイコンをクリックして [削除を取り消す] をクリックします。
役割の削除は、削除から 7 日以内に限って取り消すことができます。7 日が経過すると、役割は完全に削除され、役割に関連付けられたすべてのバインドが除去されます。
API
roles.undelete は役割を以前の状態に戻します。
name の形式は次のとおりです。
organizations/{ORGANIZATION_ID}/roles/{ROLE_NAME}projects/{PROJECT_ID}/roles/{ROLE_NAME}
役割の削除は、削除から 7 日以内に限って取り消すことができます。7 日が経過すると、役割は完全に削除され、役割に関連付けられたすべてのバインドが除去されます。
エラーコード
| エラーコード | ステータス メッセージ |
|---|---|
PERMISSION_DENIED | {path} での役割の削除を取り消す権限がありません。 |
FAILED_PRECONDITION | 削除されていない役割の削除を取り消すことはできません。 |
FAILED_PRECONDITION | 予約済みの役割 {ROLE_NAME} の削除を取り消すことはできません。 |
INVALID_ARGUMENT | 定義済みの役割の削除は取り消すことはできません。 |
