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 the endpoint is managed or 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 "restricted_administrator"
-
This role cannot be given explicitly, but instead is only available as an effective role on children of endpoints that the principal has the "administrator" role on, see effective roles for details. The principal can do most of what an "administrator" can do, but does not have data access, nor can it create roles or permissions that grant data access. Specifically it can:
-
view the endpoint, its roles, and its ACL even if the endpoint is private
-
modify or delete the endpoint definition
-
view and delete role assignments on the endpoint
-
view and delete permissions on the endpoint’s ACL
-
- 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 ofid
. 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. This role grants visibility on endpoints even if they are private. This role is inherited by child endpoints, see effective roles for details.
- 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. 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. This role is inherited by child endpoints, see effective roles for details.
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 a parent of that 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. A "child" of an endpoint/collection is defined
as any of the following: a shared endpoint created off a GCSv4 or GCP host,
a guest or mapped collection created off a GCSv5 host endpoint, or a guest
collection created off a mapped collection.
In detail:
-
The owner of an endpoint will always have an effective "administrator", role on that endpoint.
-
A user with an effective "administrator" role on an endpoint will have effective "access_manager", "activity_manager", and "activity_monitor" roles on that endpoint, along with effective "restricted_administrator", "activity_manager" and "activity_monitor" roles on all children of that endpoint.
-
A user with an effective "activity_manager" role on an endpoint will also have an effective "activity_monitor" role on that endpoint, along with effective "activity_manager" and "activity_monitor" roles on all children of that endpoint.
-
A user with an effective "activity_monitor" role on an endpoint will also have effective "activity_monitor" roles on all children of that endpoint.
-
If the endpoint is made unmanaged, then "activity_manager" and "activity_monitor" effective roles will become inactive and will no longer grant any permissions until the endpoint is made managed again. Note that in contrast the "administrator", "restricted_administrator", and "activity_manager" effective roles 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
|
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 |
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
The error code
can be found in the HTTP response body JSON document. See
error overview
.
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 an "administrator" or "restricted_adminsitrator" 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 an "administrator" or "restricted_adminsitrator" 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 an "administrator" or "restricted_adminsitrator" effective role, and that the endpoint is managed.
URL |
/endpoint/<endpoint_xid>/role/<role_id> |
---|---|
Method |
DELETE |
Response Body |
|