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"
        }
    ]
}

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"
}