Directory API memungkinkan Anda menggunakan kontrol akses berbasis peran (RBAC) untuk mengelola akses ke fitur di domain Google Workspace Anda. Anda dapat membuat peran kustom dengan hak istimewa untuk membatasi akses admin secara lebih spesifik daripada peran standar 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 memberi entitas dengan peran tersebut kemampuan untuk melakukan tugas atau operasi tertentu. Diwakili oleh
resource
Role
. - Penetapan peran
- Data peran tertentu yang diberikan kepada pengguna atau grup. Diwakili oleh
resource
RoleAssignment
. - Grup keamanan
- Jenis grup Cloud Identity yang digunakan untuk mengontrol akses ke resource organisasi. Grup {i>security<i} dapat berisi pengguna individual 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), jika organisasi root dianggap sebagai unit. Misalnya, Anda dapat menetapkan 350 peran di organisasi root dan 400 peran dalam OU lain yang telah ditentukan, seperti departemen perusahaan. Semua peran administrator standar Google Workspace 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 hingga 250 penetapan peran untuk total grup di OU keseluruhan 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. 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. Penetapan peran grup memiliki beberapa batasan tambahan—lihat pusat bantuan Admin untuk mengetahui informasi spesifik.
Pemetaan peran hingga 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, hak istimewa USERS_CREATE
tidak hanya 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 - Atur Ulang Sandi | USERS_RESET_PASSWORD + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE |
Pengguna - Paksa Perubahan Sandi | USERS_FORCE_PASSWORD_CHANGE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE |
Pengguna - Tambahkan/Hapus 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 beserta nomor halamannya di 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, 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 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 di Permintaan
izin.
Jika Anda adalah 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 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, responsnya akan menampilkan peran yang ada dalam 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 dipaginasi, gunakan
metode
roleAssignments.list()
. API mungkin menampilkan hasil kosong dengan token halaman jika parameter userKey
ditetapkan. Anda harus melanjutkan penomoran halaman hingga token halaman tidak 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, responsnya 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 bernomor halaman yang berisi semua penetapan peran, termasuk yang secara tidak langsung
ditetapkan kepada pengguna karena grup tempatnya berada, gunakan
metode
roleAssignments.list()
.
API mungkin menampilkan hasil kosong dengan token halaman. Anda harus melanjutkan penomoran halaman hingga token halaman tidak 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, lihatusers.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, responsnya menampilkan semua peran yang ditetapkan dalam 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 Permintaan
izin.
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 tersebut:
{
"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.
Untuk menetapkan peran kepada pengguna, tambahkan isi JSON dengan
user_id
pengguna, yang bisa Anda dapatkan dariusers.get()
,roleId
(seperti yang dijelaskan dalam Mendapatkan peran yang ada), danscope_type
.Untuk menetapkan peran ke akun layanan, tambahkan isi JSON dengan
unique_id
akun layanan (seperti yang dijelaskan dalam Identity and Access Management (IAM)),roleId
(seperti yang dijelaskan dalam Mendapatkan peran yang ada), danscope_type
.Untuk menetapkan peran ke grup, tambahkan isi JSON dengan
group_id
grup, yang bisa Anda dapatkan darigroups.get()
,roleId
(seperti yang dijelaskan dalam Mendapatkan peran yang ada), danscope_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 kode status HTTP 200
. Bersama dengan
kode status, responsnya 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 ketentuan
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
ditetapkan, kebijakan tersebut hanya akan berlaku saat 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 Otorisasi 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
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 kode status HTTP 200
. Bersama dengan
kode status, responsnya 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'"
}