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/".
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.
{
"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"
}
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 |
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
|
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
|
role_id |
string |
For an implicit access rule from a role
assignment, this will be set to the id of the role.
|
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 |
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.
4. Path Arguments
Name | Type | Description |
---|---|---|
endpoint_xid |
string |
The |
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
The error code
can be found in the HTTP response body JSON document. See
error overview
.
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 |
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 an "access_manager", "administrator", or "restricted_administrator" effective 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 an "access_manager", "administrator", or "restricted_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.
id
field of the access document must be omitted in create requests.
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
( |
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.
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.
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 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 |
|