Help Center/ Object Storage Service/ SDK Reference/ Java/ Buckets (SDK for Java)/ Configuring a Bucket ACL (SDK for Java)
Updated on 2024-06-18 GMT+08:00

Configuring a Bucket ACL (SDK for Java)

Function

OBS provides access control over buckets. You can use an access policy to define whether a user can perform certain operations on a specific bucket. OBS access control can be implemented using IAM permissions, bucket policies, and ACLs (including bucket and object ACLs). For more information, see Introduction to OBS Access Control.

A bucket ACL applies permissions to a different account and its IAM users, rather than the current account and its IAM users. It can grant access to both a bucket (including the objects in it) and the bucket ACL. The granted access includes view and edit permissions. You must specify a bucket name when configuring a bucket ACL. For more information, see ACLs.

If you have any questions during development, post them on the Issues page of GitHub.

You can configure a bucket ACL by referring to Method.

OBS supports five types of bucket or object permissions. For details, see Table 9.

OBS supports five types of pre-defined ACLs. For details, see Table 3.

Restrictions

Method

  • Method 1: Configure a bucket ACL when creating a bucket.
    obsBucket.setBucketName(exampleBucket);
    // Set the bucket ACL to PRIVATE.
    obsBucket.setAcl(AccessControlList.REST_CANNED_PRIVATE);
    // Create a bucket.
    obsClient.createBucket(obsBucket);
  • Method 2: Use a pre-defined access policy to configure a bucket ACL.
    // Set the bucket ACL to PRIVATE.
    obsClient.setBucketAcl(String exampleBucket, AccessControlList.REST_CANNED_PRIVATE);
  • Method 3: Call ObsClient.setBucketAcl to configure a bucket ACL.
    // Configure the bucket ACL.
    obsClient.setBucketAcl(String bucketName,AccessControlList acl);

Request Parameters

Table 1 List of request parameters

Parameter

Type

Mandatory (Yes/No)

Description

bucketName

String

Yes

Explanation:

Bucket name.

Restrictions:

  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain periods (.) and hyphens (-) adjacent to each other, for example, my-.bucket or my.-bucket.
  • If you repeatedly create buckets of the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.

Default value:

None

acl

AccessControlList

Yes

Explanation:

An ACL that can be specified at bucket creation. You can use either a pre-defined or a user-defined ACL. For more information about ACLs, see ACLs.

Value range:

  • To use a pre-defined ACL, see Table 3 for the available policies.
  • To use a user-defined ACL, see Table 2 to configure the required parameters.

Default value:

AccessControlList.REST_CANNED_PRIVATE

Table 2 AccessControlList

Parameter

Type

Mandatory (Yes/No)

Type

owner

Owner

Yes

Explanation:

Bucket owner information. For details, see Table 4.

delivered

boolean

No

Explanation:

Whether the bucket ACL is applied to all objects in the bucket.

Value range:

true: The bucket ACL is applied to all objects in the bucket.

false: The bucket ACL is not applied to any objects in the bucket.

Default value:

false

grants

Set<GrantAndPermission>

No

Explanation:

Grantee information. For details, see Table 5.

Table 3 ACL

Constant

Description

AccessControlList.REST_CANNED_PRIVATE

Private read/write.

A bucket or object can only be accessed by its owner.

AccessControlList.REST_CANNED_PUBLIC_READ

Public read.

If this permission is granted on a bucket, anyone can read the object list, multipart uploads, bucket metadata, and object versions in the bucket.

If this permission is granted on an object, anyone can read the content and metadata of the object.

AccessControlList.REST_CANNED_PUBLIC_READ_WRITE

Public read/write.

If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart uploads, upload parts, assemble parts, copy parts, and cancel multipart upload tasks.

If this permission is granted on an object, anyone can read the content and metadata of the object.

AccessControlList.REST_CANNED_PUBLIC_READ_DELIVERED

Public read on a bucket as well as objects in the bucket.

If this permission is granted on a bucket, anyone can read the object list, multipart tasks, and bucket metadata, and can also read the content and metadata of the objects in the bucket.

This permission cannot be granted on objects.

AccessControlList.REST_CANNED_PUBLIC_READ_WRITE_DELIVERED

Public read/write on a bucket as well as objects in the bucket.

If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart uploads. They can also read the content and metadata of the objects in the bucket.

This permission cannot be granted on objects.

Table 4 Owner

Parameter

Type

Mandatory (Yes/No)

Description

id

String

Yes

Explanation:

Account (domain) ID of the bucket owner.

Value range:

To obtain the account ID, see How Do I Get My Account ID and User ID?

Default value:

None

displayName

String

No

Explanation:

Account name of the owner.

Value range:

To obtain the account name, see How Do I Get My Account ID and User ID?

Default value:

None

Table 5 GrantAndPermission

Parameter

Type

Mandatory (Yes/No)

Description

grantee

GranteeInterface

Yes

Explanation:

Grantees (users or user groups). For details, see Table 6.

permission

Permission

Yes

Explanation:

Permissions to grant.

Value range:

See Table 9.

Default value:

None

delivered

boolean

No

Explanation:

Whether the bucket ACL is applied to all objects in the bucket.

Value range:

true: The bucket ACL is applied to all objects in the bucket.

false: The bucket ACL is not applied to any objects in the bucket.

Default value:

false

Table 6 GranteeInterface

Parameter

Type

Mandatory (Yes/No)

Description

CanonicalGrantee

CanonicalGrantee

Yes

Explanation:

Grantee (user) information. For details, see Table 7.

GroupGrantee

GroupGrantee

Yes

Explanation:

Grantee (user group) information.

Value range:

See Table 8.

Default value:

None

Table 7 CanonicalGrantee

Parameter

Type

Mandatory (Yes/No)

Description

grantId

String

Yes if Type is set to GranteeUser

Explanation:

Account (domain) ID of the grantee.

Value range:

To obtain the account ID, see How Do I Get My Account ID and User ID?

Default value:

None

displayName

String

No

Parameter description:

Account name of the grantee.

Value range:

To obtain the account name, see How Do I Get My Account ID and User ID?

Default value:

None

Table 8 GroupGrantee

Constant

Description

ALL_USERS

All users.

AUTHENTICATED_USERS

Authorized users. This constant is deprecated.

LOG_DELIVERY

Log delivery group. This constant is deprecated.

Table 9 Permission

Constant

Default Value

Description

PERMISSION_READ

READ

Read permission.

A grantee with this permission for a bucket can obtain the list of objects, multipart uploads, bucket metadata, and object versions in the bucket.

A grantee with this permission for an object can obtain the object content and metadata.

PERMISSION_WRITE

WRITE

Write permission.

A grantee with this permission for a bucket can upload, overwrite, and delete any object or part in the bucket.

This permission is not available for objects.

PERMISSION_READ_ACP

READ_ACP

Permission to read an ACL.

A grantee with this permission can obtain the ACL of a bucket or object.

A bucket or object owner has this permission for their bucket or object by default.

PERMISSION_WRITE_ACP

WRITE_ACP

Permission to modify an ACL.

A grantee with this permission can update the ACL of a bucket or object.

A bucket or object owner has this permission for their bucket or object by default.

This permission allows the grantee to change the access control policies, meaning the grantee has full control over a bucket or object.

PERMISSION_FULL_CONTROL

FULL_CONTROL

Full control access, including read and write permissions for a bucket and its ACL, or for an object and its ACL.

A grantee with this permission for a bucket has READ, WRITE, READ_ACP, and WRITE_ACP permissions for the bucket.

A grantee with this permission for an object has READ, WRITE, READ_ACP, and WRITE_ACP permissions for the object.

Responses

Table 10 Common response headers

Parameter

Type

Description

statusCode

int

Explanation:

HTTP status code.

Value range:

A status code is a group of digits that can be 2xx (indicating successes) or 4xx or 5xx (indicating errors). It indicates the status of a response.

For more information, see Status Code.

Default value:

None

responseHeaders

Map<String, Object>

Explanation:

HTTP response header list, composed of tuples. In a tuple, the String key indicates the name of the header, and the Object value indicates the value of the header.

Default value:

None

Code Example: Setting a Pre-defined ACL When Creating a Bucket

This example configures a pre-defined ACL during the creation of bucket exampleBucket.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
import com.obs.services.ObsClient;
import com.obs.services.exception.ObsException;
import com.obs.services.model.AccessControlList;
import com.obs.services.model.ObsBucket;
public class SetBucketAcl001 {
    public static void main(String[] args) {
        // Obtain an AK/SK pair using environment variables or import the AK/SK pair in other ways. Using hard coding may result in leakage.
        // Obtain an AK/SK pair on the management console.
        String ak = System.getenv("ACCESS_KEY_ID");
        String sk = System.getenv("SECRET_ACCESS_KEY_ID");
        // (Optional) If you are using a temporary AK/SK pair and a security token to access OBS, you are advised not to use hard coding, which may result in information leakage.
        // Obtain an AK/SK pair and a security token using environment variables or import them in other ways.
        // String securityToken = System.getenv("SECURITY_TOKEN");
        // Enter the endpoint corresponding to the bucket. CN-Hong Kong is used here as an example. Replace it with the one in your actual situation.
        String endPoint = "https://obs.ap-southeast-1.myhuaweicloud.com";
        // Obtain an endpoint using environment variables or import it in other ways.
        //String endPoint = System.getenv("ENDPOINT");
        
        // Create an ObsClient instance.
        // Use the permanent AK/SK pair to initialize the client.
        ObsClient obsClient = new ObsClient(ak, sk,endPoint);
        // Use the temporary AK/SK pair and security token to initialize the client.
        // ObsClient obsClient = new ObsClient(ak, sk, securityToken, endPoint);

        try {
            ObsBucket obsBucket = new ObsBucket();
            // Example bucket name
            String exampleBucket = "examplebucket";
            obsBucket.setBucketName(exampleBucket);
            // Set the bucket ACL to be private.
            obsBucket.setAcl(AccessControlList.REST_CANNED_PRIVATE);
            // Create a bucket.
            obsClient.createBucket(obsBucket);
            System.out.println("SetBucketAcl successfully");
        } catch (ObsException e) {
            System.out.println("SetBucketAcl failed");
            // Request failed. Print the HTTP status code.
            System.out.println("HTTP Code:" + e.getResponseCode());
            // Request failed. Print the server-side error code.
            System.out.println("Error Code:" + e.getErrorCode());
            // Request failed. Print the error details.
            System.out.println("Error Message:" + e.getErrorMessage());
            // Request failed. Print the request ID.
            System.out.println("Request ID:" + e.getErrorRequestId());
            System.out.println("Host ID:" + e.getErrorHostId());
            e.printStackTrace();
        } catch (Exception e) {
            System.out.println("SetBucketAcl failed");
            // Print other error information.
            e.printStackTrace();
        }
    }
}

Code Example: Setting a Pre-defined ACL for a Bucket

This example configures a pre-defined ACL for bucket exampleBucket.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
import com.obs.services.ObsClient;
import com.obs.services.exception.ObsException;
import com.obs.services.model.AccessControlList;
public class SetBucketAcl002 {
    public static void main(String[] args) {
        // Obtain an AK/SK pair using environment variables or import the AK/SK pair in other ways. Using hard coding may result in leakage.
        // Obtain an AK/SK pair on the management console.
        String ak = System.getenv("ACCESS_KEY_ID");
        String sk = System.getenv("SECRET_ACCESS_KEY_ID");
        // (Optional) If you are using a temporary AK/SK pair and a security token to access OBS, you are advised not to use hard coding, which may result in information leakage.
        // Obtain an AK/SK pair and a security token using environment variables or import them in other ways.
        // String securityToken = System.getenv("SECURITY_TOKEN");
        // Enter the endpoint corresponding to the bucket. CN-Hong Kong is used here as an example. Replace it with the one in your actual situation.
        String endPoint = "https://obs.ap-southeast-1.myhuaweicloud.com";
        // Obtain an endpoint using environment variables or import it in other ways.
        //String endPoint = System.getenv("ENDPOINT");
        
        // Create an ObsClient instance.
        // Use the permanent AK/SK pair to initialize the client.
        ObsClient obsClient = new ObsClient(ak, sk,endPoint);
        // Use the temporary AK/SK pair and security token to initialize the client.
        // ObsClient obsClient = new ObsClient(ak, sk, securityToken, endPoint);

        try {
            // Example bucket name
            String exampleBucket = "examplebucket";
            // Set the bucket ACL to be private.
            obsClient.setBucketAcl(exampleBucket, AccessControlList.REST_CANNED_PRIVATE);
            System.out.println("SetBucketAcl successfully");
        } catch (ObsException e) {
            System.out.println("SetBucketAcl failed");
            // Request failed. Print the HTTP status code.
            System.out.println("HTTP Code:" + e.getResponseCode());
            // Request failed. Print the server-side error code.
            System.out.println("Error Code:" + e.getErrorCode());
            // Request failed. Print the error details.
            System.out.println("Error Message:" + e.getErrorMessage());
            // Request failed. Print the request ID.
            System.out.println("Request ID:" + e.getErrorRequestId());
            System.out.println("Host ID:" + e.getErrorHostId());
            e.printStackTrace();
        } catch (Exception e) {
            System.out.println("SetBucketAcl failed");
            // Print other error information.
            e.printStackTrace();
        }
    }
}

Code Example: Setting an ACL for a Bucket

This example configures an ACL for bucket exampleBucket.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
import com.obs.services.ObsClient;
import com.obs.services.exception.ObsException;
import com.obs.services.model.AccessControlList;
import com.obs.services.model.CanonicalGrantee;
import com.obs.services.model.GroupGrantee;
import com.obs.services.model.Owner;
import com.obs.services.model.Permission;
public class SetBucketAcl003 {
    public static void main(String[] args) {
        // Obtain an AK/SK pair using environment variables or import the AK/SK pair in other ways. Using hard coding may result in leakage.
        // Obtain an AK/SK pair on the management console.
        String ak = System.getenv("ACCESS_KEY_ID");
        String sk = System.getenv("SECRET_ACCESS_KEY_ID");
        // (Optional) If you are using a temporary AK/SK pair and a security token to access OBS, you are advised not to use hard coding, which may result in information leakage.
        // Obtain an AK/SK pair and a security token using environment variables or import them in other ways.
        // String securityToken = System.getenv("SECURITY_TOKEN");
        // Enter the endpoint corresponding to the bucket. CN-Hong Kong is used here as an example. Replace it with the one in your actual situation.
        String endPoint = "https://obs.ap-southeast-1.myhuaweicloud.com";
        // Obtain an endpoint using environment variables or import it in other ways.
        //String endPoint = System.getenv("ENDPOINT");
       
        // Create an ObsClient instance.
        // Use the permanent AK/SK pair to initialize the client.
        ObsClient obsClient = new ObsClient(ak, sk,endPoint);
        // Use the temporary AK/SK pair and security token to initialize the client.
        // ObsClient obsClient = new ObsClient(ak, sk, securityToken, endPoint);

        try {
            // Example bucket name
            String exampleBucket = "examplebucket";
            // Example user ID
            String exampleUserid = "userid";
            // Example user ID
            String exampleOwnerId = "ownerid";
            AccessControlList acl = new AccessControlList();
            Owner owner = new Owner();
            owner.setId(exampleOwnerId);
            acl.setOwner(owner);
            // Grant the full control permission to a specified user.
            acl.grantPermission(new CanonicalGrantee(exampleUserid), Permission.PERMISSION_FULL_CONTROL);
            // Grant the read permission to all users.
            acl.grantPermission(GroupGrantee.ALL_USERS, Permission.PERMISSION_READ);
            // Configure the bucket ACL.
            obsClient.setBucketAcl(exampleBucket, acl);
            System.out.println("SetBucketAcl successfully");
        } catch (ObsException e) {
            System.out.println("SetBucketAcl failed");
            // Request failed. Print the HTTP status code.
            System.out.println("HTTP Code:" + e.getResponseCode());
            // Request failed. Print the server-side error code.
            System.out.println("Error Code:" + e.getErrorCode());
            // Request failed. Print the error details.
            System.out.println("Error Message:" + e.getErrorMessage());
            // Request failed. Print the request ID.
            System.out.println("Request ID:" + e.getErrorRequestId());
            System.out.println("Host ID:" + e.getErrorHostId());
            e.printStackTrace();
        } catch (Exception e) {
            System.out.println("SetBucketAcl failed");
            // Print other error information.
            e.printStackTrace();
        }
    }
}