Directory API を使用すると、ロールベースのアクセス制御を使用して、ドメイン内の機能へのユーザー アクセスを管理できます。これを行うには、権限とロール、およびユーザーへのロールの割り当てを管理します。
概要
ドメイン内でなんらかのタスクと操作を行うには、権限が必要です。 ロールとは、そのロールを持つユーザーになんらかのタスクまたは操作を実行する（ユーザー サービスや Chrome などのサービスの）権限を付与する権限の集合のことです。ロールの割り当ては、ユーザーに割り当てられた特定のロールの記録です。
このガイドのメソッドは、ドメイン内でのロールの作成や、ユーザーへのロールの割り当てに使用できます。一般的なプロセスでは、次の 3 つのリソースを使用します。
- privileges リソースは、ドメイン内でサポートされている権限のリストを取得するために使用されます。
- roles リソースは、新しいロールの作成または既存のロールの取得に使用されます。
- roleAssignments リソースは、ドメイン内のユーザーにロールを割り当てるために使用されます。
サポートされている権限を取得する
サポートされている権限のリストを取得するには、次の GET リクエストを使用し、リクエストを承認するで説明されている承認を含めます。
自社のドメインで権限を取得する管理者の場合は、顧客 ID に
my_customerを使用します。販売パートナーがいずれかの顧客の権限を取得する場合は、ユーザーを取得するの操作で返された顧客 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
},
...
]
}
ロールを作成する
新しいロールを作成するには、次の 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 メソッドを使用し、リクエストを承認するで説明されている承認を含めます。 JSON 本文では、user_id にユーザー（users.get() で取得）を指定し、roleId は既存のロールを取得するで説明したとおりに指定します。
リクエスト
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 メソッドを使用し、リクエストを承認するで説明されている承認を含めます。
JSON 本文では、ユーザーの user_id（users.get() で取得）、既存のロールを取得するで説明した roleId、condition を指定します。この 2 つの条件文字列は、下記のとおりに使用する必要があります。この条件は、Groups Editor と Groups Reader の既定の管理者ロールでのみ機能します。
これらの条件は、Cloud IAM Conditions 構文に従います。
リクエスト
セキュリティ グループにのみ適用する
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'"
}
管理コンソールの UI にロールを割り当てる
管理コンソールの UI から権限にアクセスするユーザーにロールを割り当てるには、追加の権限を付与する必要があります。たとえば、管理コンソールの UI で他のユーザーを作成できるようにするには、USERS_CREATE 権限だけでなく、USERS_UPDATE 権限と ORGANIZATION_UNITS_RETRIEVE 権限も必要になります。次の表に、管理コンソールの UI の機能と、ユーザーと組織部門の管理に必要な権限の対応を示します。
| 管理コンソールの UI の機能 | 必要な権限 |
|---|---|
| 組織部門 - 読み取り | 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 |