Endpoint ACL Management

1. Overview

Shared endpoints and owner activated S3 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 100 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 or S3 bucket 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

The owner always has permission to manage the ACL on an endpoint. The owner can also delegate ACL management to other identities or groups. This is done by assigning the "access_manager" or "administrator" role on the endpoint. See the Endpoint Roles documentation. Note that identities that have the "access_manager" role can’t further delegate ACL management to other identities, but the "adminstrator" role can.

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

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

Note:S3 endpoints do not currently support anonymous access, so anonymous rules will be identical to "all_authenticated_users" rules.

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 the "access_manager" or "administrator" 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" }, { "DATA_TYPE": "access", "principal_type": "group", "path": "/project1", "principal": "a2e662ac-d4bc-4ab7-aceb-8a12d2205326", "id": 743565, "role_id": null, "role_type": null, "permissions": "rw" } ], "DATA_TYPE": "access_list" }

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"
        },
        {
            "DATA_TYPE": "access",
            "principal_type": "group",
            "path": "/project1",
            "principal": "a2e662ac-d4bc-4ab7-aceb-8a12d2205326",
            "id": 743565,
            "role_id": null,
            "role_type": null,
            "permissions": "rw"
        }
    ],
    "DATA_TYPE": "access_list"
}

7.2. Get access rule by id

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

Authorization

Requires the "access_manager" or "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 of 100 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 the "access_manager" or "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" }

Transfer API Menu

Endpoint ACL Management

1. Overview

1.1. Linked Identities

2. ACL Management Permission and Delegation

3. Document Type

3.1. Access Document Type

3.1.1. Fields

3.1.2. Access Rule Types

3.1.3. Identity Access Rule

Group Access Rule

All Authenticated Users Access Rule

Anonymous Access Rule

3.1.4. Migration: User and Email Access Rules

4. Path Arguments

5. Common Query Parameters

6. Common Errors

7. Operations

7.1. Get list of access rules

7.2. Get access rule by id

7.3. Create access rule

7.3.1. Errors

7.4. Update access rule

7.5. Delete access rule