Trang này được dịch bởi Cloud Translation API.

Quản lý vai trò

Directory API cho phép bạn sử dụng chế độ kiểm soát quyền truy cập dựa trên vai trò (RBAC) để quản lý quyền truy cập vào các tính năng trong miền Google Workspace của bạn. Bạn có thể tạo vai trò tuỳ chỉnh có đặc quyền để hạn chế quyền truy cập của quản trị viên một cách cụ thể hơn so với các vai trò được tạo sẵn trong Google Workspace. Bạn có thể chỉ định vai trò cho người dùng hoặc nhóm bảo mật. Hướng dẫn này giải thích cách thực hiện một số thao tác cơ bản liên quan đến vai trò.

Sau đây là danh sách các thuật ngữ thường dùng trong Directory API liên quan đến RBAC trong Google Workspace:

Đặc quyền: Quyền cần thiết để thực hiện một tác vụ hoặc thao tác trong miền Google Workspace. Được biểu thị bằng tài nguyên Privilege. Không có dữ liệu ổn định nào liên kết với tài nguyên này.
Vai trò: Một tập hợp các đặc quyền cho phép những thực thể có vai trò đó thực hiện một số nhiệm vụ hoặc thao tác nhất định. Được biểu thị bằng tài nguyên Role.
Chỉ định vai trò: Bản ghi về một vai trò cụ thể được cấp cho người dùng hoặc nhóm. Được biểu thị bằng tài nguyên RoleAssignment.
Nhóm bảo mật: Một loại nhóm Cloud Identity được dùng để kiểm soát quyền truy cập vào các tài nguyên của tổ chức. Nhóm bảo mật có thể chứa cả người dùng cá nhân và nhóm.

Giới hạn về vai trò và việc chỉ định vai trò

Bạn chỉ có thể tạo một số lượng vai trò tuỳ chỉnh hoặc chỉ định vai trò có hạn. Vì vậy, nếu sắp đạt đến giới hạn, hãy hợp nhất hoặc xoá các vai trò đó để không vượt quá giới hạn. Vai trò và việc chỉ định vai trò có các giới hạn sau:

Bạn có thể tạo tối đa 750 vai trò tuỳ chỉnh cho toàn bộ tổ chức của mình.
Bạn có thể tạo tối đa 1.000 lượt chỉ định vai trò cho mỗi đơn vị tổ chức (OU), trong đó tổ chức gốc được coi là một đơn vị. Ví dụ: bạn có thể chỉ định 600 vai trò trong tổ chức gốc và 700 vai trò trong một OU khác mà bạn đã xác định, chẳng hạn như một phòng ban của công ty. Theo mặc định, tất cả vai trò quản trị viên tạo sẵn trong Google Workspace đều có phạm vi trên toàn tổ chức. Tìm hiểu thêm về các giới hạn đối với đặc quyền có thể được chỉ định ở cấp đơn vị tổ chức.

Vai trò và việc chỉ định vai trò có các giới hạn sau đối với nhóm:

Bạn có thể chỉ định mọi vai trò, ngoại trừ vai trò Quản trị viên cấp cao.
Bạn có thể chỉ định tối đa 250 vai trò cho các nhóm trong tổng số ở đơn vị tổ chức chung và trong mỗi đơn vị tổ chức.
Nhóm này phải là một nhóm bảo mật trong tổ chức của bạn.
Bạn nên hạn chế quyền thành viên nhóm cho người dùng trong tổ chức của mình. Bạn có thể thêm người dùng bên ngoài tổ chức của mình, nhưng họ có thể không nhận được các đặc quyền của vai trò. Để biết thông tin chi tiết, hãy xem bài viết Hạn chế tư cách thành viên trong nhóm. ### Chỉ định vai trò cho nhóm

Nếu cần chỉ định hơn 1.000 vai trò trong một OU, bạn có thể thêm nhiều thành viên vào một nhóm bảo mật và chỉ định vai trò cho nhóm đó. Việc chỉ định vai trò cho nhóm có một số hạn chế khác. Hãy xem Trung tâm trợ giúp dành cho quản trị viên để biết thông tin cụ thể.

Mối liên hệ giữa vai trò và đặc quyền trong Bảng điều khiển dành cho quản trị viên của Google

Để chỉ định vai trò cho những người dùng truy cập vào đặc quyền của họ thông qua Bảng điều khiển dành cho quản trị viên, bạn có thể cần cấp một số đặc quyền bổ sung. Ví dụ: để cấp cho người dùng khả năng tạo người dùng khác thông qua Bảng điều khiển dành cho quản trị viên, bạn không chỉ cần có đặc quyền USERS_CREATE mà còn cần có đặc quyền USERS_UPDATE và ORGANIZATION_UNITS_RETRIEVE. Bảng sau đây liên kết chức năng của Bảng điều khiển dành cho quản trị viên với các đặc quyền bắt buộc để quản lý người dùng và đơn vị tổ chức.

Chức năng của Bảng điều khiển dành cho quản trị viên	Đặc quyền cần thiết
Đơn vị tổ chức – Đọc	`ORGANIZATION_UNITS_RETRIEVE`
Đơn vị tổ chức – Tạo	`ORGANIZATION_UNITS_RETRIEVE` + `ORGANIZATION_UNITS_CREATE`
Đơn vị tổ chức – Cập nhật	`ORGANIZATION_UNITS_RETRIEVE` + `ORGANIZATION_UNITS_UPDATE`
Đơn vị tổ chức – Xoá	`ORGANIZATION_UNITS_RETRIEVE` + `ORGANIZATION_UNITS_DELETE`
Đơn vị tổ chức	`ORGANIZATION_UNITS_ALL`
Người dùng – Đọc	`USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
Người dùng – Tạo	`USERS_CREATE` + `USERS_UPDATE` + `ORGANIZATION_UNITS_RETRIEVE`
Người dùng – Cập nhật	`USERS_UPDATE` + `ORGANIZATION_UNITS_RETRIEVE`
Người dùng – Di chuyển người dùng	`USERS_MOVE` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
Người dùng – Đổi tên người dùng	`USERS_ALIAS` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
Người dùng – Đặt lại mật khẩu	`USERS_RESET_PASSWORD` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
Người dùng – Bắt buộc thay đổi mật khẩu	`USERS_FORCE_PASSWORD_CHANGE` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
Người dùng – Thêm/xoá bí danh	`USERS_ADD_NICKNAME` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
Người dùng – Tạm ngưng người dùng	`USERS_SUSPEND` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
NHÓM	`GROUPS_ALL`
Bảo mật – Quản lý bảo mật người dùng	`USER_SECURITY_ALL` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`

Ví dụ về trường hợp sử dụng

Trước khi bắt đầu

Trước khi chạy các ví dụ trong hướng dẫn này, hãy thiết lập quy trình xác thực và uỷ quyền.

Lấy danh sách các đặc quyền của miền

Để nhận danh sách các đặc quyền được hỗ trợ theo trang trong miền của bạn, hãy sử dụng phương thức privileges.list().

Nếu bạn là quản trị viên nhận được đặc quyền trong miền của riêng mình, hãy sử dụng my_customer làm mã nhận dạng khách hàng.
Nếu bạn là đại lý và muốn nhận đặc quyền cho một trong các khách hàng của mình, hãy sử dụng mã khách hàng do thao tác Truy xuất người dùng trả về.

Yêu cầu

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles/ALL/privileges

Phản hồi

Phản hồi thành công sẽ trả về mã trạng thái HTTP 200. Cùng với mã trạng thái, phản hồi sẽ trả về các đặc quyền được hỗ trợ trong miền:

{
  "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
        }
      ]
    },
    ...
  ]
}

Lấy các vai trò hiện có

Để lấy danh sách các vai trò hiện có, hãy sử dụng yêu cầu GET sau đây và thêm thông tin uỷ quyền theo mô tả trong phần Uỷ quyền yêu cầu.

Nếu bạn là quản trị viên đang nhận vai trò trong miền của riêng mình, hãy sử dụng my_customer làm mã nhận dạng khách hàng.
Nếu bạn là đại lý và đang nhận vai trò cho một khách hàng, hãy sử dụng mã nhận dạng khách hàng mà bạn nhận được bằng cách sử dụng thao tác Truy xuất người dùng.

Yêu cầu

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles

Phản hồi

Phản hồi thành công sẽ trả về mã trạng thái HTTP 200. Cùng với mã trạng thái, phản hồi sẽ trả về các vai trò hiện có trong miền:

{
  "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
    },
    ...
  ]
}

Liệt kê tất cả các chỉ định vai trò

Để nhận danh sách phân trang của tất cả các lượt chỉ định vai trò trực tiếp, hãy sử dụng phương thức roleAssignments.list(). API có thể trả về kết quả trống có mã thông báo trang khi bạn đặt tham số userKey. Bạn nên tiếp tục phân trang cho đến khi không có mã thông báo trang nào được trả về.

Nếu bạn là quản trị viên nhận được chỉ định vai trò trong miền của riêng mình, hãy sử dụng my_customer làm mã nhận dạng khách hàng.
Nếu bạn là đại lý nhận được chỉ định vai trò cho một trong các khách hàng của mình, hãy sử dụng mã khách hàng do thao tác Truy xuất người dùng trả về.

Yêu cầu

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments

Phản hồi

Phản hồi thành công sẽ trả về mã trạng thái HTTP 200. Cùng với mã trạng thái, phản hồi sẽ trả về tất cả các vai trò được chỉ định trong miền:

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId:"3894208461013211",
  "assignedTo:"100662996240850794412",
  "assigneeType:"user",
  "scopeType:"CUSTOMER",
}

Liệt kê tất cả các chỉ định vai trò gián tiếp

Để lấy danh sách phân trang của tất cả các lượt chỉ định vai trò, bao gồm cả những lượt chỉ định gián tiếp cho người dùng do các nhóm mà họ thuộc về, hãy sử dụng phương thức roleAssignments.list().

API có thể trả về kết quả trống bằng mã thông báo trang. Bạn nên tiếp tục phân trang cho đến khi không có mã thông báo trang nào được trả về.

Nếu bạn là quản trị viên nhận được chỉ định vai trò trong miền của riêng mình, hãy sử dụng my_customer làm mã nhận dạng khách hàng.
Nếu bạn là đại lý nhận được chỉ định vai trò cho một trong các khách hàng của mình, hãy sử dụng mã khách hàng do thao tác Truy xuất người dùng trả về.
Thay thế USER_KEY bằng một giá trị xác định người dùng trong yêu cầu API. Để biết thêm thông tin, hãy xem users.get.

Yêu cầu

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments?userKey=USER_KEY&includeIndirectRoleAssignments=true

Phản hồi

Phản hồi thành công sẽ trả về mã trạng thái HTTP 200. Cùng với mã trạng thái, phản hồi sẽ trả về tất cả các vai trò được chỉ định trong miền và liệu assigneeType là user hay group:

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId:"3894208461013211",
  "assignedTo:"100662996240850794412",
  "assigneeType:"group",
  "scopeType:"CUSTOMER",
}

Tạo vai trò

Để tạo một vai trò mới, hãy sử dụng yêu cầu POST sau đây và thêm thông tin uỷ quyền được mô tả trong phần Uỷ quyền yêu cầu. Thêm privilegeName và serviceId cho mỗi đặc quyền cần được cấp cho vai trò này. Để biết các thuộc tính yêu cầu và phản hồi, hãy xem Tài liệu tham khảo về API.

Yêu cầu

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"
    }
  ]
}

Phản hồi

Phản hồi thành công sẽ trả về mã trạng thái HTTP 200. Cùng với mã trạng thái, phản hồi sẽ trả về các thuộc tính cho vai trò mới:

{
  "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"
    }
  ]
}

Tạo một chỉ định vai trò

Để chỉ định vai trò, hãy dùng phương thức POST sau đây và thêm thông tin uỷ quyền như mô tả trong phần Uỷ quyền yêu cầu.

Để chỉ định vai trò cho người dùng, hãy thêm một phần nội dung JSON có user_id của người dùng mà bạn có thể lấy từ users.get(), roleId (như mô tả trong phần Lấy vai trò hiện có) và scope_type.
Để chỉ định vai trò cho một tài khoản dịch vụ, hãy thêm một phần nội dung JSON có unique_id của tài khoản dịch vụ (như được xác định trong Quản lý danh tính và quyền truy cập (IAM)), roleId (như mô tả trong phần Lấy các vai trò hiện có) và scope_type.
Để chỉ định vai trò cho một nhóm, hãy thêm một phần nội dung JSON có group_id của nhóm. Bạn có thể lấy group_id này từ groups.get(), roleId (như mô tả trong phần Lấy vai trò hiện có) và scope_type.

Yêu cầu

POST https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments

{
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER"
}

Phản hồi

Phản hồi thành công sẽ trả về mã trạng thái HTTP 200. Cùng với mã trạng thái, phản hồi sẽ trả về các thuộc tính cho việc chỉ định vai trò mới:

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId": "3894208461013211",
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER"
}

Tạo một chỉ định vai trò có điều kiện

Bạn có thể cấp vai trò để thực hiện các thao tác đáp ứng một số điều kiện cụ thể. Hiện tại, chỉ có 2 điều kiện được hỗ trợ:

Chỉ áp dụng cho các nhóm bảo mật
Không áp dụng cho nhóm bảo mật

Khi bạn đặt condition, chế độ này sẽ chỉ có hiệu lực khi tài nguyên được truy cập đáp ứng điều kiện. Nếu condition trống, vai trò (roleId) sẽ được áp dụng vô điều kiện cho đối tượng (assignedTo) ở phạm vi (scopeType).

Để chỉ định vai trò cho người dùng, hãy sử dụng phương thức POST sau đây và thêm thông tin uỷ quyền được mô tả trong phần Uỷ quyền yêu cầu.

Thêm một phần nội dung JSON có user_id của người dùng mà bạn có thể lấy từ users.get(), roleId như mô tả trong phần Lấy vai trò hiện có và condition. Bạn phải sử dụng nguyên văn hai chuỗi điều kiện như minh hoạ bên dưới và chúng chỉ hoạt động với vai trò quản trị viên được tạo sẵn của Trình chỉnh sửa nhóm và Người đọc nhóm. Các điều kiện này tuân theo cú pháp điều kiện Cloud IAM.

Yêu cầu

Chỉ áp dụng cho các nhóm bảo mật

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'"
}

Không áp dụng cho nhóm bảo mật

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'"
}

Phản hồi

Phản hồi thành công sẽ trả về mã trạng thái HTTP 200. Cùng với mã trạng thái, phản hồi sẽ trả về các thuộc tính cho việc chỉ định vai trò mới:

{
  "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'"
}

Quản lý vai trò Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Giới hạn về vai trò và việc chỉ định vai trò

Mối liên hệ giữa vai trò và đặc quyền trong Bảng điều khiển dành cho quản trị viên của Google

Ví dụ về trường hợp sử dụng

Trước khi bắt đầu

Lấy danh sách các đặc quyền của miền

Yêu cầu

Phản hồi

Lấy các vai trò hiện có

Yêu cầu

Phản hồi

Liệt kê tất cả các chỉ định vai trò

Yêu cầu

Phản hồi

Liệt kê tất cả các chỉ định vai trò gián tiếp

Yêu cầu

Phản hồi

Tạo vai trò

Yêu cầu

Phản hồi

Tạo một chỉ định vai trò

Yêu cầu

Phản hồi

Tạo một chỉ định vai trò có điều kiện

Yêu cầu

Chỉ áp dụng cho các nhóm bảo mật

Không áp dụng cho nhóm bảo mật

Phản hồi

Quản lý vai trò