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