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.

Role Document Example

{
  "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`: Type "identity" a Globus Auth identity id Type "group" a Globus group uuid
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.

Authorization

Requires the "administrator" effective role.

URL	/endpoint/<endpoint_xid>/role_list
Method	GET
Response Body	{ "DATA_TYPE": "role_list", "DATA": [ { "DATA_TYPE": "role", "id": "06fa8417-aa29-4b7a-a315-27868f8189dc", "principal_type": "identity", "principal": "ce5a2f3a-9aa0-4d8b-a062-63c61878a10d", "role": "access_manager" }, { "DATA_TYPE": "role", "id": "0f683bc9-0c8a-4fcf-813b-2a1b7bc171a1", "principal_type": "group", "principal": "594ef8be-21e6-4137-969a-d9d2c4d46d92", "role": "access_manager" } ] }

URL

/endpoint/<endpoint_xid>/role_list

Method

GET

Response Body

{

    "DATA_TYPE": "role_list",
    "DATA": [
        {
            "DATA_TYPE": "role",
            "id": "06fa8417-aa29-4b7a-a315-27868f8189dc",
            "principal_type": "identity",
            "principal": "ce5a2f3a-9aa0-4d8b-a062-63c61878a10d",
            "role": "access_manager"
        },
        {
            "DATA_TYPE": "role",
            "id": "0f683bc9-0c8a-4fcf-813b-2a1b7bc171a1",
            "principal_type": "group",
            "principal": "594ef8be-21e6-4137-969a-d9d2c4d46d92",
            "role": "access_manager"
        }
    ]
}

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.

Authorization

Requires the "administrator" effective role, and that the endpoint is managed.

URL	/endpoint/<endpoint_xid>/role
Method	POST
Request Body	{ "DATA_TYPE": "role", "principal_type": "identity", "principal": "ce5a2f3a-9aa0-4d8b-a062-63c61878a10d", "role": "access_manager" }
Response Body	{ "DATA_TYPE": "role", "id": "e1d00e93-e93e-4dc0-9550-faeba473d6c0", "principal_type": "identity", "principal": "ce5a2f3a-9aa0-4d8b-a062-63c61878a10d", "role": "access_manager" }

6.3. Get endpoint role by id

Get a single role assignment by id.

Authorization

Requires the "administrator" effective role.

URL	/endpoint/<endpoint_xid>/role/<role_id>
Method	GET
Response Body	{ "DATA_TYPE": "role", "id": "e1d00e93-e93e-4dc0-9550-faeba473d6c0", "principal_type": "identity", "principal": "ce5a2f3a-9aa0-4d8b-a062-63c61878a10d", "role": "access_manager" }

6.4. Delete endpoint role by id

Delete a single role assignment by id. Returns a result document on success.

Authorization

Requires the "administrator" effective role, and that the endpoint is managed.

URL

/endpoint/<endpoint_xid>/role/<role_id>

Method

DELETE

Response Body

{
    "DATA_TYPE": "result",
    "code": "Deleted",
    "message": "Role assignment 'c67b666f-e1ad-4f67-af2c-48340dd12ada' deleted successfully",
    "resource": "/endpoint/user#ep1/role/123",
    "request_id": "ABCdef789"
}

Transfer API Menu

Endpoint Roles

1. Overview

1.1. Supported Roles

1.2. Effective Roles

2. Document Types

2.1. Role Document

2.1.1. Role Document Fields

3. Path Arguments

4. Common Query Parameters

5. Common Errors

6. Operations

6.1. Get list of endpoint roles

6.2. Create endpoint role

6.3. Get endpoint role by id

6.4. Delete endpoint role by id