ACL
ACL (Access Control List) lets you control which users are allowed to perform which operations in the VK Object Storage service. Each bucket and object has its own ACL, which lists access permittees and the permissions granted to them.
The following API methods are available for ACL operations on buckets and objects:
- GetBucketACL — Get the bucket ACL.
- PutBucketACL — Set the bucket ACL.
- GetObjectACL — Get the object ACL.
- PutObjectACL — Set the object ACL.
You can set the ACL both when creating a bucket or uploading an object, and afterward. You can specify the ACL configuration in the PutBucketACL and PutObjectACL methods in two ways:
- In the request body — as an XML ACL configuration structure. This method is used only for existing buckets or objects.
- In the request headers. This method is used both when creating a bucket or uploading an object, and for existing buckets or objects.
You can use only one of these methods in a single request.
The ACL configuration in XML format contains the following elements:
-
<Owner>— contains the identifier (ID) and name (DisplayName) of the project that the bucket or object belongs to. To get theIDandDisplayName, request information about the bucket ACL. -
<Grant>— defines which permissions are granted to which grantee.<Grant>contains the<Grantee>and<Permission>elements.-
<Grantee>— specifies the access permittee using attributes:ID— the identifier of the permittee.Type— the type of the permittee:CanonicalUserorGroup.
-
<Permission>— specifies the type of permission granted.
-
Example of an XML ACL configuration structure:
<AccessControlPolicy><Owner><ID>Owner-canonical-user-ID</ID><DisplayName>owner-display-name</DisplayName></Owner><AccessControlList><Grant><Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser"><ID>Owner-canonical-user-ID</ID><DisplayName>owner-display-name</DisplayName></Grantee><Permission>FULL_CONTROL</Permission></Grant></AccessControlList></AccessControlPolicy>
The following headers are used to specify the ACL configuration in PUT requests:
x-amz-acl— assigns a preconfigured standard ACL to the bucket or object.x-amz-grant-read— sets the read permission (READ).x-amz-grant-write— sets the write permission (WRITE).x-amz-grant-read-acp— sets the ACL read permission (READ_ACP).x-amz-grant-write-acp— sets the ACL write permission (WRITE_ACP).x-amz-grant-full-control— grants full control (FULL_CONTROL).
The x-amz-acl header cannot be combined in a single request with the other headers listed above. You can either use a standard ACL or explicitly specify permittees.
Access rights to buckets and objects can be granted to the following categories of permittees:
The project is the only access permittee in VK Object Storage with the CanonicalUser type. It is automatically assigned to all buckets and objects with FULL_CONTROL permissions and is identical to the owner. This permittee cannot be deleted or changed. Permissions granted to the project apply to all VK Object Storage accounts within the project.
A predefined metagroup is an access permittee in VK Object Storage with the Group type that lets you grant separate permissions to two categories of users outside the project.
-
Authenticated Users(authenticated users) — all existing VK Object Storage accounts, from all VK Cloud projects.To grant access to the
Authenticated Usersgroup:-
When setting it via the XML structure, specify the
<URI>tag inside theGranteeblock.Example:
<URI>http://acs.amazonaws.com/groups/global/AuthenticatedUsers</URI> -
When setting it via a header, use the
urikey in its value.Example:
uri="http://acs.amazonaws.com/groups/global/AuthenticatedUsers"
-
-
All Users(all users).To grant access to the
All Usersgroup:-
When setting it via the XML structure, specify the
<URI>tag inside theGranteeblock.Example:
<URI>http://acs.amazonaws.com/groups/global/AllUsers</URI> -
When setting it via a header, use the
urikey in its value.Example:
uri="http://acs.amazonaws.com/groups/global/AllUsers"
Anonymous, unauthenticated users, if granted access, perform actions under the canonical user ID
65a011a29cdf8ec533ec3d1ccaae921c, since they do not have an account in the VK Cloud project. -
In the table below are the types of permissions that VK Object Storage supports in ACLs. For each permission, the rights it grants and the operations it allows are shown for when it is granted on a bucket and on an object.
ACL permission | Granted on a bucket | Granted on an object |
|---|---|---|
| Lists the objects in the bucket HeadBucket, ListMultiparts, ListObjects, ListParts | Reads the object's content and metadata GetObject, HeadObject |
| Creates, overwrites, and deletes any object in the bucket AbortMultipartUpload, CompleteMultipartUpload, InitiateMultipartUpload, UploadPart, PutObject, DeleteObject | Not applicable |
| Reads the bucket's ACL GetBucketAcl | Reads the object's ACL GetObjectAcl |
| Sets the ACL for the bucket PutBucketAcl | Sets the ACL for the object PutObjectAcl |
| All rights within the bucket permissions: | All rights within the object permissions: |
Getting the bucket ACL. To get it, you need the READ_ACP permission on the bucket.
If the READ_ACP permission is granted to an anonymous user, you can get the bucket ACL without using an authorization header.
Example request:
GET /?acl HTTP/1.1Host: my-test-bucket1.hb.ru-msk.vkcloud-storage.rux-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855x-amz-date: 20200831T174434ZAuthorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20200831/ru-msk/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date,Signature=71dfa4666fb740d40d05307a29321c65cc620cdb17e8a9cb83d4f0e1b1b9d236
Example response:
HTTP/1.1 200 OKDate: Mon, 31 Aug 2020 17:44:35 GMTx-amz-request-id: tx000000000000002764fa6-005963bd03-1268c-ru-mskaContent-Type: application/xmlContent-Length: 848Connection: close<?xml version="1.0" encoding="UTF-8"?><AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/"><Owner><ID>eab55955-ebdb-4f18-a94d-f3558ff150da</ID><DisplayName>VK Cloud_UserName</DisplayName></Owner><AccessControlList><Grant><Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group"><URI>http://acs.amazonaws.com/groups/global/AllUsers</URI></Grantee><Permission>READ</Permission></Grant><Grant><Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser"><ID>eab55955-ebdb-4f18-a94d-f3558ff150da</ID><DisplayName>VK Cloud_Username</DisplayName></Grantee><Permission>FULL_CONTROL</Permission></Grant></AccessControlList></AccessControlPolicy>
Setting the bucket ACL. To set the ACL, you need the WRITE_ACP permission on the bucket.
Request with the ACL configuration passed in the request body:
PUT /?acl HTTP/1.1Content-Type: application/xmlContent-Length: 675Host: my-test-bucket1.hb.ru-msk.vkcloud-storage.rux-amz-content-sha256: 724483e3830b19d6960345c484fb7904b26e8f2fb34a6c002fa779353b68c8d8x-amz-date: 20200831T183709ZAuthorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20200831/ru-msk/s3/aws4_request,SignedHeaders=content-type;host;x-amz-content-sha256;x-amz-date,Signature=1cf3f7771a4086375e5b6597026db6d55d84fbc86e3c3a86ec420ea9123e3163<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/"><Owner><ID>eab55955-ebdb-4f18-a94d-f3558ff150da</ID></Owner><AccessControlList><Grant><Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser"><ID>eab55955-ebdb-4f18-a94d-f3558ff150da</ID></Grantee><Permission>FULL_CONTROL</Permission></Grant><Grant><Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group"><URI>http://acs.amazonaws.com/groups/global/AllUsers</URI></Grantee><Permission>READ</Permission></Grant></AccessControlList></AccessControlPolicy>
Example response:
HTTP/1.1 200 OKDate: Mon, 31 Aug 2020 18:37:10 GMTx-amz-request-id: tx00000000000000278ac49-005963c956-1268c-ru-mskaContent-Type: application/xmlContent-Length: 0Connection: close
Getting the object ACL. To get it, you need the READ_ACP permission on the object.
Example request:
GET /sammy.png?acl HTTP/1.1Host: my-test-bucket1.hb.ru-msk.vkcloud-storage.rux-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855x-amz-date: 20200831T191224ZAuthorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20200831/ru-msk/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date,Signature=950e133849cd19d626291fd2937d927957cf3e97a36707d30d51a9b61ac08a8e
Example response:
HTTP/1.1 200 OKDate: Mon, 31 Aug 2020 19:12:24 GMTx-amz-request-id: tx0000000000000027a42dc-005963d198-1268c-ru-mskaContent-Type: application/xmlContent-Length: 848Connection: close<?xml version="1.0" encoding="UTF-8"?><AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/"><Owner><ID>eab55955-ebdb-4f18-a94d-f3558ff150da</ID><DisplayName>VK Cloud_UserName</DisplayName></Owner><AccessControlList><Grant><Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group"><URI>http://acs.amazonaws.com/groups/global/AllUsers</URI></Grantee><Permission>READ</Permission></Grant><Grant><Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser"><ID>eab55955-ebdb-4f18-a94d-f3558ff150da</ID><DisplayName>VK Cloud_UserName</DisplayName></Grantee><Permission>FULL_CONTROL</Permission></Grant></AccessControlList></AccessControlPolicy>
Setting the object ACL. To set the ACL, you need the WRITE_ACP permission on the object.
Request with the ACL configuration passed in the request body:
PUT /sammy.png?acl HTTP/1.1Сontent-Type: application/xmlContent-Length: 443Host: my-test-bucket1.hb.ru-msk.vkcloud-storage.rux-amz-content-sha256:c0bd9ba784be78d4f38bbc1e3b0da2de2e7a8f4ee259b3b840369cf00a78dad2x-amz-date:20200831T192142ZAuthorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20200831/ru-msk/s3/aws4_request,SignedHeaders=content-type;host;x-amz-content-sha256;x-amz-date,Signature=dfeeb2386f76b29097adadb35ac15f7d5f244f18cc95f082b0ac6d14ced48b10<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/"><Owner><ID>eab55955-ebdb-4f18-a94d-f3558ff150da</ID></Owner><AccessControlList><Grant><Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser"><ID>eab55955-ebdb-4f18-a94d-f3558ff150da</ID></Grantee><Permission>FULL_CONTROL</Permission></Grant></AccessControlList></AccessControlPolicy>
Example response:
HTTP/1.1 200 OKDate: Mon, 31 Aug 2020 19:21:42 GMTx-amz-request-id: tx0000000000000027aafc9-005963d3c6-1268c-ru-mskaContent-Type: application/xmlContent-Length: 0Connection: close
When a new ACL configuration is set, the previous configuration is deleted. To avoid this, we recommend setting access permissions for all required categories of permittees at the same time.
Example of an XML structure for setting permissions simultaneously in a single request:
<?xml version="1.0" encoding="UTF-8"?><AccessControlPolicy xmlns="http://bucket_name.hb.ru-msk.vkcloud-storage.ru/images/01.jpg/"><Owner><ID>Owner-canonical-user-ID</ID><DisplayName>owner-display-name</DisplayName></Owner><AccessControlList><Grant><Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser"><ID>Owner-canonical-user-ID</ID><DisplayName>owner-display-name</DisplayName></Grantee><Permission>FULL_CONTROL</Permission></Grant><Grant><Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser"><ID>user1-canonical-user-ID</ID><DisplayName>user1-display-name</DisplayName></Grantee><Permission>WRITE</Permission></Grant><Grant><Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group"><URI>http://acs.amazonaws.com/groups/global/AllUsers</URI></Grantee><Permission>READ</Permission></Grant><Grant><Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group"><EmailAddress>project-ID</EmailAddress></Grantee><Permission>READ</Permission></Grant></AccessControlList></AccessControlPolicy>