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 standar yang disediakan dengan Google Workspace. Anda dapat menetapkan peran untuk pengguna atau grup keamanan. Panduan ini menjelaskan cara melakukan beberapa tugas dasar yang terkait dengan peran.

Berikut ini adalah daftar istilah umum yang digunakan oleh API Direktori dengan sehubungan dengan RBAC dalam Google Workspace:

Hak istimewa

Izin yang diperlukan untuk melakukan tugas atau operasi di Domain Google Workspace. Diwakili oleh Referensi Privilege. Ada tidak ada data persisten yang terkait dengan resource ini.

Jabatan

Kumpulan hak istimewa yang memberi entitas dengan peran tersebut kemampuan untuk melakukan tugas atau operasi tertentu. Diwakili oleh Referensi Role.

Penetapan peran

Data peran tertentu yang diberikan kepada pengguna atau grup. Diwakili oleh RoleAssignment Infrastruktur Cloud.

Grup keamanan

Jenis Grup Cloud Identity yang digunakan untuk mengontrol akses ke organisasi Google Cloud Platform. Grup keamanan dapat berisi pengguna perorangan dan grup.

Batas peran dan penetapan peran

Anda hanya dapat membuat peran khusus atau penetapan peran dalam jumlah terbatas, jadi jika Anda mendekati batas, gabungkan atau hapus agar tetap berada di bawah batas tersebut. Peran dan penetapan peran memiliki batasan berikut:

• Anda dapat membuat hingga 750 peran khusus untuk seluruh organisasi.
• Anda dapat membuat hingga 1.000 penetapan peran per unit organisasi (OU), tempat organisasi root dianggap sebagai unit. Misalnya, Anda dapat menetapkan 600 peran di organisasi root dan 700 peran dalam OU lain yang telah Anda tetapkan, seperti departemen perusahaan. Semua peran administrator standar Google Workspace ditetapkan secara default ke ruang lingkup di seluruh organisasi. Pelajari selengkapnya tentang batasan 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 hingga total 250 penetapan peran ke grup di OU keseluruhan dan di dalam setiap OU.
• Grup harus berupa 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. Untuk mengetahui detailnya, lihat Membatasi keanggotaan grup. ### Penetapan peran ke grup

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

Catatan: Untuk membuat grup keamanan, Anda harus menggunakan Cloud Identity API. Anda tidak dapat menggunakan API Direktori. Untuk informasi selengkapnya, lihat grup keamanan dokumentasi.

Pemetaan peran untuk hak istimewa di konsol Google Admin

Untuk menetapkan peran bagi pengguna yang mengakses hak istimewa mereka melalui konsol Admin, hak istimewa tambahan tertentu mungkin diperlukan diberikan. Misalnya, untuk memberi pengguna kemampuan untuk membuat pengguna lain melalui konsol Admin, bukan hanya hak istimewa USERS_CREATE diperlukan, tetapi juga USERS_UPDATE dan ORGANIZATION_UNITS_RETRIEVE hak istimewa pengguna. Tabel berikut memetakan konsol Admin fungsionalitas terhadap 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 - Dibaca	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 langkah-langkah untuk menggunakan Google Workspace.

Mendapatkan daftar hak istimewa domain

Untuk mendapatkan daftar yang diberi nomor halaman dari hak istimewa yang didukung di domain Anda, gunakan privileges.list() .

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

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

Permintaan

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

Respons

Respons yang berhasil akan menampilkan status HTTP 200 dari kode Anda. Bersama dengan kode status, respons 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
        }
      ]
    },
    ...
  ]
}

Mendapatkan peran yang ada

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

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

• Jika Anda reseller yang mendapatkan peran untuk pelanggan, gunakan ID pelanggan yang Anda menggunakan metode Ambil pengguna.

Permintaan

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

Respons

Respons yang berhasil akan menampilkan status HTTP 200 dari kode Anda. 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 yang diberi nomor halaman untuk semua penetapan peran langsung, gunakan roleAssignments.list() . API mungkin menampilkan hasil kosong dengan token halaman jika userKey disetel. Anda harus melanjutkan penomoran halaman hingga tidak ada token halaman yang muncul dikembalikan.

• Jika Anda 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 ID pelanggan pengguna.

Permintaan

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

Respons

Respons yang berhasil akan menampilkan status HTTP 200 dari kode Anda. 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 yang diberi nomor halaman untuk semua penetapan peran, termasuk yang secara tidak langsung ditetapkan ke pengguna karena grupnya, gunakan roleAssignments.list() .

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

• Jika Anda 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 ID pelanggan pengguna.

• Ganti USER_KEY dengan nilai yang mengidentifikasi 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 status HTTP 200 dari kode Anda. 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 dalam Otorisasi permintaan. Tambahkan privilegeName dan serviceId untuk setiap hak istimewa yang seharusnya yang diberi peran ini. Untuk properti permintaan dan respons, lihat class API Referensi.

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 status HTTP 200 dari kode Anda. 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 dijelaskan dalam Mengizinkan permintaan.

• Untuk menetapkan peran kepada pengguna, tambahkan isi JSON dengan user_id pengguna, yang dapat Anda dapatkan dari users.get(), roleId (seperti yang dijelaskan dalam Mendapatkan peran yang ada), dan scope_type.

• Untuk menetapkan peran ke akun layanan, tambahkan isi JSON dengan unique_id akun layanan (sebagaimana ditentukan dalam Identity and Access Management (IAM)), roleId (seperti yang dijelaskan dalam Mendapatkan peran yang ada), dan scope_type.

• Untuk menetapkan peran ke grup, tambahkan isi JSON dengan group_id , yang bisa Anda dapatkan dari groups.get() roleId (seperti yang dijelaskan dalam Dapatkan peran yang ada), dan scope_type.

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 status HTTP 200 dari kode Anda. 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"
}

Buat penetapan peran dengan ketentuan

Catatan: Fitur ini hanya tersedia dalam versi v1.1beta1 API, dan hanya untuk Enterprise Standard, Enterprise Plus, Google Workspace for Education Plus dan Cloud Identity Premium. Tidak diperlukan penyiapan tambahan untuk menggunakan fitur tersebut. Penetapan peran dengan kondisi tidak dipatuhi di Konsol Admin.

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 condition disetel, tindakan tersebut hanya akan berlaku saat resource yang diakses memenuhi kondisi. Jika condition kosong, peran (roleId) adalah diterapkan ke pelaku (assignedTo) dalam cakupan (scopeType) tanpa syarat.

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

Tambahkan isi JSON dengan user_id pengguna, yang bisa Anda dapatkan dari users.get(), roleId sebagai yang dijelaskan di Mendapatkan peran yang ada, dan condition. Tujuan dua {i>string<i} kondisi harus digunakan kata demi kata seperti yang ditunjukkan di bawah ini dan mereka hanya berfungsi dengan Groups Editor dan Groups Reader peran administrator standar. 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 status HTTP 200 dari kode Anda. 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'"
}