Roles

1. Overview

The Globus identity that created an endpoint or collection (the "owner") has full control over every aspect of the entity, including the attributes, permissions, 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 or collection is subscribed.

For Globus Connect Personal collections, the owner identity will be the Globus user identity specified when setting up the mapped collection, and additional roles are created through the Transfer API resources specified below.

For Globus Connect Server, the owner of the endpoint and collection definitions in Transfer will be the Globus Client Identity specified when setting up the host endpoint, and roles are read-only in transfer. Globus Connect Server roles are managed through the Globus Connect Server Manager API.

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 or collection from the my_effective_roles field of the endpoint or collection document.

1.1. Supported Roles

Role "administrator"

The endpoint or collection owner has this role implicitly, and a principal with this role on the entity has the same capabilities as the owner:

  • modify the entity definition

  • delete the entity

  • view, add, update, and delete role assignments on the entity

  • view the entity even if it’s private

  • the entity 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

  • 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 entities 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 entity, its roles, and its permissions even if the entity is private

  • modify or delete the entity definition

  • view and delete role assignments on the entity

  • view and delete permissions on a guest collection

Role "access_manager"

The principal can view, add, and delete all access rules on the collection. This role is only supported on guest collections. Adding a principal with this role implicitly gives the principal read-write access to the collection, equivalent to "rw" permissions on path "/". Note that this implicit permission will be visible when calling Get permission list, with role_id set instead of id. Removing the implicit permission requires deleting the corresponding role, and the access rule can’t be modified with the permission resources.

Role "activity_manager"

The principal can view and control tasks and other collection activity to or from the collection. This includes all operations in the Advanced Collection Management resources (view, pause/resume, cancel). Having this role grants all capabilities of the "activity_monitor" role to the principal. This role grants visibility on collections even if they are private. This role is inherited by child collections, see effective roles for details.

Role "activity_monitor"

The principal can view tasks and other activity to or from the collection. This includes all read-only task related resources in the Advanced Collection Management resources, like events and task pause info, read-only view of pause rules, and read-only view of the guest collection’s permissions. This role also grants visibility on collections even if they are private. The private collection visibility is supported by the get endpoint or collection resource in the Advanced Collection Management resources, Endpoint and Collection Search, get endpoint or collection, get server, and get server list. If the collection is private, submitting transfers and performing filesystem operations will still return a "PermissionDenied" error - only visibility on the collection document and servers is granted. This role is inherited by child collections, see effective roles for details.

1.2. Effective Roles

The role_list resource returns "explicit" roles added using the Create role resource, but a user can have additional "effective" roles, granted by having other roles on the endpoint or collection or a parent of that entity. The my_effective_roles field of the endpoint or collection 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 collection is defined as either a guest collection created off a parent mapped collection or a Globus Connect Server mapped collection created off a parent Globs Connect Server host endpoint. In detail:

  • The owner of an endpoint or collection will always have an effective "administrator", role on that entity.

  • A user with an effective "administrator" role on an endpoint or collection will have effective "access_manager", "activity_manager", and "activity_monitor" roles on that entity, along with effective "restricted_administrator", "activity_manager" and "activity_monitor" roles on all children of that entity.

  • A user with an effective "activity_manager" role on an endpoint or collection will also have an effective "activity_monitor" role on that entity, along with effective "activity_manager" and "activity_monitor" roles on all children of that entity.

  • A user with an effective "activity_monitor" role on an endpoint or collection will also have effective "activity_monitor" roles on all children of that entity.

  • If the endpoint or collection is unsubscribed, then "activity_manager" and "activity_monitor" effective roles will become inactive and will no longer grant any permissions until the entity is subscribed again. Note that in contrast the "administrator", "restricted_administrator", and "activity_manager" effective roles will continue to remain active even when the entity is unsubscribed, 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 an endpoint or collection 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 role; 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_or_collection_id

string

The id field of the endpoint or collection.

collection_id

string

The id field of the collection.

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[1]

404

If <endpoint_or_collection_id> 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 or collection is not subscribed.

NotSupported

409

If the endpoint or collection does not support the specified role.

LimitExceeded

409

If the 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 roles

Get a list of role assignments on an endpoint or collection. Since an endpoint or collection can have at most 100 explicit roles, this list is not paged and will return at most 100 roles.

Authorization

Requires an "administrator" or "restricted_administrator" effective role

URL

/endpoint/<endpoint_or_collection_id>/role_list[1]

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. Get role by id

Get a single endpoint or collection role assignment by id.

Authorization

Requires an "administrator" or "restricted_administrator" effective role on the endpoint or collection.

URL

/endpoint/<endpoint_or_collection_id>/role/<role_id>[1]

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.3. Create Globus Connect Personal collection role

Assign a role to an identity or group for the given Globus Connect Personal collection. On success returns the created role document with the system generated id added.

Authorization

Requires the "administrator" effective role, and that the collection is subscribed.

URL

/endpoint/<collection_id>/role[1]

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.4. Delete Globus Connect Personal collection role by id

Delete a single Globus Connect Personal collection role assignment by id. Returns a result document on success.

Authorization

Requires an "administrator" or "restricted_administrator" effective role, and that the collection is subscribed.

URL

/endpoint/<collection_id>/role/<role_id>[1]

Method

DELETE

Response Body

 
{
  "DATA_TYPE": "result",
  "code": "Deleted",
  "message": "Role assignment 'e1d00e93-e93e-4dc0-9550-faeba473d6c0' deleted successfully",
  "request_id": "ABCdef789",
  "resource": "/endpoint/f90e8770-9203-4393-ae45-2afbcbf99c4d/role/e1d00e93-e93e-4dc0-9550-faeba473d6c0"
}
1. This use of the term "endpoint" is a case of legacy endpoint terminology and can also/exclusively refer to collections