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

Quản lý vai trò

API Thư mục 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 bằng các đặc quyền để giới hạn quyền truy cập của quản trị viên cụ thể hơn so với những vai trò tạo sẵn mà Google Workspace cung cấp. 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 một miền Google Workspace. Được biểu thị bằng tài nguyên Privilege. Không có dữ liệu cố đị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 hoạt động nhất định. Được biểu thị bằng tài nguyên Role.
Giao 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 trong Cloud Identity 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.

Các giới hạn đối với vai trò và vai trò chỉ định vai trò

Bạn chỉ có thể tạo một số vai trò hoặc vai trò tuỳ chỉnh có giới hạn. Vì vậy, nếu gần đạt đến giới hạn, hãy hợp nhất hoặc xoá các vai trò hoặc vai trò đó để không vượt quá giới hạn. Vai trò và 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 500 vai trò được chỉ định 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 350 vai trò trong tổ chức gốc và 400 vai trò trong một đơn vị tổ chức khác mà bạn đã xác định, chẳng hạn như một phòng ban của một công ty. Tất cả vai trò quản trị viên tạo sẵn trong Google Workspace đều được mặc định hoạt động trong phạm vi toàn tổ chức. Tìm hiểu thêm về giới hạn về đặc quyền có thể 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 cho các nhóm:

Bạn có thể chỉ định vai trò bất kỳ, 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 trong toàn đơn vị tổ chức 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 chỉ nên giới hạn tư cách thành viên nhóm đối với người dùng trong tổ chức của mình. Bạn có thể thêm người dùng từ bên ngoài tổ chức của mình, nhưng họ có thể không có được đặc quyền của vai trò. Để biết thông tin chi tiết, hãy xem phần 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 500 vai trò trong một đơn vị tổ chức, thì 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 một vai trò cho nhóm đó. Việc chỉ định vai trò trong nhóm có thêm một số hạn chế – 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 trên Bảng điều khiển dành cho quản trị viên của Google

Để chỉ định vai trò cho người dùng có quyền 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 thêm một số đặc quyền. 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, không chỉ cần có đặc quyền USERS_CREATE, mà 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 tới các cấp đặ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 - 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.

Nhận danh sách các đặc quyền của miền

Để xem danh sách được phân trang gồm 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 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
        }
      ]
    },
    ...
  ]
}

Nhận các vai trò hiện tại

Để nhận danh sách các vai trò hiện có, hãy sử dụng yêu cầu GET sau và thêm 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 có vai trò trong miền của riêng bạn, 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ò của một khách hàng, hãy sử dụng mã khách hàng mà bạ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ả vai trò được chỉ định

Để xem danh sách được phân trang gồm tất cả các vai trò được chỉ định 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ột 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 được chỉ định 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ý đượ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ề mọi 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ả vai trò gián tiếp được chỉ định

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

Có thể API này sẽ trả về kết quả trống kèm theo 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 được chỉ định 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ý đượ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ị nhận dạng 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ề mọi vai trò được chỉ định trong miền và xác định 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 vai trò mới, hãy sử dụng yêu cầu POST sau 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 mỗi đặc quyền sẽ được cấp 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 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 một vai trò, hãy sử dụng phương thức POST sau và đưa vào hoạt động uỷ quyền như mô tả trong bài viết Uỷ quyền yêu cầu.

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

Bạn có thể cấp vai trò để thực hiện những hành động đáp ứng các điều kiện cụ thể. Hiện tại, chúng tôi chỉ hỗ trợ 2 điều kiện:

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

Khi bạn đặt condition, thuộc tính này 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 tác nhân (assignedTo) ở phạm vi (scopeType) 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à thêm quyền uỷ quyền được mô tả trong phần Uỷ quyền yêu cầu.

Thêm nội dung JSON chứa 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 Nhận các vai trò hiện có và condition. Bạn phải sử dụng 2 chuỗi điều kiện đúng nguyên văn như bên dưới và chỉ hoạt động với các vai trò quản trị viên tạo sẵn cho 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 Cloud IAM.

Yêu cầu

Chỉ á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'"
}

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