役割を管理

Directory API を使用すると、ロールベースのアクセス制御（RBAC）を使用して、Google Workspace ドメイン内の機能へのアクセスを管理できます。権限を持つカスタムロールを作成して、Google Workspace に付属の既定のロールよりも具体的に管理者アクセスを制限できます。ロールはユーザーまたはセキュリティ グループに割り当てることができます。このガイドでは、ロールに関連する基本的なタスクを実行する方法について説明します。

以下は、Google Workspace 内の RBAC に関して Directory API で使用される一般的な用語のリストです。

権限
Google Workspace ドメインでタスクまたはオペレーションを実行するために必要な権限。Privilege リソースで表されます。このリソースに関連付けられた永続データはありません。
職務
そのロールを持つエンティティに特定のタスクまたはオペレーションを実行する権限を付与する権限の集合。Role リソースで表されます。
ロールの割り当て
ユーザーまたはグループに割り当てられた特定のロールの記録。RoleAssignment リソースで表されます。
セキュリティ グループ
組織リソースへのアクセスを制御するために使用される Cloud Identity グループの一種。セキュリティ グループには、個々のユーザーとグループの両方を含めることができます。

ロールとロールの割り当ての上限

作成できるカスタムロールまたはロールの割り当てには上限があるため、上限に近づいている場合は、統合または削除して上限内に収まるようにしてください。ロールとロールの割り当てには次の上限があります。

  • 組織全体で作成できるカスタムロールは最大 750 個です。
  • 組織部門（OU）ごとに最大 1,000 個のロール割り当てを作成できます。ルート組織は 1 つのユニットと見なされます。たとえば、ルート組織に 600 個のロール、定義した別の OU（会社の部門など）に 700 個のロールを割り当てることができます。Google Workspace の既定の管理者ロールはすべて、デフォルトで組織全体のスコープになっています。OU レベルで割り当てることができる権限の上限の詳細を確認する。

ロールとロールの割り当てには、グループに対して次の上限があります。

  • 特権管理者を除くすべてのロールを割り当てることができます。
  • OU 全体と各 OU 内で、合計で 250 グループにロールを割り当てることができます。
  • このグループは、組織内のセキュリティ グループである必要があります。
  • グループ メンバーを組織内のユーザーに限定することをおすすめします。組織外のユーザーを追加することもできますが、そのユーザーにロールの権限が付与されない可能性があります。詳しくは、グループ メンバーを制限するをご覧ください。### グループへのロールの割り当て

OU で 1, 000 を超えるロールを割り当てる必要がある場合は、複数のメンバーをセキュリティ グループに追加して、グループにロールを割り当てます。グループロールの割り当てには、いくつかの制限があります。詳しくは、管理者向けヘルプセンターをご覧ください。

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() メソッドを使用します。

  • 自社のドメインで権限を取得する管理者の場合は、顧客 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
    },
    ...
  ]
}

すべてのロールの割り当てを一覧表示する

すべての直接ロール割り当てのページネーション付きリストを取得するには、roleAssignments.list() メソッドを使用します。userKey パラメータが設定されている場合、API はページトークンを含む空の結果を返すことがあります。ページトークンが返されなくなるまで、ページネーション処理を続行する必要があります。

  • 自社のドメインでロールの割り当てを取得する管理者の場合は、顧客 ID に my_customer を使用します。

  • 販売パートナーがいずれかの顧客のロール割り当てを取得する場合は、ユーザーを取得するの操作で返された顧客 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 からページトークンとともに空の結果が返されることがあります。ページトークンが返されなくなるまで、ページネーションを続行する必要があります。

  • 自社のドメインでロールの割り当てを取得する管理者の場合は、顧客 ID に my_customer を使用します。

  • 販売パートナーがいずれかの顧客のロール割り当てを取得する場合は、ユーザーを取得するの操作で返された顧客 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 メソッドを使用し、リクエストを承認するで説明されている承認を含めます。

リクエスト

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'"
}