จัดการบทบาท

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

ถ้าต้องการมอบหมายมากกว่า 1, 000 บทบาทในหน่วยขององค์กร คุณสามารถเพิ่มหลายบทบาทได้ สมาชิกในกลุ่มความปลอดภัยและมอบหมายบทบาทให้กับกลุ่ม บทบาทของกลุ่ม งานมีข้อจำกัดเพิ่มเติมบางอย่าง โปรดดู ศูนย์ช่วยเหลือสำหรับผู้ดูแลระบบเพื่อดูข้อมูลที่เฉพาะเจาะจง

การแมปบทบาทกับสิทธิ์ในคอนโซลผู้ดูแลระบบของ 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

ตัวอย่างกรณีการใช้งาน

ก่อนเริ่มต้น

ดำเนินการตาม การตรวจสอบสิทธิ์และการให้สิทธิ์ ขั้นตอนสำหรับ Google Workspace

รับรายการสิทธิ์ของโดเมน

หากต้องการรับรายการสิทธิ์ที่รองรับที่มีเลขหน้าในโดเมน ให้ใช้ privileges.list()

  • หากคุณเป็นผู้ดูแลระบบที่ได้รับสิทธิ์ในโดเมนของคุณเอง ให้ใช้ my_customer เป็นรหัสลูกค้า

  • ถ้าคุณเป็นตัวแทนจำหน่ายที่ได้รับสิทธิ์สำหรับลูกค้า ใช้รหัสลูกค้าที่ส่งคืนโดยการเรียกข้อมูล user

ส่งคำขอ

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 เป็นรหัสลูกค้า

  • หากคุณเป็นตัวแทนจำหน่ายที่ได้รับบทบาทสำหรับลูกค้า โปรดใช้รหัสลูกค้าที่คุณ โดยใช้คำสั่ง เรียกข้อมูล user

ส่งคำขอ

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 เป็นรหัสลูกค้า

  • หากคุณเป็นตัวแทนจำหน่ายที่ได้รับการมอบหมายบทบาทสำหรับลูกค้ารายหนึ่ง ใช้รหัสลูกค้าที่ส่งคืนโดยการเรียกข้อมูล user

ส่งคำขอ

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

  • ให้แทนที่ 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'"
}