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 tính năng 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. Bạn có thể tạo vai trò tuỳ chỉnh với đặ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ò tạo sẵn được cung cấp 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ố tác vụ cơ bản liên quan đến vai trò.

Sau đây là danh sách các thuật ngữ phổ biến mà Directory API sử dụng 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 cấp cho các thực thể có vai trò đó khả năng thực hiện một số tác 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 của 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 dùng để kiểm soát quyền truy cập vào 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.

Hạn mức 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 bạn 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à các vai trò được chỉ định 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 bộ phận của công ty. Tất cả vai trò quản trị viên tạo sẵn của Google Workspace đều mặc định là 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 OU.

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

Bạn có thể chỉ định bất kỳ vai trò nào ngoại 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 ở OU tổng thể và trong mỗi OU.
Nhóm đó phải là nhóm bảo mật trong tổ chức của bạn.
Bạn nên hạn chế thành viên nhóm ở những 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, nhưng họ có thể không nhận được các đặc quyền theo 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ò trong 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ể.

Liên kết vai trò với đặ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ác đặ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 quyền 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ấp đặc quyền USERS_CREATE mà còn phải cấp đặ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ần có đặc quyền
Đơ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

Hoàn tất các bước xác thực và uỷ quyền cho Google Workspace.

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

Để nhận danh sách được phân trang các đặc quyền được hỗ trợ 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 có đặc quyền trong miền của riêng mình, hãy sử dụng my_customer làm mã khách hàng.
Nếu bạn là đại lý nhận được đặ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ó

Để nhận danh sách các vai trò hiện có, hãy sử dụng yêu cầu GET sau đây và đưa vào quyền uỷ quyền được mô tả trong phần Uỷ quyền yêu cầu.

Nếu bạn là quản trị viên nhận vai trò trong miền của riêng mình, hãy sử dụng my_customer làm mã khách hàng.
Nếu bạn là đại lý nhận vai trò cho khách hàng, hãy sử dụng mã khách hàng mà bạn đã nhận được bằ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ò tồn tại 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 lượt chỉ định vai trò

Để nhận danh sách phân trang 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 bằng mã thông báo trang khi bạn đặt thông 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 các vai trò được chỉ định trong miền của riêng mình, hãy sử dụng my_customer làm mã khách hàng.
Nếu bạn là đại lý nhận được các vai trò được chỉ định 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ả 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 lượt chỉ định vai trò gián tiếp

Để nhận danh sách phân trang 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 các vai trò được chỉ định trong miền của riêng mình, hãy sử dụng my_customer làm mã khách hàng.
Nếu bạn là đại lý nhận được các vai trò được chỉ định 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ả vai trò được chỉ định trong miền và liệu assigneeType có phải 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 quyền uỷ quyền được mô tả trong phần Uỷ quyền yêu cầu. Thêm privilegeName và serviceId cho từng đặc quyền cần được cấp với vai trò này. Đối với 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 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 vai trò được chỉ định

Để chỉ định vai trò, hãy sử dụng phương thức POST sau đây và thêm quyền uỷ quyền được 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 phần thân JSON có user_id của người dùng. Bạn có thể lấy phần thân nà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 phần thân JSON có unique_id của tài khoản dịch vụ (như được xác định trong phần Quản lý danh tính và quyền truy cập (IAM)), roleId (như mô tả trong phần Lấy vai trò hiện có) và scope_type.
Để chỉ định vai trò cho một nhóm, hãy thêm phần nội dung JSON có group_id của nhóm. Bạn có thể lấy phần nội dung này từ groups.get(), roleId (như mô tả trong phần Lấy các 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 vai trò được chỉ định có điều kiện

Bạn có thể cấp vai trò để thực hiện các hành động đáp ứng các điều kiện cụ thể. Hiện tại, chỉ có hai đ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 được đặt, condition sẽ chỉ có hiệu lực khi tài nguyên đang được truy cập đáp ứng điều kiện. Nếu condition trống, vai trò (roleId) sẽ được áp dụng cho đối tượng (assignedTo) ở phạm vi (scopeType) một cách vô điều kiện.

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

Thêm phần nội dung JSON có user_id của người dùng. Bạn có thể lấy phần nội dung nà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à các chuỗi này chỉ hoạt động với vai trò quản trị viên tạo sẵn của Trình chỉnh sửa nhóm và Trình đọc nhóm. Các điều kiện này tuân theo cú pháp điều kiện của 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'"
}