Endpoint Roles
1. Overview
The identity that created an endpoint (the "owner") has full control over every aspect of the endpoint, including the attributes, the ACL, and role assignments. Roles allow the owner to delegate a subset of these capabilities to other identities or groups. Note that assigning roles requires that the endpoint is managed.
Roles are assigned to a "principal", which can be a Globus Auth identity or a Globus group.
Any user can get a list of effective roles they have on an endpoint from the my_effective_roles field of the endpoint document.
1.1. Supported Roles
- Role "administrator"
-
The endpoint owner has this role implicitly, and a principal with this role on the endpoint has the same capabilities as the owner:
-
modify the endpoint definition
-
delete the endpoint
-
view, add, update, and delete role assignments on the endpoint
-
view the endpoint even if it’s private
-
the endpoint will be visible in search results even if it’s private
-
perform filesystem operations on the (ls, mkdir, rename, transfer, delete) even if it’s private
-
create a shared endpoint on a Globus Connect Personal endpoint if one of the user’s linked identities is a member of a plus group
-
all capabilities of the "access_manager" role
-
all capabilities of the "activity_manager" role
-
- Role "access_manager"
-
The principal can view, add, and delete all access rules on the endpoint. This role is only supported on endpoints that support access control lists. Adding a principal with this role implicitly gives the principal read-write access to the endpoint, equivalent to an access rule with permissions "rw" on path "/". Note that this implicit access rule will be visible when calling Get list of access rules, with role_id set instead of id. Removing the implicit access rule requires deleting the corresponding endpoint role, and the access rule can’t be modified with the acl API.
- Role "activity_manager"
-
The principal can view and control tasks and other endpoint activity to or from the endpoint. This includes all operations in the Advanced Endpoint Management API (view, pause/resume, cancel). Having this role grants all capabilities of the "activity_monitor" role to the principal. If set on a host endpoint, this role is inherited by all hosted shared endpoints.
- Role "activity_monitor"
-
The principal can view tasks and other activity to or from the endpoint. This includes all read-only task related resources in the Advanced Endpoint Management API, like events and task pause info, read-only view of pause rules, and read-only view of the ACL on shared endpoints. If set on a host endpoint, this role is inherited by all hosted shared endpoints. This role also grants visibility on endpoints even if they are private. The private endpoint visibility is supported by the get endpoint as admin resource in the Advanced Endpoint Management API, Endpoint Search, get endpoint, get endpoint server, and get endpoint server list. If the endpoint is private, submitting transfers and performing filesystem operations will still return a "PermissionDenied" error - only visibility on the endpoint document and servers is granted.
1.2. Effective Roles
The role_list resource returns "explicit" roles added using the Create endpoint role resource, but a user can have additional "effective" roles, granted by having other roles on the endpoint or it’s host, or by being the owner of the endpoint. The my_effective_roles field of the endpoint document will include all effective roles, not just the explicit roles returned in the role_list. Authorization decisions are based on the effective roles in my_effective_roles, rather than the explicit role list. In detail:
-
The owner of an endpoint has the effective roles "administrator", "access_manager", and "activity_manager".
-
A user with the "administrator" role will also have the effective roles "access_manager" and "activity_manager".
-
A user with the "activity_monitor" role on a host endpoint will have the "activity_monitor" effective roles on all hosted shared endpoints, and a user with the "activity_manager" role on a host endpoint will have the "activity_manager" role on all hosted shared endpoints.
-
A user with the "activity_manager" effective role on an endpoint will also have the "activity_monitor" effective role on the endpoint.
-
If the endpoint is made unmanaged, then users with the "activity_manager" or "activity_monitor" roles will no longer have the corresponding effective roles (i.e. the roles will become inactive), until the endpoint is made managed again. Note that in contrast the "administrator" role will continue to remain active even when the endpoint is made unmanaged, but no new roles can be added.
2. Document Types
2.1. Role Document
The "role" document type represents the assignment of a role on the endpoint to a Globus identity or group.
{
"DATA_TYPE": "role",
"id": "1405823f-0597-4a16-b296-46d4f0ae4b15",
"principal_type": "identity",
"principal": "ce5a2f3a-9aa0-4d8b-a062-63c61878a10d",
"role": "access_manager"
}2.1.1. Role Document Fields
Fields are required for create unless otherwise specified.
| Field Name | JSON Type | Description |
|---|---|---|
DATA_TYPE |
string |
Always has value "role" to indicate this document type. Optional in create requests. |
id |
string |
Globally unique id string for this role assignment. This is system generated and should not be included in create requests. |
principal_type |
string |
Type of principal that the rule applies to. One of "identity" or "group". |
principal |
string |
The subject of the access rule; the interpretation depends on principal_type:
|
role |
string |
The role to assign to the principal. See the Supported Roles section above. |
3. Path Arguments
| Name | Type | Description |
|---|---|---|
endpoint_xid |
string |
The id field of the endpoint, or for backward compatibility the canonical_name of the endpoint. The latter is deprecated, and all clients should be updated to use id. |
role_id |
string |
Unique identifier for a role assignment. |
4. Common Query Parameters
| Name | Type | Description |
|---|---|---|
fields |
string |
Comma separated list of fields to include in the response. This can be used to save bandwidth on large list responses when not all fields are needed. |
5. Common Errors
| Code | HTTP Status | Description |
|---|---|---|
EndpointNotFound |
404 |
If <endpoint_xid> not found |
RoleNotFound |
404 |
If <role_id> not found |
PermissionDenied |
403 |
If user does not have privileges to get, modify, or delete the specified role(s). |
Exists |
409 |
If a role assignment with the same principal and role already exists. |
Conflict |
409 |
If the endpoint is not managed. |
NotSupported |
409 |
If the endpoint does not support the specified role. |
LimitExceeded |
409 |
If the endpoint role list already has the maximum of 100 role assignments. |
ServiceUnavailable |
503 |
If the service is down for maintenance. |
6. Operations
6.1. Get list of endpoint roles
Get a list of role assignments on an endpoint. Since an endpoint can have at most 100 roles, this list is not paged and will return at most 100 roles.
Requires the "administrator" effective role.
URL |
/endpoint/<endpoint_xid>/role_list |
|---|---|
Method |
GET |
Response Body |
|
6.2. Create endpoint role
Assign a role to an identity or group for the given endpoint. On success returns a copy of the created role with the system generated id added.
Requires the "administrator" effective role, and that the endpoint is managed.
URL |
/endpoint/<endpoint_xid>/role |
|---|---|
Method |
POST |
Request Body |
|
Response Body |
|
6.3. Get endpoint role by id
Get a single role assignment by id.
Requires the "administrator" effective role.
URL |
/endpoint/<endpoint_xid>/role/<role_id> |
|---|---|
Method |
GET |
Response Body |
|
6.4. Delete endpoint role by id
Delete a single role assignment by id. Returns a result document on success.
Requires the "administrator" effective role, and that the endpoint is managed.
URL |
/endpoint/<endpoint_xid>/role/<role_id> |
|---|---|
Method |
DELETE |
Response Body |
|