Directory API ช่วยให้คุณใช้การควบคุมการเข้าถึงตามบทบาท (RBAC) เพื่อจัดการสิทธิ์เข้าถึงฟีเจอร์ในโดเมน Google Workspace ได้ คุณสามารถสร้างบทบาทที่กำหนดเองซึ่งมีสิทธิ์เพื่อจำกัดการเข้าถึงของผู้ดูแลระบบได้เฉพาะเจาะจงกว่าบทบาทที่สร้างไว้ล่วงหน้าซึ่งมาพร้อมกับ Google Workspace คุณสามารถมอบหมายบทบาทให้กับผู้ใช้หรือกลุ่มความปลอดภัยได้ คู่มือนี้จะอธิบายวิธีทํางานบางอย่างที่เกี่ยวข้องกับบทบาทพื้นฐาน
ต่อไปนี้คือรายการคําศัพท์ทั่วไปที่ Directory API ใช้เกี่ยวกับ RBAC ภายใน Google Workspace
- สิทธิ์
- สิทธิ์ที่จําเป็นต่อการดำเนินการหรืองานในโดเมน Google Workspace แสดงโดยแหล่งข้อมูล
Privilege
ไม่มีข้อมูลที่เก็บไว้ถาวรซึ่งเชื่อมโยงกับทรัพยากรนี้ - Role
- ชุดสิทธิ์ที่อนุญาตให้เอนทิตีที่มีบทบาทนั้นสามารถดําเนินการหรืองานบางอย่างได้ แสดงโดยทรัพยากร
Role
- การมอบหมายบทบาท
- บันทึกของบทบาทที่มอบให้กับผู้ใช้หรือกลุ่ม แสดงโดยแหล่งข้อมูล
RoleAssignment
- กลุ่มความปลอดภัย
- ประเภทกลุ่ม Cloud Identity ที่ใช้ควบคุมการเข้าถึงทรัพยากรขององค์กร กลุ่มความปลอดภัยมีทั้งผู้ใช้รายบุคคลและกลุ่ม
บทบาทและขีดจํากัดการมอบหมายบทบาท
คุณสร้างบทบาทที่กำหนดเองหรือการมอบหมายบทบาทได้เพียงจำนวนหนึ่งเท่านั้น ดังนั้นหากใกล้ถึงขีดจำกัดแล้ว ให้รวมหรือนำบทบาทเหล่านั้นออกเพื่อไม่ให้เกินขีดจำกัด บทบาทและการมอบหมายบทบาทมีข้อจำกัดต่อไปนี้
- คุณสามารถสร้างบทบาทที่กำหนดเองได้สูงสุด 750 รายการสำหรับทั้งองค์กร
- คุณสามารถสร้างการมอบหมายบทบาทได้สูงสุด 1,000 รายการต่อหน่วยขององค์กร (OU) โดยที่องค์กรระดับรูทจะถือเป็นหน่วย เช่น คุณสามารถมอบหมายบทบาท 600 บทบาทในองค์กรระดับรูทและ 700 บทบาทภายใน OU อื่นที่คุณกำหนดไว้ เช่น แผนกขององค์กร บทบาทผู้ดูแลระบบที่กําหนดไว้ล่วงหน้าทั้งหมดของ Google Workspace จะมีขอบเขตระดับองค์กรโดยค่าเริ่มต้น ดูข้อมูลเพิ่มเติมเกี่ยวกับขีดจํากัดของสิทธิ์ที่มอบหมายได้ในระดับ OU
บทบาทและการมอบหมายบทบาทมีขีดจํากัดต่อไปนี้สําหรับกลุ่ม
- คุณสามารถมอบหมายบทบาทใดก็ได้ ยกเว้นบทบาทผู้ดูแลระบบขั้นสูง
- คุณสามารถมอบหมายบทบาทให้กลุ่มได้สูงสุดทั้งหมด 250 รายการในระดับ OU โดยรวมและภายใน OU แต่ละหน่วย
- กลุ่มดังกล่าวต้องเป็นกลุ่มความปลอดภัยในองค์กร
- เราขอแนะนําให้จํากัดการเป็นสมาชิกกลุ่มไว้เฉพาะผู้ใช้ในองค์กร คุณสามารถเพิ่มผู้ใช้จากภายนอกองค์กรได้ แต่ผู้ใช้ดังกล่าวอาจไม่ได้รับสิทธิ์บทบาท โปรดดูรายละเอียดที่หัวข้อจำกัดการเป็นสมาชิกกลุ่ม ### การกำหนดบทบาทให้กับกลุ่ม
หากต้องการมอบหมายบทบาทมากกว่า 1, 000 บทบาทใน OU คุณสามารถเพิ่มสมาชิกหลายคนในกลุ่มความปลอดภัยและมอบหมายบทบาทให้กลุ่มได้ การกำหนดบทบาทกลุ่มมีข้อจำกัดเพิ่มเติมบางอย่าง โปรดดูข้อมูลเฉพาะที่ศูนย์ช่วยเหลือสำหรับผู้ดูแลระบบ
การแมปบทบาทกับสิทธิ์ในคอนโซลผู้ดูแลระบบของ 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 |
ตัวอย่าง Use Case
ก่อนเริ่มต้น
ทําตามขั้นตอนการตรวจสอบสิทธิ์และการให้สิทธิ์สําหรับ 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 Editor และ Groups Reader เท่านั้น
เงื่อนไขเหล่านี้เป็นไปตามไวยากรณ์ของเงื่อนไข 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'"
}