Directory API を使用すると、ロールベースのアクセス制御(RBAC)を使用して、Google Workspace ドメイン内の機能へのアクセスを管理できます。権限のあるカスタムロールを作成して、Google Workspace にあらかじめ用意されているロールよりも具体的に管理者権限を制限できます。ロールは、ユーザーまたはセキュリティ グループに割り当てることができます。このガイドでは、ロール関連の基本的なタスクを実行する方法について説明します。
Directory API で Google Workspace 内の RBAC に関連して使用される一般的な用語は次のとおりです。
- 権限
- Google Workspace ドメインでタスクまたはオペレーションを実行するために必要な権限。
Privilege
リソースで表されます。このリソースに関連付けられた永続データはありません。 - ロール
- そのロールを持つエンティティに特定のタスクまたはオペレーションの実行権限を付与する権限のコレクション。
Role
リソースで表されます。 - ロールの割り当て
- ユーザーまたはグループに付与された特定のロールのレコード。
RoleAssignment
リソースで表されます。 - セキュリティ グループ
- 組織リソースへのアクセスを制御するために使用される Cloud Identity グループの一種。セキュリティ グループには、個々のユーザーとグループの両方を含めることができます。
ロールとロールの割り当て上限
作成できるカスタムロールまたはロールの割り当ては限られているため、上限に近づいている場合は、上限を超えないように統合または削除します。ロールとロールの割り当てには次の制限があります。
- 組織全体に対して最大 750 個のカスタムロールを作成できます。
- ルート組織を 1 つの組織部門と見なす組織部門(OU)ごとに、最大 500 個のロール割り当てを作成できます。たとえば、ルート組織に 350 個のロールを、会社の部門など、定義した別の OU に 400 個のロールを割り当てることができます。Google Workspace の既定の管理者ロールはすべて、デフォルトで組織全体のスコープに設定されます。詳細については、OU レベルで割り当て可能な権限の上限をご覧ください。
ロールとロールの割り当てには、グループに対して次の制限があります。
- 特権管理者以外のすべてのロールを割り当てることができます。
- 組織部門全体と各組織部門で、合計で最大 250 個のロールをグループに割り当てることができます。
- このグループは、組織内のセキュリティ グループである必要があります。
- グループ メンバーを組織内のユーザーに制限することをおすすめします。組織外のユーザーを追加できますが、ロールの権限が付与されない場合があります。詳しくは、グループ メンバーシップを制限するをご覧ください。
グループへのロールの割り当て
OU に 500 を超えるロールを割り当てる必要がある場合は、複数のメンバーをセキュリティ グループに追加して、そのグループにロールを割り当てることができます。グループのロールの割り当てには、追加の制限事項があります。詳細については、管理者用ヘルプセンターをご覧ください。
Google 管理コンソールのロールと権限のマッピング
管理コンソールから権限にアクセスするユーザーにロールを割り当てるには、特定の追加の権限を付与しなければならない場合があります。たとえば、ユーザーに管理コンソールを使用して他のユーザーを作成する権限を付与するには、USERS_CREATE
権限だけでなく、USERS_UPDATE
権限と ORGANIZATION_UNITS_RETRIEVE
権限も必要です。次の表に、管理コンソールの機能と、ユーザーと組織部門の管理に必要な権限の対応を示します。
管理コンソールの機能 | 必要な権限 |
---|---|
組織部門 - 読み取り | ORGANIZATION_UNITS_RETRIEVE |
組織部門 - 作成 | ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_CREATE |
組織部門 - 更新 | ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_UPDATE |
組織部門 - 削除 | ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_DELETE |
組織部門 | ORGANIZATION_UNITS_ALL |
ユーザー - 読み取り | USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE |
ユーザー - 作成 | USERS_CREATE 、USERS_UPDATE 、ORGANIZATION_UNITS_RETRIEVE |
ユーザー - 更新 | USERS_UPDATE + ORGANIZATION_UNITS_RETRIEVE |
ユーザー - ユーザーの移動 | USERS_MOVE 、USERS_RETRIEVE 、ORGANIZATION_UNITS_RETRIEVE |
ユーザー - ユーザー名の変更 | USERS_ALIAS 、USERS_RETRIEVE 、ORGANIZATION_UNITS_RETRIEVE |
ユーザー - パスワードの再設定 | USERS_RESET_PASSWORD 、USERS_RETRIEVE 、ORGANIZATION_UNITS_RETRIEVE |
ユーザー - パスワード変更の強制 | USERS_FORCE_PASSWORD_CHANGE 、USERS_RETRIEVE 、ORGANIZATION_UNITS_RETRIEVE |
ユーザー - エイリアスの追加と削除 | USERS_ADD_NICKNAME 、USERS_RETRIEVE 、ORGANIZATION_UNITS_RETRIEVE |
ユーザー - ユーザーの停止 | USERS_SUSPEND 、USERS_RETRIEVE 、ORGANIZATION_UNITS_RETRIEVE |
グループ | GROUPS_ALL |
セキュリティ - ユーザー セキュリティの管理 | USER_SECURITY_ALL 、USERS_RETRIEVE 、ORGANIZATION_UNITS_RETRIEVE |
ユースケースの例
始める前に
Google Workspace の認証と認可の手順を完了します。
ドメイン権限のリストを取得する
ドメインでサポートされている権限のリストをページ分けして取得するには、privileges.list()
メソッドを使用します。
独自のドメインで権限を取得する管理者の場合は、
my_customer
をお客様 ID として使用します。販売パートナーが顧客のいずれかの権限を取得する場合は、ユーザーを取得するオペレーションで返されたお客様 ID を使用します。
リクエスト
GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles/ALL/privileges
レスポンス
成功すると、HTTP 200 ステータス コードが返されます。レスポンスでは、ステータス コードとともに、ドメインでサポートされている権限が返されます。
{
"kind": "admin\#directory\#privileges",
"etag": ...,
"items": [
{
"kind": "admin\#directory\#privilege",
"etag": ...,
"serviceId": "02afmg282jiquyg",
"privilegeName": "APP_ADMIN",
"isOuScopable": false
},
{
"kind": "admin\#directory\#privilege",
"etag": ...,
"serviceId": "04f1mdlm0ki64aw",
"privilegeName": "MANAGE_USER_SETTINGS",
"isOuScopable": true,
"childPrivileges": [
{
"kind": "admin\#directory\#privilege",
"etag": ...,
"serviceId": "04f1mdlm0ki64aw",
"privilegeName": "MANAGE_APPLICATION_SETTINGS",
"isOuScopable": true
}
]
},
...
]
}
既存のロールを取得する
既存のロールのリストを取得するには、次の GET
リクエストを使用し、リクエストを承認するで説明されている承認を含めます。
独自のドメインでロールを取得する管理者の場合は、お客様 ID として
my_customer
を使用します。販売パートナーがお客様のロールを取得する場合は、ユーザーを取得するオペレーションで取得したお客様 ID を使用します。
リクエスト
GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles
レスポンス
成功すると、HTTP 200
ステータス コードが返されます。レスポンスでは、ステータス コードとともにドメインに存在するロールが返されます。
{
"kind": "admin\#directory\#roles",
"etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/DywA6_jaJCYw-f0lFs2-g17UWe8\"",
"items": [
{
"kind": "admin\#directory\#role",
"etag": ... ,
"roleId": "3894208461012993",
"roleName": "_SEED_ADMIN_ROLE",
"roleDescription": "Google Workspace Administrator Seed Role",
"rolePrivileges": [
{
"privilegeName": "SUPER_ADMIN",
"serviceId": "01ci93xb3tmzyin"
},
{
"privilegeName": "ROOT_APP_ADMIN",
"serviceId": "00haapch16h1ysv"
},
{
"privilegeName": "ADMIN_APIS_ALL",
"serviceId": "00haapch16h1ysv"
},
...
],
"isSystemRole": true,
"isSuperAdminRole": true
},
{
"kind": "admin\#directory\#role",
"etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/bTXiZXfuK1NGr_f4paosCWXuHmw\"",
"roleId": "3894208461012994",
"roleName": "_GROUPS_ADMIN_ROLE",
"roleDescription": "Groups Administrator",
"rolePrivileges": [
{
"privilegeName": "CHANGE_USER_GROUP_MEMBERSHIP",
"serviceId": "01ci93xb3tmzyin"
},
{
"privilegeName": "USERS_RETRIEVE",
"serviceId": "00haapch16h1ysv"
},
{
"privilegeName": "GROUPS_ALL",
"serviceId": "00haapch16h1ysv"
},
{
"privilegeName": "ADMIN_DASHBOARD",
"serviceId": "01ci93xb3tmzyin"
},
{
"privilegeName": "ORGANIZATION_UNITS_RETRIEVE",
"serviceId": "00haapch16h1ysv"
}
],
"isSystemRole": true
},
...
]
}
すべてのロールの割り当てを一覧表示する
直接ロールのすべての割り当てのリストをページ分けして取得するには、roleAssignments.list()
メソッドを使用します。userKey
パラメータが設定されている場合、API はページトークンとともに空の結果を返すことがあります。ページトークンが返されなくなるまでページ分割を続行する必要があります。
独自のドメインでロールの割り当てを取得する管理者の場合は、
my_customer
をお客様 ID として使用します。販売パートナーがいずれかの顧客のロール割り当てを取得する場合は、ユーザーを取得するオペレーションで返されたお客様 ID を使用します。
リクエスト
GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments
レスポンス
成功すると、HTTP 200
ステータス コードが返されます。レスポンスでは、ステータス コードとともに、ドメインに割り当てられているすべてのロールが返されます。
{
"kind": "admin\#directory\#roleAssignment",
"etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
"roleAssignmentId:"3894208461013211",
"assignedTo:"100662996240850794412",
"assigneeType:"user",
"scopeType:"CUSTOMER",
}
すべての間接ロールの割り当てを一覧表示する
すべてのロールの割り当てのリストをページ分けされたリスト(ユーザーが所属するグループによってユーザーに間接的に割り当てられたものを含む)を取得するには、roleAssignments.list()
メソッドを使用します。
API からページトークンを含む空の結果が返されることがあります。ページトークンが返されなくなるまでページ分割を続行する必要があります。
独自のドメインでロールの割り当てを取得する管理者の場合は、
my_customer
をお客様 ID として使用します。販売パートナーがいずれかの顧客のロール割り当てを取得する場合は、ユーザーを取得するオペレーションで返されたお客様 ID を使用します。
USER_KEY
は、API リクエストでユーザーを識別する値に置き換えます。詳細については、users.get
をご覧ください。
リクエスト
GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments?userKey=USER_KEY&includeIndirectRoleAssignments=true
レスポンス
成功すると、HTTP 200
ステータス コードが返されます。レスポンスでは、ステータス コードとともに、ドメインに割り当てられたすべてのロールと、assigneeType
が user
か group
かが返されます。
{
"kind": "admin\#directory\#roleAssignment",
"etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
"roleAssignmentId:"3894208461013211",
"assignedTo:"100662996240850794412",
"assigneeType:"group",
"scopeType:"CUSTOMER",
}
ロールを作成する
新しいロールを作成するには、次の POST
リクエストを使用し、リクエストを承認するで説明されている承認を含めます。このロールで付与する権限ごとに privilegeName
と serviceId
を追加します。リクエストとレスポンスのプロパティについては、API リファレンスをご覧ください。
リクエスト
POST https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles { "roleName": "My New Role", "rolePrivileges": [ { "privilegeName": "USERS_ALL", "serviceId": "00haapch16h1ysv" }, { "privilegeName": "GROUPS_ALL", "serviceId": "00haapch16h1ysv" } ] }
レスポンス
成功すると、HTTP 200
ステータス コードが返されます。レスポンスでは、ステータス コードとともに新しいロールのプロパティが返されます。
{
"kind": "admin\#directory\#role",
"etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/uX9tXw0qyijC9nUKgCs08wo8aEM\"",
"roleId": "3894208461013031",
"roleName": "My New Role",
"rolePrivileges": [
{
"privilegeName": "GROUPS_ALL",
"serviceId": "00haapch16h1ysv"
},
{
"privilegeName": "USERS_ALL",
"serviceId": "00haapch16h1ysv"
}
]
}
ロールの割り当てを作成する
ロールを割り当てるには、次の POST
メソッドを使用して、リクエストを承認するで説明されている承認を含めます。
ユーザーにロールを割り当てるには、ユーザーの
user_id
を含む JSON 本文を追加します。これは、users.get()
、roleId
(既存のロールを取得するを参照)、scope_type
から取得できます。サービス アカウントにロールを割り当てるには、サービス アカウントの
unique_id
(Identity and Access Management(IAM)で定義されている)、roleId
(既存のロールを取得するを参照)、scope_type
を含む JSON 本文を追加します。グループにロールを割り当てるには、グループの
group_id
を含む JSON 本文を追加します。これは、groups.get()
、roleId
(既存のロールを取得するを参照)、およびscope_type
から取得できます。
リクエスト
POST https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments { "roleId": "3894208461012995", "assignedTo": "100662996240850794412", "scopeType": "CUSTOMER" }
レスポンス
成功すると、HTTP 200
ステータス コードが返されます。レスポンスでは、ステータス コードとともに、新しいロールの割り当てのプロパティが返されます。
{
"kind": "admin\#directory\#roleAssignment",
"etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
"roleAssignmentId": "3894208461013211",
"roleId": "3894208461012995",
"assignedTo": "100662996240850794412",
"scopeType": "CUSTOMER"
}
条件を指定してロールの割り当てを作成する
ロールを付与すると、特定の条件を満たすアクションを実行できます。現在、次の 2 つの条件のみがサポートされています。
- セキュリティ グループにのみ適用
- セキュリティ グループには適用されない
condition
が設定されている場合、アクセスされるリソースが条件を満たしている場合にのみ有効になります。condition
が空の場合、ロール(roleId
)はスコープ(scopeType
)のアクター(assignedTo
)に無条件に適用されます。
ユーザーにロールを割り当てるには、次の POST メソッドを使用して、リクエストを承認するで説明されている承認を含めます。
ユーザーの user_id
(users.get() から取得できる)、既存のロールを取得するで説明されている roleId
、condition
を含む JSON 本文を追加します。2 つの条件文字列は、次に示すようにそのまま使用する必要があります。これらの文字列は、グループ エディタとグループ読み取りの事前構築された管理者ロールでのみ機能します。これらの条件は、Cloud IAM 条件構文に従います。
リクエスト
セキュリティ グループにのみ適用
POST https://admin.googleapis.com/admin/directory/v1.1beta1/customer/customer_id/roleassignments { "roleId": "3894208461012995", "assignedTo": "100662996240850794412", "scopeType": "CUSTOMER", "condition": "api.getAttribute('cloudidentity.googleapis.com/groups.labels', []).hasAny(['groups.security']) && resource.type == 'cloudidentity.googleapis.com/Group'" }
セキュリティ グループには適用されない
POST https://admin.googleapis.com/admin/directory/v1.1beta1/customer/customer_id/roleassignments { "roleId": "3894208461012995", "assignedTo": "100662996240850794412", "scopeType": "CUSTOMER", "condition": "!api.getAttribute('cloudidentity.googleapis.com/groups.labels', []).hasAny(['groups.security']) && resource.type == 'cloudidentity.googleapis.com/Group'" }
レスポンス
成功すると、HTTP 200
ステータス コードが返されます。レスポンスでは、ステータス コードとともに、新しいロールの割り当てのプロパティが返されます。
{
"kind": "admin\#directory\#roleAssignment",
"etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
"roleAssignmentId": "3894208461013211",
"roleId": "3894208461012995",
"assignedTo": "100662996240850794412",
"scopeType": "CUSTOMER",
"condition": "!api.getAttribute('cloudidentity.googleapis.com/groups.labels',
[]).hasAny(['groups.security']) && resource.type ==
'cloudidentity.googleapis.com/Group'"
}