Kelola peran

Directory API memungkinkan Anda menggunakan kontrol akses berbasis peran (RBAC) untuk mengelola akses ke fitur di domain Google Workspace Anda. Anda dapat membuat peran khusus dengan hak istimewa untuk membatasi akses admin secara lebih spesifik daripada peran bawaan yang diberikan dengan Google Workspace. Anda dapat menetapkan peran untuk pengguna atau grup keamanan. Panduan ini menjelaskan cara melakukan beberapa tugas dasar terkait peran.

Berikut adalah daftar istilah umum yang digunakan oleh Directory API terkait RBAC dalam Google Workspace:

Hak istimewa
Izin yang diperlukan untuk melakukan tugas atau operasi di domain Google Workspace. Diwakili oleh resource Privilege. Tidak ada data persisten yang terkait dengan resource ini.
Role
Kumpulan hak istimewa yang memberikan kemampuan kepada entitas dengan peran tersebut untuk melakukan tugas atau operasi tertentu. Diwakili oleh resource Role.
Penetapan peran
Catatan peran tertentu yang diberikan kepada pengguna atau grup. Direpresentasikan oleh resource RoleAssignment.
Grup keamanan
Jenis grup Cloud Identity yang digunakan untuk mengontrol akses ke resource organisasi. Grup {i>security<i} dapat berisi pengguna individu dan grup.

Batas penetapan peran dan peran

Anda hanya dapat membuat peran khusus atau penetapan peran dalam jumlah terbatas. Jadi, jika hampir mencapai batas, gabungkan atau hapus peran tersebut agar tidak melebihi batas. Peran dan penetapan peran memiliki batas berikut:

  • Anda dapat membuat hingga 750 peran khusus untuk seluruh organisasi.
  • Anda dapat membuat hingga 500 penetapan peran per unit organisasi (OU), tempat organisasi root dianggap sebagai unit. Misalnya, Anda dapat menetapkan 350 peran di organisasi root dan 400 peran dalam OU lain yang telah ditentukan, misalnya departemen perusahaan. Semua peran administrator standar Google Workspace akan ditetapkan secara default ke cakupan seluruh organisasi. Pelajari lebih lanjut batas hak istimewa yang dapat ditetapkan di tingkat OU.

Peran dan penetapan peran memiliki batas berikut untuk grup:

  • Anda dapat menetapkan peran apa pun kecuali Admin Super.
  • Anda dapat memiliki total hingga 250 penetapan peran untuk grup di keseluruhan OU dan dalam setiap OU.
  • Grup harus merupakan grup keamanan di organisasi Anda.
  • Sebaiknya batasi keanggotaan grup untuk pengguna di organisasi Anda. Anda dapat menambahkan pengguna dari luar organisasi, tetapi mereka mungkin tidak mendapatkan hak istimewa peran tersebut. Untuk mengetahui detailnya, lihat Membatasi keanggotaan grup.

Penetapan peran ke grup

Jika perlu menetapkan lebih dari 500 peran di OU, Anda dapat menambahkan beberapa anggota ke grup keamanan dan menetapkan peran ke grup tersebut. Penetapan peran grup memiliki beberapa batasan tambahan—lihat Pusat bantuan admin untuk mengetahui informasi spesifik.

Pemetaan peran ke hak istimewa konsol Google Admin

Untuk menetapkan peran bagi pengguna yang mengakses hak istimewa mereka melalui konsol Admin, hak istimewa tambahan tertentu mungkin perlu diberikan. Misalnya, untuk memberi pengguna kemampuan untuk membuat pengguna lain melalui konsol Admin, tidak hanya hak istimewa USERS_CREATE yang diperlukan, tetapi juga hak istimewa USERS_UPDATE dan ORGANIZATION_UNITS_RETRIEVE. Tabel berikut memetakan fungsi konsol Admin ke pemberian hak istimewa yang diperlukan untuk mengelola pengguna dan unit organisasi.

Fungsi konsol Admin Hak istimewa yang diperlukan
Unit Organisasi - Baca ORGANIZATION_UNITS_RETRIEVE
Unit Organisasi - Buat ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_CREATE
Unit Organisasi - Pembaruan ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_UPDATE
Unit Organisasi - Hapus ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_DELETE
Unit Organisasi ORGANIZATION_UNITS_ALL
Pengguna - Baca USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Pengguna - Buat USERS_CREATE + USERS_UPDATE + ORGANIZATION_UNITS_RETRIEVE
Pengguna - Pembaruan USERS_UPDATE + ORGANIZATION_UNITS_RETRIEVE
Pengguna - Pindahkan Pengguna USERS_MOVE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Pengguna - Ganti Nama Pengguna USERS_ALIAS + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Pengguna - Reset Sandi USERS_RESET_PASSWORD + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Pengguna - Paksa Perubahan Sandi USERS_FORCE_PASSWORD_CHANGE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Pengguna - Menambahkan/Menghapus Alias USERS_ADD_NICKNAME + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Pengguna - Tangguhkan Pengguna USERS_SUSPEND + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
GRUP GROUPS_ALL
Keamanan - Pengelolaan Keamanan Pengguna USER_SECURITY_ALL + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE

Contoh kasus penggunaan

Sebelum memulai

Selesaikan langkah autentikasi dan otorisasi untuk Google Workspace.

Mendapatkan daftar hak istimewa domain

Untuk mendapatkan daftar hak istimewa yang didukung dan dipaginasi dalam domain Anda, gunakan metode privileges.list().

  • Jika Anda adalah administrator yang mendapatkan hak istimewa di domain Anda sendiri, gunakan my_customer sebagai ID pelanggan.

  • Jika Anda adalah reseller yang mendapatkan hak istimewa untuk salah satu pelanggan Anda, gunakan ID pelanggan yang ditampilkan oleh operasi Mengambil pengguna.

Permintaan

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles/ALL/privileges

Respons

Respons yang berhasil akan menampilkan kode status HTTP 200. Bersama dengan kode status, responsnya akan menampilkan hak istimewa yang didukung di domain:

{
  "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
        }
      ]
    },
    ...
  ]
}

Dapatkan peran yang sudah ada

Untuk mendapatkan daftar peran yang ada, gunakan permintaan GET berikut dan sertakan otorisasi yang dijelaskan di Izin permintaan.

  • Jika Anda adalah administrator yang mendapatkan peran di domain Anda sendiri, gunakan my_customer sebagai ID pelanggan.

  • Jika Anda reseller mendapatkan peran untuk pelanggan, gunakan ID pelanggan yang Anda dapatkan menggunakan operasi Mengambil pengguna.

Permintaan

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles

Respons

Respons yang berhasil akan menampilkan kode status HTTP 200. Bersama dengan kode status, respons akan menampilkan peran yang ada di domain:

{
  "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
    },
    ...
  ]
}

Mencantumkan semua penetapan peran

Untuk mendapatkan daftar semua penetapan peran langsung yang diberi nomor halaman, gunakan metode roleAssignments.list(). API mungkin menampilkan hasil kosong dengan token halaman saat parameter userKey ditetapkan. Anda harus melanjutkan penomoran halaman hingga tidak ada token halaman yang ditampilkan.

  • Jika Anda adalah administrator yang mendapatkan penetapan peran di domain Anda sendiri, gunakan my_customer sebagai ID pelanggan.

  • Jika Anda adalah reseller yang mendapatkan penetapan peran untuk salah satu pelanggan Anda, gunakan ID pelanggan yang ditampilkan oleh operasi Mengambil pengguna.

Permintaan

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments

Respons

Respons yang berhasil akan menampilkan kode status HTTP 200. Bersama dengan kode status, respons akan menampilkan semua peran yang ditetapkan di domain:

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId:"3894208461013211",
  "assignedTo:"100662996240850794412",
  "assigneeType:"user",
  "scopeType:"CUSTOMER",
}

Mencantumkan semua penetapan peran tidak langsung

Untuk mendapatkan daftar semua penetapan peran yang diberi nomor halaman, termasuk yang ditetapkan secara tidak langsung kepada pengguna karena grup tempatnya berada, gunakan metode roleAssignments.list().

API mungkin menampilkan hasil kosong dengan token halaman. Anda harus melanjutkan penomoran halaman hingga tidak ada token halaman yang ditampilkan.

  • Jika Anda adalah administrator yang mendapatkan penetapan peran di domain Anda sendiri, gunakan my_customer sebagai ID pelanggan.

  • Jika Anda adalah reseller yang mendapatkan penetapan peran untuk salah satu pelanggan Anda, gunakan ID pelanggan yang ditampilkan oleh operasi Mengambil pengguna.

  • Ganti USER_KEY dengan nilai yang mengidentifikasi pengguna dalam permintaan API. Untuk informasi selengkapnya, lihat users.get.

Permintaan

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments?userKey=USER_KEY&includeIndirectRoleAssignments=true

Respons

Respons yang berhasil akan menampilkan kode status HTTP 200. Bersama dengan kode status, respons akan menampilkan semua peran yang ditetapkan di domain dan apakah assigneeType adalah user atau group:

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId:"3894208461013211",
  "assignedTo:"100662996240850794412",
  "assigneeType:"group",
  "scopeType:"CUSTOMER",
}

Membuat peran

Untuk membuat peran baru, gunakan permintaan POST berikut dan sertakan otorisasi yang dijelaskan di Mengizinkan permintaan. Tambahkan privilegeName dan serviceId untuk setiap hak istimewa yang harus diberikan dengan peran ini. Untuk properti permintaan dan respons, lihat Referensi API.

Permintaan

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

Respons

Respons yang berhasil akan menampilkan kode status HTTP 200. Bersama dengan kode status, respons akan menampilkan properti untuk peran baru:

{
  "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"
    }
  ]
}

Membuat penetapan peran

Untuk menetapkan peran, gunakan metode POST berikut dan sertakan otorisasi yang dijelaskan dalam Permintaan otorisasi.

Permintaan

POST https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments

{
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER"
}

Respons

Respons yang berhasil akan menampilkan kode status HTTP 200. Bersama dengan kode status, respons akan menampilkan properti untuk penetapan peran baru:

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId": "3894208461013211",
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER"
}

Membuat penetapan peran dengan kondisi

Anda dapat memberikan peran untuk melakukan tindakan yang memenuhi kondisi tertentu. Saat ini, hanya dua kondisi yang didukung:

  • Hanya berlaku untuk grup keamanan
  • Tidak berlaku untuk grup keamanan

Jika ditetapkan, condition hanya akan berlaku jika resource yang diakses memenuhi kondisi. Jika condition kosong, peran (roleId) diterapkan ke pelaku (assignedTo) pada cakupan (scopeType) tanpa syarat.

Untuk menetapkan peran kepada pengguna, gunakan metode POST berikut dan sertakan otorisasi yang dijelaskan dalam Mengizinkan permintaan.

Tambahkan isi JSON dengan user_id pengguna yang bisa Anda dapatkan dari users.get(), roleId seperti yang dijelaskan dalam Mendapatkan peran yang ada, dan condition. Kedua string kondisi harus digunakan kata demi kata seperti yang ditunjukkan di bawah, dan keduanya hanya berfungsi dengan peran administrator standar dan Groups Editor dan Groups Reader. Kondisi ini mengikuti sintaksis kondisi Cloud IAM.

Permintaan

Hanya berlaku untuk grup keamanan
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'"
}
Tidak berlaku untuk grup keamanan
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'"
}

Respons

Respons yang berhasil akan menampilkan kode status HTTP 200. Bersama dengan kode status, respons akan menampilkan properti untuk penetapan peran baru:

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