役割を管理

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 メソッドを使用して、リクエストを承認するで説明されている承認を含めます。

リクエスト

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