Guest Collection Permission Management

Table of Contents

1. Overview
- 1.1. Terminology
- 1.2. Linked Identities
2. Roles
3. Document Type
- 3.1. Permission Document
4. Path Arguments
5. Common Query Parameters
6. Common Errors
7. Operations

1. Overview

Both Globus Connect Server and Globus Connect Personal guest collections use permissions managed in the Transfer service to give collection access to users to users who do not have a local account on the parent mapped collection. The Transfer API provides resources for reading, creating, updating and deleting permissions. Each guest collection can have at most 1000 permissions.

Transfer-managed permissions are always additive, so permissions cannot be further restricted in subdirectories. For example, if a permission gives an identity read-write access to "/projects/" and another permission gives read-only access to "/projects/study1/", then the identity is still granted full read-write access to "/projects/study1/".

Note

Access is still subject to the local filesystem permissions for the owner of the guest collection. Transfer-managed permissions provide an additional layer on top of local permissions to simplify collaboration among identities.

1.1. Terminology

The set of permissions on a guest collection was previously referred to as an Access Control List, or ACL. The Transfer API itself will sometimes refer to an individual permission as an "access rule", "rule", "access", or "acl" in URLs, documents, and messages.

1.2. Linked Identities

When an operation is performed against a guest collection using Transfer-managed permissions, it will use permissions for all the linked identities and groups associated with the Globus Auth account.

2. Roles

Managing permissions on a guest collection requires an "administrator", "restricted_administrator", or "access_manager" effective role on the guest collection:

An "administrator" has the ability to view, create, edit, and delete permissions on the guest collection, and can also assign additional "administrator" or "access_manager" roles.
A "restricted_administrator" has the ability to view and delete permissions on the guest collection, but cannot grant themselves data access by creating or editing permissions or assigning additional roles.
An "access_manager" has the ability to view, create, edit, and delete permissions on the guest collection, but cannot assign new roles.

Identities and groups with an "access_manager" or "administrator" effective role on a guest collection also have an implicit "rw" permission on "/". These are visible in the permission list, but the implicit permissions can’t be fetched, updated or deleted using the below permission resources. The Roles resources should be used to manipulate role assignments. Note that permissions from roles can only have principal_type of "identity" or "group", and will have role_id set instead of id, for use with the Roles resources.

3. Document Type

3.1. Permission Document

A permission document represents a single permission on the guest collection. The DATA_TYPE is "access" due to previous terminology.

Permission Document Example

{
  "DATA_TYPE": "access",
  "create_time": "2021-04-06T19:58:11+00:00",
  "expiration_date": null,
  "id": "ca761528-90da-11ec-bad3-cd8db799a66a",
  "path": "/",
  "permissions": "r",
  "principal": "623568a4-3960-4836-be02-09366d201bcb",
  "principal_type": "identity",
  "role_id": null,
  "role_type": null
}

Uniqueness

Attempting to create a permission with the same principal_type, principal, and path as an existing permission on the guest collection will result in an "Exists" error.

3.1.1. Fields

Field Name	JSON Type	Description
DATA_TYPE	string	Always has value "access" to indicate this document type.
create_time	ISO 8601 datetime string	The time when this permission was created. Will be null for implicit permissions.
expiration_date	ISO 8601 datetime string	If not `null`, the time at which the permission will be removed. Can only be set on High Assurance collections. If not specified on creation and acl_max_expiration_period_mins is set on the collection, this field will be set to (the current time + `acl_max_expiration_period_mins`). If specified, must be earlier than (the current time + `acl_max_expiration_period_mins`). When `acl_max_expiration_period_mins` is set on both the guest collection and mapped collection, the smaller value of the two will be used.
id	string	Unique id for this permission. Implicit permissions from role assignments will have a null `id`, see `role_id`.
notify_email	string	When creating an identity permission, clients can optionally specify a valid email address to send notification to. This address should be known to belong to the identity being shared to, for example using Globus Auth to get the address associated with the identity id. Note that this will not be persisted as part of the permission, and can’t be set on update or other permission types.
notify_message	string	If `notify_email` is set, this can be set to include a custom message in the notification email. Max 2048 characters.
path	string	Absolute path to a directory the permission applies to. The path must begin and end with a slash, and can’t contain un-normalized components "/../" or "/./". paths beginning with "/~/" will be relative to the home directory if one exists on the file system. The path is limited to 2000 characters after encoding; in practice this means 2000 ascii characters and slightly less when unicode is present and must be encoded.
permissions	string	What permissions to grant the principal specified in `principal_type` and `principal`. Either read-only, specified as "r", or read-write, specified as "rw".
principal	string	The subject of the permission; the interpretation depends on `principal_type`: Type "identity" a Globus identity uuid Type "group" a Globus group uuid Type "all_authenticated_users" an empty string Type "anonymous" an empty string
principal_type	string	Type of principal that the permission applies to. One of "identity", "group", "all_authenticated_users", or "anonymous".
role_id	string	For an implicit permission from a role assignment, this will be set to the id of the role. `null` for standard permissions. This can be used to manipulate the corresponding role using the Roles resources.
role_type	string	If role_id is null, this is also null. Otherwise, this is the type of the role, either "administrator" or "access_manager".

3.1.2. Permission Types

3.1.3. Identity permissions

Identity permissions apply to a single identity, indicated by a Globus Auth identity id.

When an identity permission is added, a notification email can optionally be sent to the email address associated with that user’s Globus account.

Group permissions

Group permissions specify a Globus group by id, and apply to all users in that group. Groups can be created and discovered with the Groups API.

Note

Group ids are not validated; it is the responsibility of the client to ensure the id is correct via the Groups API. Also if the group is deleted, the permission will no longer provide any access but will stay on the guest collection until deleted.

All Authenticated Users permissions

These permissions grant access to all users who have authenticated with Globus Auth. This can be used to share data with everyone, but still allows monitoring of who is accessing the data.

Anonymous permissions

These permissions grant access to anyone, including both users who have authenticated with Globus Auth and anonymous users without Globus Auth issued access tokens. Anonymous access is currently only possible via public HTTPs access to Globus Connect Server guest collections.

4. Path Arguments

Name	Type	Description
collection_id	string	The `id` of the guest collection.
permission_id	string	UUID of the permission.

5. Common Query Parameters

Name	Description
fields	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.

6. 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 <collection_id> not found.
AccessRuleNotFound	404	If <permission_id> is not found.
NotSupported	409	If <collection_id> is not a guest collection.
PermissionDenied	403	If you do not have permissions to view or modify permissions on <collection_id>.
ServiceUnavailable	503	If the service is down for maintenance.

7. Operations

7.1. Get list of permissions

Get the list of permissions for a specified guest collection.

Note

This list includes implicit permissions based on roles, which can’t be manipulated directly with other permission resources. See Roles.

Authorization

Requires an "access_manager", "administrator", or "restricted_administrator" effective role on the guest collection.

URL	/endpoint/<collection_id>/access_list^[1]
Method	GET
Response Body	{ "DATA": [ { "DATA_TYPE": "access", "create_time": "2021-04-06T19:58:11+00:00", "id": "ca761528-90da-11ec-bad3-cd8db799a66a", "path": "/", "permissions": "r", "principal": "623568a4-3960-4836-be02-09366d201bcb", "principal_type": "identity", "role_id": null, "role_type": null }, { "DATA_TYPE": "access", "create_time": "2021-04-06T20:01:32+00:00", "id": "e94a340d-3132-4806-bb42-381cd3fb6128", "path": "/project1", "permissions": "rw", "principal": "a2e662ac-d4bc-4ab7-aceb-8a12d2205326", "principal_type": "group", "role_id": null, "role_type": null } ], "DATA_TYPE": "access_list", "endpoint": "f90e8770-9203-4393-ae45-2afbcbf99c4d" }

URL

/endpoint/<collection_id>/access_list^[1]

Method

GET

Response Body

{
  "DATA": [
    {
      "DATA_TYPE": "access",
      "create_time": "2021-04-06T19:58:11+00:00",
      "id": "ca761528-90da-11ec-bad3-cd8db799a66a",
      "path": "/",
      "permissions": "r",
      "principal": "623568a4-3960-4836-be02-09366d201bcb",
      "principal_type": "identity",
      "role_id": null,
      "role_type": null
    },
    {
      "DATA_TYPE": "access",
      "create_time": "2021-04-06T20:01:32+00:00",
      "id": "e94a340d-3132-4806-bb42-381cd3fb6128",
      "path": "/project1",
      "permissions": "rw",
      "principal": "a2e662ac-d4bc-4ab7-aceb-8a12d2205326",
      "principal_type": "group",
      "role_id": null,
      "role_type": null
    }
  ],
  "DATA_TYPE": "access_list",
  "endpoint": "f90e8770-9203-4393-ae45-2afbcbf99c4d"
}

7.2. Get permission by id

Get a single permission for a specified guest collection by id.

Authorization

Requires an "access_manager", "administrator", or "restricted_administrator" effective role on the guest collection.

URL	/endpoint/<collection_id>/access/<permission_id>^[1]
Method	GET
Response Body	Permission document

7.3. Create permission

Create a new permission on a specified guest collection. The response contains the id of the newly created permission in the access_id field. Returns http status 201 and a result document with code "Created" on success.

The notify_email and notify_message fields are optional and not persisted as part of the access document.

Note

The id field of the access document must be omitted in create requests.

Authorization

Requires the "access_manager" or "administrator" effective role on the guest collection.

URL	/endpoint/<collection_id>/access^[1]
Method	POST
Request Body	`{ "DATA_TYPE": "access", "notify_email": "user@example.com", "path": "/", "permissions": "r", "principal": "623568a4-3960-4836-be02-09366d201bcb", "principal_type": "identity" }`
Response Body	`{ "DATA_TYPE": "access_create_result", "access_id": "ca761528-90da-11ec-bad3-cd8db799a66a", "code": "Created", "message": "Access rule created successfully.", "request_id": "ABCdef789", "resource": "/endpoint/f90e8770-9203-4393-ae45-2afbcbf99c4d/access" }`

7.3.1. Errors

Code	HTTP Status	Description
InvalidPath	400	If the path specified in the permission is not valid or too long.
LimitExceeded	409	If the guest collection already has the maximum number of permissions.
Exists	409	If a permission with the same `principal_type`, `principal`, and `path` already exists on the guest collection.

7.4. Update permission

Update the permissions on an existing permission on a specified guest collection. Other fields may be omitted. If the id is present it must match the id in the URL.

Returns a result document with code "Updated" on success, but checking that the HTTP status code is 2xx is sufficient to verify success.

Note

This may support updating path or other fields in the future, so clients should make sure to use the correct value for the other fields or omit them entirely.

Authorization

Requires the "access_manager" or "administrator" effective role on the guest collection.

URL	/endpoint/<collection_id>/access/<permission_id>^[1]
Method	PUT
Request Body	Access document
Response Body	`{ "DATA_TYPE": "result", "code": "Updated", "message": "Access rule 'ca761528-90da-11ec-bad3-cd8db799a66a' permissions updated successfully", "request_id": "ABCdef789", "resource": "/endpoint/f90e8770-9203-4393-ae45-2afbcbf99c4d/access/ca761528-90da-11ec-bad3-cd8db799a66a" }`

7.5. Delete permission

Delete a single permission, specified by id.

Returns a result document with code "Deleted" on success and HTTP status code 200, and an "AccessRuleNotFound" error if the permission has already been deleted. If the client is using a retry loop, both should be accepted as success in case the first successful attempt is disconnected after the request is processed but before the response is received by the client.

Authorization

Requires an "access_manager", "administrator", or "restricted_administrator" effective role on the guest collection.

URL	/endpoint/<collection_id>/access/<permission_id>^[1]
Method	DELETE
Request Body	Empty
Response Body	`{ "DATA_TYPE": "result", "code": "Deleted", "message": "Access rule 'ca761528-90da-11ec-bad3-cd8db799a66a' deleted successfully", "request_id": "ABCdef789", "resource": "/endpoint/f90e8770-9203-4393-ae45-2afbcbf99c4d/access/ca761528-90da-11ec-bad3-cd8db799a66a" }`

1. This use of the term "endpoint" is a case of legacy endpoint terminology and can also/exclusively refer to collections