Configure object access permissions with Node.js SDK - Object Storage Service

Object Storage Service (OSS) supports two levels of access control: bucket-level ACLs and object-level ACLs. Use object-level ACLs when you need to control access for individual objects separately from the bucket's default permissions.

ACL types

OSS provides four ACL types for objects:

Access permission	Description	Value
Inherit from bucket	The object inherits the access permissions of the bucket.	`default`
Private	The object owner and authorized users have read and write permissions. All other users have no access.	`private`
Public-read	The object owner and authorized users have read and write permissions. All other users have read-only access.	`public-read`
Public-read-write	All users have read and write permissions on the object.	`public-read-write`

Warning

public-read allows any internet user to read the object. Use this only for objects that are intentionally public.

Warning

public-read-write allows any internet user to both read and write the object. Avoid using this unless required by your use case.

Prerequisites

Before you begin, ensure that you have:

An OSS bucket
The ali-oss package installed (npm install ali-oss)
The OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables set with valid access credentials

Set object ACL

Use putACL to set the ACL on an object.

const oss = require('ali-oss');

const client = oss({
  // Set region to the region where the bucket is located.
  // Example: oss-cn-hangzhou for the China (Hangzhou) region.
  region: '<your-region>',
  // Load access credentials from environment variables.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: '<your-bucket-name>',
});

async function setACL() {
  try {
    // Specify the full object path. Do not include the bucket name.
    await client.putACL('<your-object-name>', 'private');
    console.log('ACL updated successfully.');
  } catch (e) {
    console.error(e);
  }
}

setACL();

Replace the placeholders with actual values:

Placeholder	Description	Example
`<your-region>`	The region where your bucket is located	`oss-cn-hangzhou`
`<your-bucket-name>`	The name of your bucket	`my-bucket`
`<your-object-name>`	The full path of the object, excluding the bucket name	`photos/2024/image.jpg`

Get object ACL

Use getACL to retrieve the current ACL of an object. The method returns an object with an acl property containing the current ACL value.

const oss = require('ali-oss');

const client = oss({
  // Set region to the region where the bucket is located.
  // Example: oss-cn-hangzhou for the China (Hangzhou) region.
  region: '<your-region>',
  // Load access credentials from environment variables.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: '<your-bucket-name>',
});

async function getACL() {
  try {
    // Specify the full object path. Do not include the bucket name.
    const result = await client.getACL('<your-object-name>');
    console.log(result.acl);
  } catch (e) {
    console.error(e);
  }
}

getACL();

References

For the complete sample code, see the GitHub example.
For the API operation used to set object ACLs, see PutObjectACL.
For the API operation used to get object ACLs, see GetObjectACL.