Access control

This document describes the access control options available to you in Pub/Sub.

Overview

Pub/Sub uses Cloud Identity and Access Management (Cloud IAM) for access control.

In Pub/Sub, access control can be configured at the project level and at the individual resource level. 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 consume messages from a subscription, but not to delete the topic or subscription.
  • Grant access to all Pub/Sub resources within a project to a group of developers.

For a detailed description of Cloud IAM and its features, see the Cloud IAM documentation. In particular, see Granting, changing, and revoking access to resources.

Every Pub/Sub method requires the caller to have the necessary permissions. For a list of the permissions and roles Pub/Sub Cloud IAM supports, see the Roles section, below.

Permissions and roles

This section summarizes the permissions and roles Pub/Sub Cloud IAM supports.

Required permissions

The following table lists the permissions that the caller must have to call each method:

Method Required Permission(s)
projects.snapshots.create pubsub.snapshots.create on the containing Cloud project and pubsub.subscriptions.consume permission on the source subscription.
projects.snapshots.delete pubsub.snapshots.delete on the requested snapshot.
projects.snapshots.getIamPolicy pubsub.snapshots.getIamPolicy on the requested snapshot.
projects.snapshots.list pubsub.snapshots.list on the requested Cloud project.
projects.snapshots.patch pubsub.snapshots.update on the requested snapshot.
projects.snapshots.setIamPolicy pubsub.snapshots.setIamPolicy on the requested snapshot.
projects.snapshots.testIamPermissions None.
projects.subscriptions.acknowledge pubsub.subscriptions.consume on the requested subscription.
projects.subscriptions.create pubsub.subscriptions.create on the containing Cloud project and pubsub.topics.attachSubscription on the requested topic. Note that for creating a subscription in Project A to a Topic T in Project B, the appropriate permissions must be granted on both Project A and on Topic T. In this case, user identity info can be captured in Project B's audit logs.
projects.subscriptions.delete pubsub.subscriptions.delete on the requested subscription.
projects.subscriptions.get pubsub.subscriptions.get on the requested subscription.
projects.subscriptions.getIamPolicy pubsub.subscriptions.getIamPolicy on the requested subscription.
projects.subscriptions.list pubsub.subscriptions.list on the requested Cloud project.
projects.subscriptions.modifyAckDeadline pubsub.subscriptions.consume on the requested subscription.
projects.subscriptions.modifyPushConfig pubsub.subscriptions.update on the requested subscription.
projects.subscriptions.patch pubsub.subscriptions.update on the requested subscription.
projects.subscriptions.pull pubsub.subscriptions.consume on the requested subscription.
projects.subscriptions.seek pubsub.subscriptions.consume on the requested subscription and pubsub.snapshots.seek on the requested snapshot, if any.
projects.subscriptions.setIamPolicy pubsub.subscriptions.setIamPolicy on the requested subscription.
projects.subscriptions.testIamPermissions None.
projects.topics.create pubsub.topics.create on the containing Cloud project.
projects.topics.delete pubsub.topics.delete on the requested topic.
projects.topics.get pubsub.topics.get on the requested topic.
projects.topics.getIamPolicy pubsub.topics.getIamPolicy on the requested topic.
projects.topics.list pubsub.topics.list on the requested Cloud project.
projects.topics.patch pubsub.topics.update on the requested topic.
projects.topics.publish pubsub.topics.publish on the requested topic.
projects.topics.setIamPolicy pubsub.topics.setIamPolicy on the requested topic.
projects.topics.subscriptions.list pubsub.topics.get on the requested topic.
projects.topics.testIamPermissions None.

Roles

The following table lists the Pub/Sub Cloud IAM roles with a corresponding list of all the permissions each role includes. Note that every permission is applicable to a particular resource type.

These preconfigured roles address many typical use cases. However, you might need a role that includes a custom set of permissions. For instance, you may wish to create a role that allows a user to create a subscription in a project, without letting them delete or update existing topics or subscriptions in the project. In those cases, you may be able to create an Cloud IAM custom role that meets your needs.

Role includes permission(s): for resource type:
roles/pubsub.publisher pubsub.topics.publish Topic
roles/pubsub.subscriber
 pubsub.snapshots.seek Snapshot
pubsub.subscriptions.consume Subscription
pubsub.topics.attachSubscription Topic
roles/pubsub.viewer or
roles/viewer
 pubsub.snapshots.get Snapshot
pubsub.snapshots.list Project
pubsub.subscriptions.get Subscription
pubsub.subscriptions.list Project
pubsub.topics.get Topic
pubsub.topics.list Project
resourcemanager.projects.get Project
servicemanagement.projectSettings.get Project
serviceusage.quotas.get Project
serviceusage.services.get Project
serviceusage.services.list Project
roles/pubsub.editor or
roles/editor
 All of the above, as well as:
pubsub.snapshots.create Project
pubsub.snapshots.delete Snapshot
pubsub.snapshots.update Snapshot
pubsub.subscriptions.create Project
pubsub.subscriptions.delete Subscription
pubsub.subscriptions.update Subscription
pubsub.topics.create Project
pubsub.topics.delete Topic
pubsub.topics.update Topic
pubsub.topics.updateTag Topic
roles/pubsub.admin or
roles/owner
 All of the above, as well as:
pubsub.snapshots.getIamPolicy Snapshot
pubsub.snapshots.setIamPolicy Snapshot
pubsub.subscriptions.getIamPolicy Subscription
pubsub.subscriptions.setIamPolicy Subscription
pubsub.topics.getIamPolicy Topic
pubsub.topics.setIamPolicy Topic

The roles roles/owner, roles/editor, and roles/viewer include also permissions for other Google Cloud services.

Controlling access via the Google Cloud Console

You can use the GCP Console to manage access control for your topics and projects.

To set access controls at the project level:

  1. Open the Cloud IAM page in the Cloud Console.
  2. Select your project, and click Continue.
  3. Click Add Member.
  4. Enter the email address of a new member to whom you have not granted any Cloud IAM role previously.
  5. Select a role from the drop-down menu.
  6. Click Add.
  7. Verify that the member is listed under the role that you granted.

To set access controls for topics and subscriptions:

  1. Navigate to the Pub/Sub topics page in the console.
  2. Select your Pub/Sub-enabled project.

  3. Select the topic or subscription.

    You can set permissions for multiple topics at one time. To set permissions for a topic's subscription, expand the topic and click the subscription to open it in its own page.

  4. Click Permissions. In the pane that appears:

    1. Type in a member name or names.
    2. Select a role from the drop-down menu.
    3. Click Add.

Controlling access via the Cloud IAM API

The Pub/Sub Cloud IAM API lets you set and get policies on individual topics and subscriptions in a project, and test a user's permissions for a given resource. As with the regular Pub/Sub methods, you can invoke the Cloud IAM API methods via the client libraries, or the API Explorer, or directly over HTTP.

Note that you cannot use the Pub/Sub Cloud IAM API to manage policies at the Google Cloud project level.

The following sections give examples for how to set and get a policy, and how to test what permissions a caller has for a given resource.

Getting a policy

The getIamPolicy() method allows you to get an existing policy. This method returns a JSON object containing the policy associated with the resource.

Here is some sample code to get a policy for a subscription:

C#

Before trying this sample, follow the C# setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub C# API reference documentation. 

SubscriptionName subscriptionName = new SubscriptionName(projectId, subscriptionId);
Policy policy = publisher.GetIamPolicy(subscriptionName.ToString());
Console.WriteLine($"Subscription IAM Policy found for {subscriptionId}:");
Console.WriteLine(policy.Bindings);

GCLOUD COMMAND

Get the subscription policy:

gcloud pubsub subscriptions get-iam-policy \
   projects/${PROJECT}/subscriptions/${SUBSCRIPTION} \
   --format json

Output:

   {
     "etag": "BwUjMhCsNvY=",
     "bindings": [
       {
         "role": "roles/pubsub.admin",
         "members": [
           "user:user-1@gmail.com"
         ]
       },
       {
         "role": "roles/pubsub.editor",
         "members": [
           "serviceAccount:service-account-2@appspot.gserviceaccount.com",
           "user:user-3@gmail.com"
       }
     ]
   }

GO

Before trying this sample, follow the Go setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Go API reference documentation. 

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/iam"
	"cloud.google.com/go/pubsub"
)

func policy(w io.Writer, projectID, subID string) (*iam.Policy, error) {
	// projectID := "my-project-id"
	// subID := "my-sub"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return nil, fmt.Errorf("pubsub.NewClient: %v", err)
	}

	policy, err := client.Subscription(subID).IAM().Policy(ctx)
	if err != nil {
		return nil, fmt.Errorf("Subscription: %v", err)
	}
	for _, role := range policy.Roles() {
		fmt.Fprintf(w, "%q: %q\n", role, policy.Members(role))
	}
	return policy, nil
}

JAVA

Before trying this sample, follow the Java setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Java API reference documentation. 

try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
  ProjectSubscriptionName subscriptionName =
      ProjectSubscriptionName.of(projectId, subscriptionId);
  Policy policy = subscriptionAdminClient.getIamPolicy(subscriptionName.toString());
  if (policy == null) {
    // subscription was not found
  }
  return policy;
}

NODE.JS

Before trying this sample, follow the Node.js setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Node.js API reference documentation. 

/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const subscriptionName = 'YOUR_SUBSCRIPTION_NAME';

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

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function getSubscriptionPolicy() {
  // Retrieves the IAM policy for the subscription
  const [policy] = await pubSubClient
    .subscription(subscriptionName)
    .iam.getPolicy();

  console.log(`Policy for subscription: ${JSON.stringify(policy.bindings)}.`);
}

getSubscriptionPolicy().catch(console.error);

PHP

Before trying this sample, follow the PHP setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub PHP API reference documentation. 

use Google\Cloud\PubSub\PubSubClient;

/**
 * Prints the policy for a PubSub subscription.
 *
 * @param string $projectId  The Google project ID.
 * @param string $subscriptionName  The Pub/Sub subscription name.
 */
function get_subscription_policy($projectId, $subscriptionName)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $subscription = $pubsub->subscription($subscriptionName);
    $policy = $subscription->iam()->policy();
    print_r($policy);
}

PYTHON

Before trying this sample, follow the Python setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Python API reference documentation. 

from google.cloud import pubsub_v1

# TODO(developer)
# project_id = "your-project-id"
# subscription_id = "your-subscription-id"

client = pubsub_v1.SubscriberClient()
subscription_path = client.subscription_path(project, subscription_id)

policy = client.get_iam_policy(subscription_path)

print("Policy for subscription {}:".format(subscription_path))
for binding in policy.bindings:
    print("Role: {}, Members: {}".format(binding.role, binding.members))

client.close()

RUBY

Before trying this sample, follow the Ruby setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Ruby API reference documentation. 

# project_id        = "Your Google Cloud Project ID"
# subscription_name = "Your Pubsub subscription name"
require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new project: project_id

subscription = pubsub.subscription subscription_name
policy       = subscription.policy

puts "Subscription policy:"
puts policy.roles

Here is some sample code to get a policy for a topic:

C#

Before trying this sample, follow the C# setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub C# API reference documentation. 

TopicName topicName = new TopicName(projectId, topicId);
Policy policy = publisher.GetIamPolicy(topicName.ToString());
Console.WriteLine($"Topic IAM Policy found for {topicId}:");
Console.WriteLine(policy.Bindings);

GCLOUD COMMAND

Get the topic policy

gcloud pubsub topics get-iam-policy \
    projects/${PROJECT}/topics/${TOPIC} \
    --format json

Output:

{
  "etag": "BwUjMhCsNvY=",
  "bindings": [
    {
      "role":" roles/pubsub.viewer",
      "members": [
        "user:user-1@gmail.com"
      ]
    }
  ]
}

GO

Before trying this sample, follow the Go setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Go API reference documentation. 

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/iam"
	"cloud.google.com/go/pubsub"
)

func policy(w io.Writer, projectID, topicID string) (*iam.Policy, error) {
	// projectID := "my-project-id"
	// topicID := "my-topic"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return nil, fmt.Errorf("pubsub.NewClient: %v", err)
	}

	policy, err := client.Topic(topicID).IAM().Policy(ctx)
	if err != nil {
		return nil, fmt.Errorf("Policy: %v", err)
	}
	for _, role := range policy.Roles() {
		fmt.Fprint(w, policy.Members(role))
	}
	return policy, nil
}

JAVA

Before trying this sample, follow the Java setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Java API reference documentation. 

try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {
  ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
  Policy policy = topicAdminClient.getIamPolicy(topicName.toString());
  if (policy == null) {
    // topic iam policy was not found
  }
  return policy;
}

NODE.JS

Before trying this sample, follow the Node.js setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Node.js API reference documentation. 

/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const topicName = 'YOUR_TOPIC_NAME';

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

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function getTopicPolicy() {
  // Retrieves the IAM policy for the topic
  const [policy] = await pubSubClient.topic(topicName).iam.getPolicy();
  console.log('Policy for topic: %j.', policy.bindings);
}

getTopicPolicy().catch(console.error);

PHP

Before trying this sample, follow the PHP setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub PHP API reference documentation. 

use Google\Cloud\PubSub\PubSubClient;

/**
 * Prints the policy for a Pub/Sub topic.
 *
 * @param string $projectId  The Google project ID.
 * @param string $topicName  The Pub/Sub topic name.
 */
function get_topic_policy($projectId, $topicName)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $policy = $topic->iam()->policy();
    print_r($policy);
}

PYTHON

Before trying this sample, follow the Python setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Python API reference documentation. 

from google.cloud import pubsub_v1

# TODO(developer)
# project_id = "your-project-id"
# topic_id = "your-topic-id"

client = pubsub_v1.PublisherClient()
topic_path = client.topic_path(project, topic_id)

policy = client.get_iam_policy(topic_path)

print("Policy for topic {}:".format(topic_path))
for binding in policy.bindings:
    print("Role: {}, Members: {}".format(binding.role, binding.members))

RUBY

Before trying this sample, follow the Ruby setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Ruby API reference documentation. 

# project_id = "Your Google Cloud Project ID"
# topic_name = "Your Pubsub topic name"
require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new project: project_id

topic  = pubsub.topic topic_name
policy = topic.policy

puts "Topic policy:"
puts policy.roles

Setting a policy

The setIamPolicy() method lets you attach a policy to a resource. The setIamPolicy() method takes a SetIamPolicyRequest, which contains the policy to be set and the resource to which the policy is attached. It returns the resulting policy.

Here is some sample code to set a policy for a subscription:

C#

Before trying this sample, follow the C# setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub C# API reference documentation.

pubsub/api/PubsubSample/Program.cs 
Policy policy = new Policy
{
    Bindings =
    {
        new Binding { Role = roleToBeAddedToPolicy,
            Members = { member } }
    }
};
SetIamPolicyRequest request = new SetIamPolicyRequest
{
    Resource = new SubscriptionName(projectId, subscriptionId).ToString(),
    Policy = policy
};
Policy response = publisher.SetIamPolicy(request);
Console.WriteLine($"Subscription IAM Policy updated: {response}");

GCLOUD COMMAND

1. Save the policy for the subscription.

gcloud pubsub subscriptions get-iam-policy \
   projects/${PROJECT}/subscriptions/${SUBSCRIPTION} \
   --format json > subscription_policy.json

2. Open subscription_policy.json and update bindings by giving appropriate roles to appropriate members. For more information about working with subscription_policy.json files, see Cloud Identity and Access Management policy document.

   {
     "etag": "BwUjMhCsNvY=",
     "bindings": [
       {
         "role": "roles/pubsub.admin",
         "members": [
           "user:user-1@gmail.com"
         ]
       },
       {
         "role": "roles/pubsub.editor",
         "members": [
           "serviceAccount:service-account-2@appspot.gserviceaccount.com"
       }
     ]
   }

3. Apply the new subscription policy.

gcloud pubsub subscriptions set-iam-policy \
  projects/${PROJECT}/subscriptions/${SUBSCRIPTION} \
  subscription_policy.json

GO

Before trying this sample, follow the Go setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Go API reference documentation. 

import (
	"context"
	"fmt"

	"cloud.google.com/go/iam"
	"cloud.google.com/go/pubsub"
)

// addUsers adds all IAM users to a subscription.
func addUsers(projectID, subID string) error {
	// projectID := "my-project-id"
	// subID := "my-sub"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %v", err)
	}

	sub := client.Subscription(subID)
	policy, err := sub.IAM().Policy(ctx)
	if err != nil {
		return fmt.Errorf("Policy: %v", err)
	}
	// Other valid prefixes are "serviceAccount:", "user:"
	// See the documentation for more values.
	policy.Add(iam.AllUsers, iam.Viewer)
	policy.Add("group:cloud-logs@google.com", iam.Editor)
	if err := sub.IAM().SetPolicy(ctx, policy); err != nil {
		return fmt.Errorf("SetPolicy: %v", err)
	}
	// NOTE: It may be necessary to retry this operation if IAM policies are
	// being modified concurrently. SetPolicy will return an error if the policy
	// was modified since it was retrieved.
	return nil
}

JAVA

Before trying this sample, follow the Java setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Java API reference documentation. 

try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
  ProjectSubscriptionName subscriptionName =
      ProjectSubscriptionName.of(projectId, subscriptionId);
  Policy policy = subscriptionAdminClient.getIamPolicy(subscriptionName.toString());
  // Create a role => members binding
  Binding binding =
      Binding.newBuilder()
          .setRole(Role.viewer().toString())
          .addMembers(Identity.allAuthenticatedUsers().toString())
          .build();
  // Update policy
  Policy updatedPolicy = policy.toBuilder().addBindings(binding).build();

  updatedPolicy =
      subscriptionAdminClient.setIamPolicy(subscriptionName.toString(), updatedPolicy);
  return updatedPolicy;
}

NODE.JS

Before trying this sample, follow the Node.js setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Node.js API reference documentation. 

/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const subscriptionName = 'YOUR_SUBSCRIPTION_NAME';

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

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function setSubscriptionPolicy() {
  // The new IAM policy
  const newPolicy = {
    bindings: [
      {
        // Add a group as editors
        role: 'roles/pubsub.editor',
        members: ['group:cloud-logs@google.com'],
      },
      {
        // Add all users as viewers
        role: 'roles/pubsub.viewer',
        members: ['allUsers'],
      },
    ],
  };

  // Updates the IAM policy for the subscription
  const [updatedPolicy] = await pubSubClient
    .subscription(subscriptionName)
    .iam.setPolicy(newPolicy);

  console.log('Updated policy for subscription: %j', updatedPolicy.bindings);
}

setSubscriptionPolicy().catch(console.error);

PHP

use Google\Cloud\PubSub\PubSubClient;

/**
 * Adds a user to the policy for a Pub/Sub subscription.
 *
 * @param string $projectId  The Google project ID.
 * @param string $subscriptionName  The Pub/Sub subscription name.
 * @param string $userEmail  The user email to add to the policy.
 */
function set_subscription_policy($projectId, $subscriptionName, $userEmail)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $subscription = $pubsub->subscription($subscriptionName);
    $policy = $subscription->iam()->policy();
    $policy['bindings'][] = [
        'role' => 'roles/pubsub.subscriber',
        'members' => ['user:' . $userEmail]
    ];
    $subscription->iam()->setPolicy($policy);

    printf('User %s added to policy for %s' . PHP_EOL,
        $userEmail,
        $subscriptionName);
}

PYTHON

Before trying this sample, follow the Python setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Python API reference documentation. 

from google.cloud import pubsub_v1

# TODO(developer)
# project_id = "your-project-id"
# subscription_id = "your-subscription-id"

client = pubsub_v1.SubscriberClient()
subscription_path = client.subscription_path(project, subscription_id)

policy = client.get_iam_policy(subscription_path)

# Add all users as viewers.
policy.bindings.add(role="roles/pubsub.viewer", members=["allUsers"])

# Add a group as an editor.
policy.bindings.add(role="roles/editor", members=["group:cloud-logs@google.com"])

# Set the policy
policy = client.set_iam_policy(subscription_path, policy)

print("IAM policy for subscription {} set: {}".format(subscription_id, policy))

client.close()

RUBY

Before trying this sample, follow the Ruby setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Ruby API reference documentation. 

# project_id        = "Your Google Cloud Project ID"
# subscription_name = "Your Pubsub subscription name"
require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new project: project_id

subscription = pubsub.subscription subscription_name
subscription.policy do |policy|
  policy.add "roles/pubsub.subscriber",
             "serviceAccount:account-name@project-name.iam.gserviceaccount.com"
end

Here is some sample code to set a policy for a topic:

C#

Before trying this sample, follow the C# setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub C# API reference documentation. 

Policy policy = new Policy
{
    Bindings =
        {
            new Binding { Role = roleToBeAddedToPolicy,
                Members = { member } }
        }
};
SetIamPolicyRequest request = new SetIamPolicyRequest
{
    Resource = new TopicName(projectId, topicId).ToString(),
    Policy = policy
};
Policy response = publisher.SetIamPolicy(request);
Console.WriteLine($"Topic IAM Policy updated: {response}");

GCLOUD COMMAND

1. Save the policy for the topic.

gcloud pubsub topics get-iam-policy \
   projects/${PROJECT}/topics/${TOPIC} \
   --format json > topic_policy.json

2. Open topic_policy.json and update bindings by giving appropriate roles to appropriate members. For more information about working with subscription_policy.json files, see Cloud Identity and Access Management policy document. 

   {
     "etag": "BwUjMhCsNvY=",
     "bindings": [
       {
         "role": "roles/pubsub.editor",
         "members": [
           "user:user-1@gmail.com",
           "user:user-2@gmail.com"
         ]
       }
     ]
   }

3. Apply the new topic policy.

gcloud pubsub topics set-iam-policy  \
   projects/${PROJECT}topics/${TOPIC}     \
   topic_policy.json

GO

Before trying this sample, follow the Go setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Go API reference documentation. 

import (
	"context"
	"fmt"

	"cloud.google.com/go/iam"
	"cloud.google.com/go/pubsub"
)

func addUsers(projectID, topicID string) error {
	// projectID := "my-project-id"
	// topicID := "my-topic"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %v", err)
	}

	topic := client.Topic(topicID)
	policy, err := topic.IAM().Policy(ctx)
	if err != nil {
		return fmt.Errorf("Policy: %v", err)
	}
	// Other valid prefixes are "serviceAccount:", "user:"
	// See the documentation for more values.
	policy.Add(iam.AllUsers, iam.Viewer)
	policy.Add("group:cloud-logs@google.com", iam.Editor)
	if err := topic.IAM().SetPolicy(ctx, policy); err != nil {
		return fmt.Errorf("SetPolicy: %v", err)
	}
	// NOTE: It may be necessary to retry this operation if IAM policies are
	// being modified concurrently. SetPolicy will return an error if the policy
	// was modified since it was retrieved.
	return nil
}

JAVA

Before trying this sample, follow the Java setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Java API reference documentation. 

try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {
  String topicName = ProjectTopicName.format(projectId, topicId);
  Policy policy = topicAdminClient.getIamPolicy(topicName);
  // add role -> members binding
  Binding binding =
      Binding.newBuilder()
          .setRole(Role.viewer().toString())
          .addMembers(Identity.allAuthenticatedUsers().toString())
          .build();
  // create updated policy
  Policy updatedPolicy = Policy.newBuilder(policy).addBindings(binding).build();
  updatedPolicy = topicAdminClient.setIamPolicy(topicName, updatedPolicy);
  return updatedPolicy;
}

NODE.JS

Before trying this sample, follow the Node.js setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Node.js API reference documentation. 

/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const topicName = 'YOUR_TOPIC_NAME';

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

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function setTopicPolicy() {
  // The new IAM policy
  const newPolicy = {
    bindings: [
      {
        // Add a group as editors
        role: 'roles/pubsub.editor',
        members: ['group:cloud-logs@google.com'],
      },
      {
        // Add all users as viewers
        role: 'roles/pubsub.viewer',
        members: ['allUsers'],
      },
    ],
  };

  // Updates the IAM policy for the topic
  const [updatedPolicy] = await pubSubClient
    .topic(topicName)
    .iam.setPolicy(newPolicy);
  console.log('Updated policy for topic: %j', updatedPolicy.bindings);
}

setTopicPolicy().catch(console.error);

PHP

use Google\Cloud\PubSub\PubSubClient;

/**
 * Adds a user to the policy for a Pub/Sub topic.
 *
 * @param string $projectId  The Google project ID.
 * @param string $topicName  The Pub/Sub topic name.
 * @param string $userEmail  The user email to add to the policy.
 */
function set_topic_policy($projectId, $topicName, $userEmail)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $policy = $topic->iam()->policy();
    $policy['bindings'][] = [
        'role' => 'roles/pubsub.publisher',
        'members' => ['user:' . $userEmail]
    ];
    $topic->iam()->setPolicy($policy);

    printf('User %s added to policy for %s' . PHP_EOL,
        $userEmail,
        $topicName);
}

PYTHON

Before trying this sample, follow the Python setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Python API reference documentation. 

from google.cloud import pubsub_v1

# TODO(developer)
# project_id = "your-project-id"
# topic_id = "your-topic-id"

client = pubsub_v1.PublisherClient()
topic_path = client.topic_path(project, topic_id)

policy = client.get_iam_policy(topic_path)

# Add all users as viewers.
policy.bindings.add(role="roles/pubsub.viewer", members=["allUsers"])

# Add a group as a publisher.
policy.bindings.add(
    role="roles/pubsub.publisher", members=["group:cloud-logs@google.com"]
)

# Set the policy
policy = client.set_iam_policy(topic_path, policy)

print("IAM policy for topic {} set: {}".format(topic_id, policy))

RUBY

Before trying this sample, follow the Ruby setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Ruby API reference documentation. 

# project_id = "Your Google Cloud Project ID"
# topic_name = "Your Pubsub topic name"
require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new project: project_id

topic = pubsub.topic topic_name
topic.policy do |policy|
  policy.add "roles/pubsub.publisher",
             "serviceAccount:account_name@project_name.iam.gserviceaccount.com"
end

Testing permissions

You can use the testIamPermissions() method to check which of the given permissions the caller has for the given resource. It takes as parameters a resource name and a set of permissions, and returns the caller's subset of permissions.

Here is some sample code to test permissions for a subscription:

C#

Before trying this sample, follow the C# setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub C# API reference documentation. 

List<string> permissions = new List<string>();
permissions.Add("pubsub.subscriptions.get");
permissions.Add("pubsub.subscriptions.update");
TestIamPermissionsRequest request = new TestIamPermissionsRequest
{
    Resource = new SubscriptionName(_projectId, subscriptionId).ToString(),
    Permissions = { permissions }
};
TestIamPermissionsResponse response = publisher.TestIamPermissions(request);
return response;

GCLOUD COMMAND

gcloud iam list-testable-permissions \
   https://pubsub.googleapis.com/v1/projects/${PROJECT}/subscriptions/${SUBSCRIPTION} \
   --format json

Output:

 [
    {
     "name": "pubsub.subscriptions.consume",
     "stage": "GA"
   },
   {
     "name": "pubsub.subscriptions.delete",
     "stage": "GA"
   },
   {
     "name": "pubsub.subscriptions.get",
     "stage": "GA"
   },
   {
     "name": "pubsub.subscriptions.getIamPolicy",
     "stage": "GA"
    },
   {
     "name": "pubsub.subscriptions.setIamPolicy",
     "stage": "GA"
   },
   {
     "name": "pubsub.subscriptions.update",
     "stage": "GA"
   }
 ]

GO

Before trying this sample, follow the Go setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Go API reference documentation. 

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub"
)

func testPermissions(w io.Writer, projectID, subID string) ([]string, error) {
	// projectID := "my-project-id"
	// subID := "my-sub"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return nil, fmt.Errorf("pubsub.NewClient: %v", err)
	}

	sub := client.Subscription(subID)
	perms, err := sub.IAM().TestPermissions(ctx, []string{
		"pubsub.subscriptions.consume",
		"pubsub.subscriptions.update",
	})
	if err != nil {
		return nil, fmt.Errorf("TestPermissions: %v", err)
	}
	for _, perm := range perms {
		fmt.Fprintf(w, "Allowed: %v\n", perm)
	}

JAVA

Before trying this sample, follow the Java setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Java API reference documentation. 

try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {
  List<String> permissions = new LinkedList<>();
  permissions.add("pubsub.subscriptions.get");
  ProjectSubscriptionName subscriptionName =
      ProjectSubscriptionName.of(projectId, subscriptionId);
  TestIamPermissionsResponse testedPermissions =
      topicAdminClient.testIamPermissions(subscriptionName.toString(), permissions);
  return testedPermissions;
}

NODE.JS

Before trying this sample, follow the Node.js setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Node.js API reference documentation. 

/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const subscriptionName = 'YOUR_SUBSCRIPTION_NAME';

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

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function testSubscriptionPermissions() {
  const permissionsToTest = [
    'pubsub.subscriptions.consume',
    'pubsub.subscriptions.update',
  ];

  // Tests the IAM policy for the specified subscription
  const [permissions] = await pubSubClient
    .subscription(subscriptionName)
    .iam.testPermissions(permissionsToTest);

  console.log('Tested permissions for subscription: %j', permissions);
}

testSubscriptionPermissions().catch(console.error);

PHP

Before trying this sample, follow the PHP setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub PHP API reference documentation. 

use Google\Cloud\PubSub\PubSubClient;

/**
 * Prints the permissions of a subscription.
 *
 * @param string $projectId  The Google project ID.
 * @param string $subscriptionName  The Pub/Sub subscription name.
 */
function test_subscription_permissions($projectId, $subscriptionName)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $subscription = $pubsub->subscription($subscriptionName);
    $permissions = $subscription->iam()->testPermissions([
        'pubsub.subscriptions.consume',
        'pubsub.subscriptions.update'
    ]);
    foreach ($permissions as $permission) {
        printf('Permission: %s' . PHP_EOL, $permission);
    }
}

PYTHON

Before trying this sample, follow the Python setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Python API reference documentation. 

from google.cloud import pubsub_v1

# TODO(developer)
# project_id = "your-project-id"
# subscription_id = "your-subscription-id"

client = pubsub_v1.SubscriberClient()
subscription_path = client.subscription_path(project, subscription_id)

permissions_to_check = [
    "pubsub.subscriptions.consume",
    "pubsub.subscriptions.update",
]

allowed_permissions = client.test_iam_permissions(
    subscription_path, permissions_to_check
)

print(
    "Allowed permissions for subscription {}: {}".format(
        subscription_path, allowed_permissions
    )
)

client.close()

RUBY

Before trying this sample, follow the Ruby setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Ruby API reference documentation. 

# project_id        = "Your Google Cloud Project ID"
# subscription_name = "Your Pubsub subscription name"
require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new project: project_id

subscription = pubsub.subscription subscription_name
permissions  = subscription.test_permissions "pubsub.subscriptions.consume",
                                             "pubsub.subscriptions.update"

puts "Permission to consume" if permissions.include? "pubsub.subscriptions.consume"
puts "Permission to update" if permissions.include? "pubsub.subscriptions.update"

Here is some sample code to test permissions for a topic:

C#

Before trying this sample, follow the C# setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub C# API reference documentation. 

List<string> permissions = new List<string>();
permissions.Add("pubsub.topics.get");
permissions.Add("pubsub.topics.update");
TestIamPermissionsRequest request = new TestIamPermissionsRequest
{
    Resource = new TopicName(_projectId, topicId).ToString(),
    Permissions = { permissions }
};
TestIamPermissionsResponse response = publisher.TestIamPermissions(request);
return response;

GCLOUD COMMAND

gcloud iam list-testable-permissions \
   https://pubsub.googleapis.com/v1/projects/${PROJECT}/topics/${TOPIC} \
   --format json

Output

 [
   {
     "name": "pubsub.topics.attachSubscription",
     "stage": "GA"
   },
   {
     "name": "pubsub.topics.delete",
     "stage": "GA"
   },
   {
     "name": "pubsub.topics.get",
     "stage": "GA"
   },
   {
     "name": "pubsub.topics.getIamPolicy",
     "stage": "GA"
   },
   {
     "name": "pubsub.topics.publish",
     "stage": "GA"
   },
   {
     "name": "pubsub.topics.setIamPolicy",
     "stage": "GA"
   },
   {
     "name": "pubsub.topics.update",
     "stage": "GA"
   }
 ]

GO

Before trying this sample, follow the Go setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Go API reference documentation. 

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub"
)

func testPermissions(w io.Writer, projectID, topicID string) ([]string, error) {
	// projectID := "my-project-id"
	// topicID := "my-topic"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return nil, fmt.Errorf("pubsub.NewClient: %v", err)
	}

	topic := client.Topic(topicID)
	perms, err := topic.IAM().TestPermissions(ctx, []string{
		"pubsub.topics.publish",
		"pubsub.topics.update",
	})
	if err != nil {
		return nil, fmt.Errorf("TestPermissions: %v", err)
	}
	for _, perm := range perms {
		fmt.Fprintf(w, "Allowed: %v\n", perm)
	}
	return perms, nil
}

JAVA

Before trying this sample, follow the Java setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Java API reference documentation. 

try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {
  List<String> permissions = new LinkedList<>();
  permissions.add("pubsub.topics.get");
  ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
  TestIamPermissionsResponse testedPermissions =
      topicAdminClient.testIamPermissions(topicName.toString(), permissions);
  return testedPermissions;
}

NODE.JS

Before trying this sample, follow the Node.js setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Node.js API reference documentation. 

/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const topicName = 'YOUR_TOPIC_NAME';

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

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function testTopicPermissions() {
  const permissionsToTest = [
    'pubsub.topics.attachSubscription',
    'pubsub.topics.publish',
    'pubsub.topics.update',
  ];

  // Tests the IAM policy for the specified topic
  const [permissions] = await pubSubClient
    .topic(topicName)
    .iam.testPermissions(permissionsToTest);

  console.log('Tested permissions for topic: %j', permissions);
}

testTopicPermissions().catch(console.error);

PHP

Before trying this sample, follow the PHP setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub PHP API reference documentation. 

use Google\Cloud\PubSub\PubSubClient;

/**
 * Prints the permissions of a topic.
 *
 * @param string $projectId  The Google project ID.
 * @param string $topicName  The Pub/Sub topic name.
 */
function test_topic_permissions($projectId, $topicName)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $permissions = $topic->iam()->testPermissions([
        'pubsub.topics.attachSubscription',
        'pubsub.topics.publish',
        'pubsub.topics.update'
    ]);
    foreach ($permissions as $permission) {
        printf('Permission: %s' . PHP_EOL, $permission);
    }
}

PYTHON

Before trying this sample, follow the Python setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Python API reference documentation. 

from google.cloud import pubsub_v1

# TODO(developer)
# project_id = "your-project-id"
# topic_id = "your-topic-id"

client = pubsub_v1.PublisherClient()
topic_path = client.topic_path(project, topic_id)

permissions_to_check = ["pubsub.topics.publish", "pubsub.topics.update"]

allowed_permissions = client.test_iam_permissions(topic_path, permissions_to_check)

print(
    "Allowed permissions for topic {}: {}".format(topic_path, allowed_permissions)
)

RUBY

Before trying this sample, follow the Ruby setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Ruby API reference documentation. 

# project_id = "Your Google Cloud Project ID"
# topic_name = "Your Pubsub topic name"
require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new project: project_id

topic       = pubsub.topic topic_name
permissions = topic.test_permissions "pubsub.topics.attachSubscription",
                                     "pubsub.topics.publish", "pubsub.topics.update"

puts "Permission to attach subscription" if permissions.include? "pubsub.topics.attachSubscription"
puts "Permission to publish" if permissions.include? "pubsub.topics.publish"
puts "Permission to update" if permissions.include? "pubsub.topics.update"

Sample use case: cross-project communication

Pub/Sub Cloud Identity and Access Management is useful for fine-tuning access in cross-project communication. For example, suppose a service account in Cloud Project A wants to publish messages to a topic in Cloud Project B. You could accomplish this by granting the service account Edit permission in Cloud Project B. However, this approach is often too coarse. You can use the Cloud IAM API to achieve a more fine-grained level of access.

Cross-project communication

For example, this snippet uses the setIamPolicy() method in project-b and a prepared topic_policy.json file to grant the service account foobar@project-a.iam.gserviceaccount.com of project-a the publisher role on the topic projects/project-b/topics/topic-b:

gcloud pubsub topics set-iam-policy \
    projects/project-b/topics/topic-b \
    topic_policy.json
Output: 
Updated Cloud IAM policy for topic topic-b.
bindings:
- members:
  - serviceAccount:foobar@project-a.iam.gserviceaccount.com
  role: roles/pubsub.publisher
etag: BwWGrQYX6R4=

Partial availability behavior

Authorization checks depend on the Cloud IAM subsystem. In order to offer consistently low response latency for data operations (publishing and message consumption), the system may fall back on cached Cloud IAM policies. For information about when your changes will take effect, see the Cloud IAM documentation.