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 |
ตัวอย่างกรณีการใช้งาน
ก่อนเริ่มต้น
ตั้งค่าการตรวจสอบสิทธิ์และการให้สิทธิ์ก่อนเรียกใช้ตัวอย่างในคู่มือนี้
ดูรายการสิทธิ์ของโดเมน
หากต้องการดูรายการสิทธิ์ที่รองรับในโดเมนของคุณแบบแบ่งหน้า ให้ใช้เมธอด
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 รายการตามที่แสดงด้านล่าง และสตริงดังกล่าวจะใช้ได้กับบทบาทผู้ดูแลระบบที่สร้างไว้ล่วงหน้าของเครื่องมือแก้ไขกลุ่มและผู้อ่านกลุ่มเท่านั้น
เงื่อนไขเหล่านี้เป็นไปตามไวยากรณ์ของเงื่อนไข 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'"
}