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 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. 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.

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

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.

Authorization

Requires an "administrator" or "restricted_adminsitrator" 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"
        }
    ]
}

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 an "administrator" or "restricted_adminsitrator" 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 an "administrator" or "restricted_adminsitrator" 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"
}