Endpoint ACL Management

1. Overview

Shared endpoints have an associated Access Control List (ACL), and the API provides methods for reading, creating, updating and deleting access rules in the ACL. The ACL for each endpoint can have at most 1000 access rules.

The owner of the endpoint always has full read and write access to the endpoint.

Access rules are always additive, so permissions cannot be further restricted in subdirectories. For example, if a rule gives the identity read-write access to "/projects/" and another rule 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. Globus ACLs provide an additional layer on top of local permissions to simplify collaboration among identities.

1.1. Linked Identities

When an operation is performed against an endpoint using Globus access rules, it will use access rules for all the linked identities and groups associated with the Globus Auth account.

2. ACL Management Permission and Delegation

ACL management permissions are based on the "administrator", "restricted_administrator", and "access_manager" effective roles. See Endpoint Roles for more information or role assignment.

An "administrator" has full permissions to manage the ACL, and assigning additional "administrator" or "access_manager" roles for managing the ACL.

A "restricted_administrator" has permission to view and delete permissions in the ACL, but cannot grant themselves data access by creating or editing permissions or assigning additional roles.

An "access_manager" has full permissions to manager the ACL, but cannot assign new roles.

Identities and groups with an "access_manager" or "administrator" role assignment on an endpoint also have implicit "rw" permission on "/". This is visible in the access list, but the implicit rules can’t be fetched, updated or deleted using any other part of the acl API. The Endpoint Roles API should be used to manipulate role assignments. Note that access rules from roles can only have principal_type of "identity" or "group", and will have role_id set instead of id, for use with the Endpoint Roles API. Access rule ids are not guaranteed to be unique from role ids, so passing a role_id to the acl API could result in a "NotFound" error or in an unrelated access rule being returned.

3. Document Type

3.1. Access Document Type

ACL management resources use the "access" document type, which represents a single access rule in the ACL.

Access Document Example
{
    "DATA_TYPE": "access",
    "id": 12345,
    "role_id": null,
    "role_type": null,
    "principal_type": "identity",
    "principal": "368e91db-2294-4b32-b344-6870afb3777d",
    "path": "/",
    "permissions": "r",
    "create_time": "2021-04-06T19:56:08+00:00"
}
Uniqueness

Attempting to create an access rule with the same (principal_type, principal, path) as an existing rule in the endpoint’s ACL 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.

id

string

Unique id for this access rule. Implicit access rules from role assignments will have a null id, see role_id.

principal_type

string

Type of principal that the rule applies to. One of "identity", "group", or "all_authenticated_users" or "anonymous".

principal

string

The subject of the access rule; 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

path

string

Absolute path to a directory the access rule applies to. The path must begin and end with a slash, and can’t contain un-normalized components "/../" or "/./". GridFTP endpoints and shared endpoints hosted on GridFTP endpoints also support home directory relative paths beginning with "/~/". 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

How much permission to grant the principal specified in principal_type and principal. Either read-only, specified as "r", or read-write, specified as "rw".

role_id

string

For an implicit access rule from a role assignment, this will be set to the id of the role. null for standard access rules. This can be used to manipulate the corresponding role using the Endpoint Roles API.

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

create_time

ISO 8601 datetime string

The time when this access rule was created. Will be null for implicit access rules.

notify_email

string

When creating an identity rule, 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 access rule, and can’t be set on update or other rule 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.

3.1.2. Access Rule Types

3.1.3. Identity Access Rule

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

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

Group Access Rule

Group access rules apply to all Globus users in a Globus group. Groups can be created and discovered with the Nexus API. In the access rules, they are indicated by the group id, not by the group name which is not necessarily unique.

Note
Group ids are not validated; it is the responsibility of the client to ensure the id is correct via the Group API in Nexus. Also if the group is deleted, the rule will no longer provide any access but will stay in the ACL until deleted by the user or client application.
All Authenticated Users Access Rule

These rules grant access to all Globus users. This can be used to share data with everyone, but still allows monitoring of how many people are accessing the data.

Anonymous Access Rule

These rules grant access to anyone, including both authenticated Globus users and anonymous users who do not have a Globus account or haven’t authenticated. The anonymous access is via public HTTP servers running at the endpoint, alongside the GridFTP server.

3.1.4. Migration: User and Email Access Rules

These access rule types can no longer be created, and all previously created rules of these types have been converted to "identity" type access rules.

4. Path Arguments

Name Type Description

endpoint_xid

string

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

id

int

Integer id of an access rule.

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

Code HTTP Status Description

EndpointNotFound

404

If <endpoint_xid> not found

AccessRuleNotFound

404

If access rule specified by <id> is not found

NotSupported

409

If <endpoint_xid> does not support ACLs. See the acl_available field of endpoint to determine if an endpoint supports ACLs.

PermissionDenied

403

If you do not have permissions to view or modify ACLs on <endpoint_xid>.

ServiceUnavailable

503

If the service is down for maintenance.

7. Operations

7.1. Get list of access rules

Get the list of access rules in the ACL for a specified endpoint.

Note
This list includes implicit rules roles, which can’t be manipulated directly with other operations in the acl API. The endpoint owner always has full read-write permission. See ACL Management Permissions and Delegation.
Authorization

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

URL

/endpoint/<endpoint_xid>/access_list

Method

GET

Response Body

 
{
    "length": 2,
    "endpoint": "alice#myshare",
    "DATA": [
        {
            "DATA_TYPE": "access",
            "principal_type": "identity",
            "path": "/",
            "principal": "623568a4-3960-4836-be02-09366d201bcb",
            "id": 12345,
            "role_id": null,
            "role_type": null,
            "permissions": "r",
            "create_time": "2021-04-06T19:58:11+00:00"
        },
        {
            "DATA_TYPE": "access",
            "principal_type": "group",
            "path": "/project1",
            "principal": "a2e662ac-d4bc-4ab7-aceb-8a12d2205326",
            "id": 743565,
            "role_id": null,
            "role_type": null,
            "permissions": "rw",
            "create_time": "2021-04-06T20:01:32+00:00"
        }
    ],
    "DATA_TYPE": "access_list"
}

7.2. Get access rule by id

Get a single access rule for a specified endpoint by id.

Authorization

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

URL

/endpoint/<endpoint_xid>/access/<id>

Method

GET

Response Body

Access document

7.3. Create access rule

Create a new access rule. The response contains the id of the newly created rule 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 endpoint.

URL

/endpoint/<endpoint_xid>/access

Method

POST

Request Body

 
{
    "DATA_TYPE": "access",
    "principal_type": "identity",
    "principal": "623568a4-3960-4836-be02-09366d201bcb",
    "path": "/",
    "permissions": "r",
    "notify_email": "user@example.com"
}

Response Body

 
{
    "code": "Created",
    "resource": "/endpoint/epname/access",
    "DATA_TYPE": "access_create_result",
    "request_id": "abc123",
    "access_id": 12345,
    "message": "Access rule created successfully."
}

7.3.1. Errors

Code HTTP Status Description

InvalidPath

400

If the path specified in the access rule is not valid or too long.

LimitExceeded

409

If the endpoint ACL already has the maximum number of access rules.

Exists

409

If an access rule with the same (principal_type, principal, path) already exists in the endpoint’s ACL.

7.4. Update access rule

Update the permissions on an existing access rule. Other fields (besides DATA_TYPE which must always be present) 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.
Note
If an email access rule has been claimed since the client fetched it and become a user access rule, this will update the user access rule, which has the same id.
Authorization

Requires the "access_manager" or "administrator" effective role on the endpoint.

URL

/endpoint/<endpoint_xid>/access/<id>

Method

PUT

Request Body

Access document

Response Body

 
{
    "message": "Access rule '123' permissions updated successfully",
    "code": "Updated",
    "resource": "/endpoint/user#ep1/access/123",
    "DATA_TYPE": "result",
    "request_id": "ABCdef789"
}

7.5. Delete access rule

Delete a single access rule, specified by id.

Returns a result document with code "Deleted" on success and HTTP status code 200, and an "AccessRuleNotFound" error if the rule 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 endpoint.

URL

/endpoint/<endpoint_xid>/access/<id>

Method

DELETE

Request Body

Empty

Response Body

 
{
    "message": "Access rule '123' deleted successfully",
    "code": "Deleted",
    "resource": "/endpoint/user#ep1/access/123",
    "DATA_TYPE": "result",
    "request_id": "ABCdef789"
}