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 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/".
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.
{
"DATA_TYPE": "access",
"id": 12345,
"role_id": null,
"role_type": null,
"principal_type": "identity",
"principal": "368e91db-2294-4b32-b344-6870afb3777d",
"path": "/",
"permissions": "r"
}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:
|
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 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.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.
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.
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.
Requires the "access_manager" or "administrator" role on the endpoint.
URL |
/endpoint/<endpoint_xid>/access_list |
|---|---|
Method |
GET |
Response Body |
|
7.2. Get access rule by id
Get a single access rule for a specified endpoint by id.
Requires the "access_manager" or "administrator" effective role on the endpoint.
URL |
/endpoint/<endpoint_xid>/access/<id> |
|---|---|
Method |
GET |
Response Body |
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.
Requires the "access_manager" or "administrator" effective role on the endpoint.
URL |
/endpoint/<endpoint_xid>/access |
|---|---|
Method |
POST |
Request Body |
|
Response Body |
|
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.
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 |
|
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.
Requires the "access_manager" or "administrator" effective role on the endpoint.
URL |
/endpoint/<endpoint_xid>/access/<id> |
|---|---|
Method |
DELETE |
Request Body |
Empty |
Response Body |
|