Acl

Acl

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>}

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 <optional>

Callback function.

Returns:
Type Description
Promise.<AddAclResponse>
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>}

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>
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.

See BucketAccessControls: get API Documentation See ObjectAccessControls: get API Documentation

Parameters:
Name Type Attributes Description
options object | function <optional>

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

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 <optional>

Callback function.

Returns:
Type Description
Promise.<GetAclResponse>
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>}

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 <optional>

Callback function.

Returns:
Type Description
Promise.<UpdateAclResponse>
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];
});
```