IAM

IAM

IAM (Identity and Access Management) allows you to set permissions on invidual resources and offers a wider range of roles: editor, owner, publisher, subscriber, and viewer. This gives you greater flexibility and allows you to set more fine-grained access control.

For example:

  • Grant access on a per-topic or per-subscription basis, rather than for the whole Cloud project.
  • Grant access with limited capabilities, such as to only publish messages to a topic, or to only to consume messages from a subscription, but not to delete the topic or subscription.

The IAM access control features described in this document are Beta, including the API methods to get and set IAM policies, and to test IAM permissions. Cloud Pub/Sub's use of IAM features is not covered by any SLA or deprecation policy, and may be subject to backward-incompatible changes.

Constructor

new IAM(pubsub, id)

Parameters:
Name Type Description
pubsub PubSub

PubSub Object.
id string

The name of the topic or subscription.
Source:
See:
Example
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();

const topic = pubsub.topic('my-topic');
// topic.iam

const subscription = pubsub.subscription('my-subscription');
// subscription.iam

Methods

getPolicy(gaxOptionsopt, callbackopt) → {Promise.<GetPolicyResponse>}

Get the IAM policy

Parameters:
Name Type Attributes Description
gaxOptions object <optional>

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html.
callback GetPolicyCallback <optional>

Callback function.
Source:
See:
Example
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();

const topic = pubsub.topic('my-topic');
const subscription = topic.subscription('my-subscription');

topic.iam.getPolicy(function(err, policy, apiResponse) {});

subscription.iam.getPolicy(function(err, policy, apiResponse) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
topic.iam.getPolicy().then(function(data) {
  const policy = data[0];
  const apiResponse = data[1];
});

setPolicy(policy, gaxOptionsopt, callback) → {Promise.<SetPolicyResponse>}

Set the IAM policy

Parameters:
Name Type Attributes Description
policy object

The policy.

Properties
Name Type Attributes Description
bindings array <optional>

Bindings associate members with roles.
rules Array.<object> <optional>

Rules to be applied to the policy.
etag string <optional>

Etags are used to perform a read-modify-write.
gaxOptions object <optional>

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html.
callback SetPolicyCallback

Callback function.
Source:
See:
Throws:

If no policy is provided.

Type
Error
Example
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();

const topic = pubsub.topic('my-topic');
const subscription = topic.subscription('my-subscription');

const myPolicy = {
  bindings: [
    {
      role: 'roles/pubsub.subscriber',
      members:
['serviceAccount:myotherproject@appspot.gserviceaccount.com']
    }
  ]
};

topic.iam.setPolicy(myPolicy, function(err, policy, apiResponse) {});

subscription.iam.setPolicy(myPolicy, function(err, policy, apiResponse)
{});

//-
// If the callback is omitted, we'll return a Promise.
//-
topic.iam.setPolicy(myPolicy).then(function(data) {
  const policy = data[0];
  const apiResponse = data[1];
});

testPermissions(permissions, gaxOptionsopt, callbackopt) → {Promise.<TestIamPermissionsResponse>}

Test a set of permissions for a resource.

Permissions with wildcards such as * or storage.* are not allowed.

Parameters:
Name Type Attributes Description
permissions string | Array.<string>

The permission(s) to test for.
gaxOptions object <optional>

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html.
callback TestIamPermissionsCallback <optional>

Callback function.
Source:
See:
Throws:

If permissions are not provided.

Type
Error
Example
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();

const topic = pubsub.topic('my-topic');
const subscription = topic.subscription('my-subscription');

//-
// Test a single permission.
//-
const test = 'pubsub.topics.update';

topic.iam.testPermissions(test, function(err, permissions, apiResponse) {
  console.log(permissions);
  // {
  //   "pubsub.topics.update": true
  // }
});

//-
// Test several permissions at once.
//-
const tests = [
  'pubsub.subscriptions.consume',
  'pubsub.subscriptions.update'
];

subscription.iam.testPermissions(tests, function(err, permissions) {
  console.log(permissions);
  // {
  //   "pubsub.subscriptions.consume": true,
  //   "pubsub.subscriptions.update": false
  // }
});

//-
// If the callback is omitted, we'll return a Promise.
//-
topic.iam.testPermissions(test).then(function(data) {
  const permissions = data[0];
  const apiResponse = data[1];
});