OSS on CloudBox bucket ACLs

An Access Control List (ACL) controls who can read from and write to an OSS on CloudBox bucket. OSS checks the bucket ACL on every request to verify that the requester has the required permissions. Set the ACL when you create a bucket, or modify it later as your requirements change. Only the bucket owner can modify the ACL.

Prerequisites

Before you begin, ensure that you have:

OSS on CloudBox deployed in one of the supported regions: China (Hangzhou), China (Shanghai), China (Shenzhen), China (Heyuan), China (Beijing), or China (Chengdu)
A cloud box purchased. For more information, see Purchase a cloud box
A Virtual Private Cloud (VPC) and a vSwitch created in OSS on CloudBox. For more information, see Create a VPC and a vSwitch
A VPC internal network set up with a single tunnel configured. To apply for this, contact technical support

ACL types

ACL	Who can read	Who can write	Recommendation
`private`	Bucket owner only	Bucket owner only	Default. Recommended for most use cases.
`public-read`	Everyone, including anonymous users	Bucket owner only	Use with caution. May result in unexpected access and high costs.
`public-read-write`	Everyone, including anonymous users	Everyone, including anonymous users	Not recommended. Risk of unauthorized access, data tampering, and high costs.

ACL inheritance and ownership

Only the bucket owner can modify the bucket ACL.
Modifying the bucket ACL changes the ACL of all objects that inherit the bucket ACL.
Objects uploaded without an explicit ACL inherit the bucket ACL.

Set or modify the bucket ACL

Choose the method that matches your workflow:

Method	Best for
OSS console	Quick setup and one-off changes
OSS SDK for Java	Automated or programmatic configuration (Java only; version 3.15.0 or later required)
ossutil	Command-line scripting and batch operations
OSS API	Custom integrations requiring direct API calls

Use the OSS console

Set the ACL when creating a bucket

Log on to the OSS console.
In the left-side navigation pane, choose Data Service > OSS on CloudBox Buckets. On the OSS on CloudBox Buckets page, click Create Bucket.
In the Create Bucket panel, configure the ACL field. For information about other bucket creation parameters, see Create an OSS on CloudBox bucket.
Click OK.

Modify the ACL of an existing bucket

Log on to the OSS console.
In the left-side navigation pane, choose Data Service > OSS on CloudBox Buckets. On the OSS on CloudBox Buckets page, click the bucket whose ACL you want to modify.
In the left-side navigation tree, choose Permission Control > ACL.
On the ACL tab, click Settings and select the new ACL.
Click Save.

Use OSS SDK for Java

OSS SDK for Java (version 3.15.0 or later) is the only SDK that supports setting the ACL for an OSS on CloudBox bucket.

The following example sets the bucket ACL to private.

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.CannedAccessControlList;
import com.aliyun.oss.common.auth.DefaultCredentialProvider;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.ClientBuilderConfiguration;
import com.aliyun.oss.common.auth.CredentialsProviderFactory;
import com.aliyun.oss.common.auth.EnvironmentVariableCredentialsProvider;

public class Demo {

    public static void main(String[] args) throws Exception {
        // Specify the data endpoint of the OSS on CloudBox bucket.
        String endpoint = "https://cb-f8z7yvzgwfkl9q0h****.cn-hangzhou.oss-cloudbox.aliyuncs.com";
        // Load credentials from environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the bucket name.
        String bucketName = "examplebucket";
        // Specify the region where the bucket is located.
        String region = "cn-hangzhou";
        // Specify the cloud box ID.
        String cloudBoxId = "cb-f8z7yvzgwfkl9q0h****";

        // Create an OSSClient instance. Call shutdown() when the client is no longer needed.
        ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
        conf.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(new DefaultCredentialProvider(credentialsProvider.getCredentials()))
                .clientConfiguration(conf)
                .region(region)
                .cloudBoxId(cloudBoxId)
                .build();

        try {
            // Set the bucket ACL to private.
            ossClient.setBucketAcl(bucketName, CannedAccessControlList.Private);
        } catch (OSSException oe) {
            System.out.println("OSS rejected the request.");
            System.out.println("Error Message: " + oe.getErrorMessage());
            System.out.println("Error Code: " + oe.getErrorCode());
            System.out.println("Request ID: " + oe.getRequestId());
            System.out.println("Host ID: " + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Client failed to reach OSS.");
            System.out.println("Error Message: " + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

Replace the following placeholders with actual values:

Placeholder	Description	Example
`cb-f8z7yvzgwfkl9q0h****`	Cloud box ID	`cb-f8z7yvzgwfkl9q0h1234`
`examplebucket`	Bucket name	`my-cloudbox-bucket`
`cn-hangzhou`	Region ID	`cn-shanghai`

Use ossutil

For ossutil instructions, see put-bucket-acl.

Use the OSS API

For scenarios requiring direct API calls, see PutBucketAcl. Include signature calculation in your code.

Configure the ACL for an OSS on CloudBox bucket to grant or deny read and write permissions