Directory API ช่วยให้คุณใช้การควบคุมการเข้าถึงตามบทบาท (RBAC) เพื่อจัดการการเข้าถึงฟีเจอร์ในโดเมน Google Workspace ได้ คุณสามารถสร้างบทบาทที่กำหนดเองพร้อมด้วยสิทธิ์เพื่อจำกัดสิทธิ์เข้าถึงระดับผู้ดูแลระบบ อย่างเฉพาะเจาะจงมากกว่าบทบาทที่กำหนดไว้ล่วงหน้าที่มาพร้อมกับ Google Workspace คุณสามารถมอบหมายบทบาท ให้กับผู้ใช้หรือกลุ่มความปลอดภัย คำแนะนำนี้จะอธิบายวิธีทำงานพื้นฐานบางส่วนที่เกี่ยวข้องกับบทบาท
ต่อไปนี้เป็นรายการคำศัพท์ทั่วไปที่ใช้โดย Directory API เกี่ยวกับ RBAC ภายใน Google Workspace
- สิทธิ์
- สิทธิ์ที่จำเป็นในการทำงานหรือดำเนินการในโดเมน Google Workspace ทรัพยากร
Privilege
เป็นตัวแทน ไม่มีข้อมูลถาวรที่เชื่อมโยงกับแหล่งข้อมูลนี้ - Role
- คอลเล็กชันของสิทธิ์ที่มอบความสามารถในการทำงานหรือดำเนินการบางอย่างให้กับเอนทิตีที่มีบทบาทดังกล่าว นำเสนอโดยแหล่งข้อมูล
Role
- การมอบหมายบทบาท
- บันทึกของบทบาทเฉพาะที่กำหนดให้กับผู้ใช้หรือกลุ่ม นำเสนอโดยแหล่งข้อมูล
RoleAssignment
- กลุ่มความปลอดภัย
- กลุ่ม Cloud Identity ประเภทหนึ่งที่ใช้ควบคุมการเข้าถึงทรัพยากรขององค์กร กลุ่มความปลอดภัยมีทั้งผู้ใช้แต่ละรายและกลุ่มได้
ขีดจำกัดของการมอบหมายบทบาท
คุณสร้างบทบาทที่กำหนดเองหรือการมอบหมายบทบาทได้ในจำนวนจำกัดเท่านั้น ดังนั้นหากคุณใช้งานใกล้ถึงขีดจำกัดแล้ว ให้รวมหรือนำออกเพื่อให้ไม่เกินขีดจำกัด บทบาทและการมอบหมายบทบาทมีขีดจำกัดต่อไปนี้
- คุณสร้างบทบาทที่กําหนดเองได้สูงสุด 750 บทบาทสําหรับทั้งองค์กร
- คุณจะสร้างการมอบหมายบทบาทได้สูงสุด 500 บทบาทต่อหน่วยขององค์กร (OU) โดยที่องค์กรระดับรูทเป็นหน่วยหนึ่ง ตัวอย่างเช่น คุณสามารถมอบหมายบทบาท 350 บทบาทในองค์กรระดับรูท และ 400 บทบาทภายใน OU อื่นที่คุณกำหนด เช่น แผนกของบริษัท บทบาทผู้ดูแลระบบที่สร้างไว้ล่วงหน้าทั้งหมดของ Google Workspace จะมีค่าเริ่มต้นเป็นขอบเขตสำหรับทั้งองค์กร เรียนรู้เพิ่มเติมเกี่ยวกับข้อจำกัดของสิทธิ์ที่สามารถกำหนดในระดับ OU
บทบาทและการมอบหมายบทบาทมีขีดจำกัดต่อไปนี้สำหรับกลุ่ม
- คุณสามารถมอบหมายบทบาทใดก็ได้ยกเว้นผู้ดูแลระบบขั้นสูง
- คุณสามารถมอบหมายบทบาทให้กลุ่มได้สูงสุด 250 บทบาทใน OU โดยรวมและภายใน 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 | GROUPS_ALL |
การรักษาความปลอดภัย - การจัดการการรักษาความปลอดภัยของผู้ใช้ | USER_SECURITY_ALL + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE |
ตัวอย่างกรณีการใช้งาน
ก่อนเริ่มต้น
ทำตามขั้นตอนการตรวจสอบสิทธิ์และการให้สิทธิ์สำหรับ Google Workspace ให้เสร็จสมบูรณ์
รับรายการสิทธิ์ของโดเมน
หากต้องการดูรายการสิทธิ์ที่รองรับแบบใส่เลขหน้าในโดเมนของคุณ ให้ใช้เมธอด privileges.list()
หากคุณเป็นผู้ดูแลระบบที่ได้รับสิทธิ์ในโดเมนของคุณเอง ให้ใช้
my_customer
เป็นรหัสลูกค้าหากคุณเป็นตัวแทนจำหน่ายที่ได้รับสิทธิ์สำหรับลูกค้าของคุณ ให้ใช้รหัสลูกค้าที่แสดงโดยการดำเนินการเรียกข้อมูลผู้ใช้
ส่งคำขอ
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
ต่อไปนี้และรวมการให้สิทธิ์ที่อธิบายไว้ในส่วนให้สิทธิ์คำขอ
หากคุณเป็นผู้ดูแลระบบที่ได้รับบทบาทในโดเมนของคุณเอง ให้ใช้
my_customer
เป็นรหัสลูกค้าหากคุณเป็นตัวแทนจำหน่ายที่ได้รับบทบาทสำหรับลูกค้า ให้ใช้รหัสลูกค้าที่คุณได้โดยใช้การดำเนินการเรียกข้อมูลผู้ใช้
ส่งคำขอ
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()
API อาจแสดงผลลัพธ์ที่ว่างเปล่าพร้อมด้วยโทเค็นของหน้าเว็บเมื่อมีการตั้งค่าพารามิเตอร์ userKey
คุณควรใส่เลขหน้าต่อไปจนกว่าจะไม่มีโทเค็นของหน้าแสดง
หากคุณเป็นผู้ดูแลระบบที่ได้รับมอบหมายบทบาทในโดเมนของคุณเอง ให้ใช้
my_customer
เป็นรหัสลูกค้าหากคุณเป็นตัวแทนจำหน่ายที่ได้รับมอบหมายบทบาทให้ลูกค้ารายหนึ่งของคุณ ให้ใช้รหัสลูกค้าที่แสดงผลโดยการดำเนินการเรียกข้อมูลผู้ใช้
ส่งคำขอ
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
เป็นรหัสลูกค้าหากคุณเป็นตัวแทนจำหน่ายที่ได้รับมอบหมายบทบาทให้ลูกค้ารายหนึ่งของคุณ ให้ใช้รหัสลูกค้าที่แสดงผลโดยการดำเนินการเรียกข้อมูลผู้ใช้
แทนที่
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
ต่อไปนี้และรวมการให้สิทธิ์ที่อธิบายไว้ในการให้สิทธิ์คำขอ
หากต้องการมอบหมายบทบาทให้กับผู้ใช้ ให้เพิ่มเนื้อหา JSON ด้วย
user_id
ของผู้ใช้ ซึ่งจะได้จากusers.get()
,roleId
(ตามที่อธิบายไว้ในรับบทบาทที่มีอยู่) และscope_type
หากต้องการมอบหมายบทบาทให้กับบัญชีบริการ ให้เพิ่มเนื้อหา JSON ด้วย
unique_id
ของบัญชีบริการ (ตามที่ระบุไว้ใน Identity and Access Management (IAM))roleId
(ตามที่อธิบายไว้ในส่วนรับบทบาทที่มีอยู่) และscope_type
หากต้องการมอบหมายบทบาทให้กับกลุ่ม ให้เพิ่มเนื้อหา JSON ด้วย
group_id
ของกลุ่ม ซึ่งจะหาได้จากgroups.get()
,roleId
(ตามที่อธิบายไว้ในรับบทบาทที่มีอยู่) และscope_type
ส่งคำขอ
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
) จะมีผลกับผู้ดำเนินการ (assignedTo
) ในขอบเขต (scopeType
) อย่างไม่มีเงื่อนไข
หากต้องการมอบหมายบทบาทให้กับผู้ใช้ ให้ใช้เมธอด POST ต่อไปนี้และรวมการให้สิทธิ์ที่อธิบายไว้ในการให้สิทธิ์คำขอ
เพิ่มเนื้อหา JSON ด้วย user_id
ของผู้ใช้ ซึ่งดูได้จาก users.get(), roleId
ตามที่อธิบายไว้ในรับบทบาทที่มีอยู่ และ condition
สตริงเงื่อนไขทั้ง 2 รายการต้องใช้แบบคำต่อคำตามที่แสดงด้านล่าง และใช้ได้กับบทบาทผู้ดูแลระบบที่กำหนดไว้ล่วงหน้าในเครื่องมือแก้ไข Groups และผู้อ่าน Groups เท่านั้น
เงื่อนไขเหล่านี้เป็นไปตามไวยากรณ์เงื่อนไขของ 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'"
}