Acl - Documentation

Cloud Storage uses access control lists (ACLs) to manage object and bucket access. ACLs are the mechanism you use to share objects with other users and allow other users to access your buckets and objects.

An ACL consists of one or more entries, where each entry grants permissions to an entity. Permissions define the actions that can be performed against an object or bucket (for example, READ or WRITE); the entity defines who the permission applies to (for example, a specific user or group of users).

Where an entity value is accepted, we follow the format the Cloud Storage API expects.

Refer to https://cloud.google.com/storage/docs/json_api/v1/defaultObjectAccessControls for the most up-to-date values.

user-userId
user-email
group-groupId
group-email
domain-domain
project-team-projectId
allUsers
allAuthenticatedUsers

Examples:

The user "liz@example.com" would be user-liz@example.com.
The group "example@googlegroups.com" would be group-example@googlegroups.com.
To refer to all members of the Google Apps for Business domain "example.com", the entity would be domain-example.com.

For more detailed information, see About Access Control Lists.

Members

owners

An object of convenience methods to add or delete owner ACL permissions for a given entity.

The supported methods include:

myFile.acl.owners.addAllAuthenticatedUsers
myFile.acl.owners.deleteAllAuthenticatedUsers
myFile.acl.owners.addAllUsers
myFile.acl.owners.deleteAllUsers
myFile.acl.owners.addDomain
myFile.acl.owners.deleteDomain
myFile.acl.owners.addGroup
myFile.acl.owners.deleteGroup
myFile.acl.owners.addProject
myFile.acl.owners.deleteProject
myFile.acl.owners.addUser
myFile.acl.owners.deleteUser

Example

const storage = require('@google-cloud/storage')();
const myBucket = storage.bucket('my-bucket');
const myFile = myBucket.file('my-file');

//-
// Add a user as an owner of a file.
//-
const myBucket = gcs.bucket('my-bucket');
const myFile = myBucket.file('my-file');
myFile.acl.owners.addUser('email@example.com', function(err, aclObject)
{});

//-
// For reference, the above command is the same as running the following.
//-
myFile.acl.add({
  entity: 'user-email@example.com',
  role: gcs.acl.OWNER_ROLE
}, function(err, aclObject) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
myFile.acl.owners.addUser('email@example.com').then(function(data) {
  const aclObject = data[0];
  const apiResponse = data[1];
});

readers

An object of convenience methods to add or delete reader ACL permissions for a given entity.

The supported methods include:

myFile.acl.readers.addAllAuthenticatedUsers
myFile.acl.readers.deleteAllAuthenticatedUsers
myFile.acl.readers.addAllUsers
myFile.acl.readers.deleteAllUsers
myFile.acl.readers.addDomain
myFile.acl.readers.deleteDomain
myFile.acl.readers.addGroup
myFile.acl.readers.deleteGroup
myFile.acl.readers.addProject
myFile.acl.readers.deleteProject
myFile.acl.readers.addUser
myFile.acl.readers.deleteUser

Example

const storage = require('@google-cloud/storage')();
const myBucket = storage.bucket('my-bucket');
const myFile = myBucket.file('my-file');

//-
// Add a user as a reader of a file.
//-
myFile.acl.readers.addUser('email@example.com', function(err, aclObject)
{});

//-
// For reference, the above command is the same as running the following.
//-
myFile.acl.add({
  entity: 'user-email@example.com',
  role: gcs.acl.READER_ROLE
}, function(err, aclObject) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
myFile.acl.readers.addUser('email@example.com').then(function(data) {
  const aclObject = data[0];
  const apiResponse = data[1];
});

writers

An object of convenience methods to add or delete writer ACL permissions for a given entity.

The supported methods include:

myFile.acl.writers.addAllAuthenticatedUsers
myFile.acl.writers.deleteAllAuthenticatedUsers
myFile.acl.writers.addAllUsers
myFile.acl.writers.deleteAllUsers
myFile.acl.writers.addDomain
myFile.acl.writers.deleteDomain
myFile.acl.writers.addGroup
myFile.acl.writers.deleteGroup
myFile.acl.writers.addProject
myFile.acl.writers.deleteProject
myFile.acl.writers.addUser
myFile.acl.writers.deleteUser

Example

const storage = require('@google-cloud/storage')();
const myBucket = storage.bucket('my-bucket');
const myFile = myBucket.file('my-file');

//-
// Add a user as a writer of a file.
//-
myFile.acl.writers.addUser('email@example.com', function(err, aclObject)
{});

//-
// For reference, the above command is the same as running the following.
//-
myFile.acl.add({
  entity: 'user-email@example.com',
  role: gcs.acl.WRITER_ROLE
}, function(err, aclObject) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
myFile.acl.writers.addUser('email@example.com').then(function(data) {
  const aclObject = data[0];
  const apiResponse = data[1];
});

Methods

add(options, callbackopt) → {Promise.<AddAclResponse>}

Add access controls on a Bucket or File.

Parameters:

Name Type Attributes Description

options

object

Configuration options.

Properties

Name	Type	Attributes	Description
`entity`	string		Whose permissions will be added.
`role`	string		Permissions allowed for the defined entity. See Access Control.
`generation`	number	<optional>	File Objects Only Select a specific revision of this file (as opposed to the latest version, the default).
`userProject`	string	<optional>	The ID of the project which will be billed for the request.

callback

AddAclCallback

Callback function.

Returns:

Type	Description
Promise.<AddAclResponse>

See:

Examples

const storage = require('@google-cloud/storage')();
const myBucket = storage.bucket('my-bucket');
const myFile = myBucket.file('my-file');

const options = {
  entity: 'user-useremail@example.com',
  role: gcs.acl.OWNER_ROLE
};

myBucket.acl.add(options, function(err, aclObject, apiResponse) {});

//-
// For file ACL operations, you can also specify a `generation` property.
// Here is how you would grant ownership permissions to a user on a
specific
// revision of a file.
//-
myFile.acl.add({
  entity: 'user-useremail@example.com',
  role: gcs.acl.OWNER_ROLE,
  generation: 1
}, function(err, aclObject, apiResponse) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
myBucket.acl.add(options).then(function(data) {
  const aclObject = data[0];
  const apiResponse = data[1];
});

Example of adding an owner to a file:

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of your GCS bucket
  // const bucketName = 'your-unique-bucket-name';

  // The name of the file to access
  // const fileName = 'file.txt';

  // The email address of the user to add
  // const userEmail = 'user-email-to-add';

  // Imports the Google Cloud client library
  const {Storage} = require('@google-cloud/storage');

  // Creates a client
  const storage = new Storage();

  async function addFileOwner() {
    await storage
      .bucket(bucketName)
      .file(fileName)
      .acl.owners.addUser(userEmail);

    console.log(`Added user ${userEmail} as an owner on file ${fileName}.`);
  }

  addFileOwner().catch(console.error);

Example of adding an owner to a bucket:

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of your GCS bucket
  // const bucketName = 'your-unique-bucket-name';

  // The email address of the user to add
  // const userEmail = 'user-email-to-add';

  // Imports the Google Cloud client library
  const {Storage} = require('@google-cloud/storage');

  // Creates a client
  const storage = new Storage();

  async function addBucketOwner() {
    // Makes the user an owner of the bucket. You can use addAllUsers(),
    // addDomain(), addProject(), addGroup(), and addAllAuthenticatedUsers()
    // to grant access to different types of entities. You can also use "readers"
    // and "writers" to grant different roles.
    await storage.bucket(bucketName).acl.owners.addUser(userEmail);

    console.log(`Added user ${userEmail} as an owner on bucket ${bucketName}.`);
  }

  addBucketOwner().catch(console.error);

Example of adding a default owner to a bucket:

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of your GCS bucket
  // const bucketName = 'your-unique-bucket-name';

  // The email address of the user to add
  // const userEmail = 'user-email-to-add';

  // Imports the Google Cloud client library
  const {Storage} = require('@google-cloud/storage');

  // Creates a client
  const storage = new Storage();

  async function addBucketDefaultOwner() {
    // Makes the user an owner in the default ACL of the bucket. You can use
    // addAllUsers(), addDomain(), addProject(), addGroup(), and
    // addAllAuthenticatedUsers() to grant access to different types of entities.
    // You can also use "readers" and "writers" to grant different roles.
    await storage.bucket(bucketName).acl.default.owners.addUser(userEmail);

    console.log(`Added user ${userEmail} as an owner on bucket ${bucketName}.`);
  }

  addBucketDefaultOwner().catch(console.error);

delete(options, callback) → {Promise.<RemoveAclResponse>}

Delete access controls on a Bucket or File.

Parameters:

Name Type Description

options

object

Configuration object.

Properties

Name	Type	Attributes	Description
`entity`	string		Whose permissions will be revoked.
`generation`	int	<optional>	File Objects Only Select a specific revision of this file (as opposed to the latest version, the default).
`userProject`	string	<optional>	The ID of the project which will be billed for the request.

callback

RemoveAclCallback

The callback function.

Returns:

Type	Description
Promise.<RemoveAclResponse>

See:

Examples

const storage = require('@google-cloud/storage')();
const myBucket = storage.bucket('my-bucket');
const myFile = myBucket.file('my-file');

myBucket.acl.delete({
  entity: 'user-useremail@example.com'
}, function(err, apiResponse) {});

//-
// For file ACL operations, you can also specify a `generation` property.
//-
myFile.acl.delete({
  entity: 'user-useremail@example.com',
  generation: 1
}, function(err, apiResponse) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
myFile.acl.delete().then(function(data) {
  const apiResponse = data[0];
});

Example of removing an owner from a bucket:

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of your GCS bucket
  // const bucketName = 'your-unique-bucket-name';

  // The email address of the user to remove
  // const userEmail = 'user-email-to-remove';

  // Imports the Google Cloud client library
  const {Storage} = require('@google-cloud/storage');

  // Creates a client
  const storage = new Storage();

  async function removeBucketOwner() {
    // Removes the user from the access control list of the bucket. You can use
    // deleteAllUsers(), deleteDomain(), deleteProject(), deleteGroup(), and
    // deleteAllAuthenticatedUsers() to remove access for different types of entities.
    await storage.bucket(bucketName).acl.owners.deleteUser(userEmail);

    console.log(`Removed user ${userEmail} from bucket ${bucketName}.`);
  }

  removeBucketOwner().catch(console.error);

Example of removing a default owner from a bucket:

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of your GCS bucket
  // const bucketName = 'your-unique-bucket-name';

  // The email address of the user to remove
  // const userEmail = 'user-email-to-remove';

  // Imports the Google Cloud client library
  const {Storage} = require('@google-cloud/storage');

  // Creates a client
  const storage = new Storage();

  async function removeBucketDefaultOwner() {
    // Removes the user from the access control list of the bucket. You can use
    // deleteAllUsers(), deleteDomain(), deleteProject(), deleteGroup(), and
    // deleteAllAuthenticatedUsers() to remove access for different types of entities.
    await storage.bucket(bucketName).acl.default.owners.deleteUser(userEmail);

    console.log(`Removed user ${userEmail} from bucket ${bucketName}.`);
  }

  removeBucketDefaultOwner().catch(console.error);

Example of removing an owner from a bucket:

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of your GCS bucket
  // const bucketName = 'your-unique-bucket-name';

  // The ID of your GCS file
  // const fileName = 'your-file-name';

  // The email address of the user to remove
  // const userEmail = 'user-email-to-remove';

  // Imports the Google Cloud client library
  const {Storage} = require('@google-cloud/storage');

  // Creates a client
  const storage = new Storage();

  async function removeFileOwner() {
    // Removes the user from the access control list of the file. You can use
    // deleteAllUsers(), deleteDomain(), deleteProject(), deleteGroup(), and
    // deleteAllAuthenticatedUsers() to remove access for different types of entities.
    await storage
      .bucket(bucketName)
      .file(fileName)
      .acl.owners.deleteUser(userEmail);

    console.log(`Removed user ${userEmail} from file ${fileName}.`);
  }

  removeFileOwner().catch(console.error);

get(optionsopt, callbackopt) → {Promise.<GetAclResponse>}

Get access controls on a Bucket or File. If an entity is omitted, you will receive an array of all applicable access controls.

Parameters:

Name Type Attributes Description

options

object | function

Configuration options. If you want to receive a list of all access controls, pass the callback function as the only argument.

Properties

Name	Type	Attributes	Description
`entity`	string	<optional>	Whose permissions will be fetched.
`generation`	number	<optional>	File Objects Only Select a specific revision of this file (as opposed to the latest version, the default).
`userProject`	string	<optional>	The ID of the project which will be billed for the request.

callback

GetAclCallback

Callback function.

Returns:

Type	Description
Promise.<GetAclResponse>

See:

Examples

const storage = require('@google-cloud/storage')();
const myBucket = storage.bucket('my-bucket');
const myFile = myBucket.file('my-file');

myBucket.acl.get({
  entity: 'user-useremail@example.com'
}, function(err, aclObject, apiResponse) {});

//-
// Get all access controls.
//-
myBucket.acl.get(function(err, aclObjects, apiResponse) {
  // aclObjects = [
  //   {
  //     entity: 'user-useremail@example.com',
  //     role: 'owner'
  //   }
  // ]
});

//-
// For file ACL operations, you can also specify a `generation` property.
//-
myFile.acl.get({
  entity: 'user-useremail@example.com',
  generation: 1
}, function(err, aclObject, apiResponse) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
myBucket.acl.get().then(function(data) {
  const aclObject = data[0];
  const apiResponse = data[1];
});

Example of printing a file's ACL:

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of your GCS bucket
  // const bucketName = 'your-unique-bucket-name';

  // The ID of your GCS file
  // const fileName = 'your-file-name';

  // Imports the Google Cloud client library
  const {Storage} = require('@google-cloud/storage');

  // Creates a client
  const storage = new Storage();

  async function printFileAcl() {
    // Gets the ACL for the file
    const [acls] = await storage.bucket(bucketName).file(fileName).acl.get();

    acls.forEach(acl => {
      console.log(`${acl.role}: ${acl.entity}`);
    });
  }

  printFileAcl().catch(console.error);

Example of printing a file's ACL for a specific user:

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of your GCS bucket
  // const bucketName = 'your-unique-bucket-name';

  // The ID of your GCS file
  // const fileName = 'your-file-name';

  // The email address of the user to check
  // const userEmail = 'user-email-to-check';

  // Imports the Google Cloud client library
  const {Storage} = require('@google-cloud/storage');

  // Creates a client
  const storage = new Storage();

  async function printFileAclForUser() {
    const options = {
      // Specify the user
      entity: `user-${userEmail}`,
    };

    // Gets the user's ACL for the file
    const [aclObject] = await storage
      .bucket(bucketName)
      .file(fileName)
      .acl.get(options);

    console.log(`${aclObject.role}: ${aclObject.entity}`);
  }

  printFileAclForUser().catch(console.error);

Example of printing a bucket's ACL:

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of your GCS bucket
  // const bucketName = 'your-unique-bucket-name';

  // Imports the Google Cloud client library
  const {Storage} = require('@google-cloud/storage');

  // Creates a client
  const storage = new Storage();

  async function printBucketAcl() {
    // Gets the ACL for the bucket
    const [acls] = await storage.bucket(bucketName).acl.get();

    acls.forEach(acl => {
      console.log(`${acl.role}: ${acl.entity}`);
    });
  }
  printBucketAcl().catch(console.error);

Example of printing a bucket's ACL for a specific user:

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of your GCS bucket
  // const bucketName = 'your-unique-bucket-name';

  // The email address of the user to check
  // const userEmail = 'user-email-to-check';

  // Imports the Google Cloud client library
  const {Storage} = require('@google-cloud/storage');

  // Creates a client
  const storage = new Storage();

  async function printBucketAclForUser() {
    const options = {
      // Specify the user
      entity: `user-${userEmail}`,
    };

    // Gets the user's ACL for the bucket
    const [aclObject] = await storage.bucket(bucketName).acl.get(options);

    console.log(`${aclObject.role}: ${aclObject.entity}`);
  }

  printBucketAclForUser().catch(console.error);

update(options, callbackopt) → {Promise.<UpdateAclResponse>}

Update access controls on a Bucket or File.

Parameters:

Name Type Attributes Description

options

object

Configuration options.

Properties

Name	Type	Attributes	Description
`entity`	string		Whose permissions will be updated.
`role`	string		Permissions allowed for the defined entity. See Storage.acl.
`generation`	number	<optional>	File Objects Only Select a specific revision of this file (as opposed to the latest version, the default).
`userProject`	string	<optional>	The ID of the project which will be billed for the request.

callback

UpdateAclCallback

Callback function.

Returns:

Type	Description
Promise.<UpdateAclResponse>

See:

Example

const storage = require('@google-cloud/storage')();
const myBucket = storage.bucket('my-bucket');
const myFile = myBucket.file('my-file');

const options = {
  entity: 'user-useremail@example.com',
  role: gcs.acl.WRITER_ROLE
};

myBucket.acl.update(options, function(err, aclObject, apiResponse) {});

//-
// For file ACL operations, you can also specify a `generation` property.
//-
myFile.acl.update({
  entity: 'user-useremail@example.com',
  role: gcs.acl.WRITER_ROLE,
  generation: 1
}, function(err, aclObject, apiResponse) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
myFile.acl.update(options).then(function(data) {
  const aclObject = data[0];
  const apiResponse = data[1];
});