Access control with Identity and Access Management

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

Overview

Pub/Sub usesIdentity and Access Management (IAM) for accesscontrol.

IAM allows you to grant specificroles to users, groups,and service accounts, giving them the necessarypermissions to perform theirtasks. You can grant these IAM roles using theGoogle Cloud console or the IAM API.

In Pub/Sub, access control can be configured at the projectlevel and at the individual resource level. Here are some examples forusing Pub/Sub access control:

  • Grant access on a per-resource basis, rather than for the whole Cloud project.

  • Grant access with limited capabilities, such as to only publish messages to atopic, or to only consume messages from a subscription, but not to delete thetopic or subscription.

  • Grant access to all Pub/Sub resources within a project to agroup of developers.

If you have view-only access to a single resource such as a topic or asubscription, you cannot view the resource using the Google Cloud console.Instead, you can use Google Cloud CLI to view the resource.

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

Note: Pub/Sub is not associated with any specific IP address.This is relevant if you rely on IP-based firewall rules.

Types of roles in Pub/Sub

Similar to other Google Cloud products, Pub/Sub supportsthree types of roles:

Required Pub/Sub permissions

The following sections lists Pub/Sub permissions required foraccessing different Pub/Sub resources.

Required permissions for topics

The following table outlines the required permissions for eachPub/Sub API method related to topics. It shows whichIAM permission is needed to call each method, along with a description ofwhat the method does.

MethodDescriptionRequired permission
projects.topics.createCreates the given topic with the given name.pubsub.topics.create on the containing Cloud project
projects.topics.deleteDeletes the topic with the given name.pubsub.topics.delete on the requested topic
projects.topics.getGets the configuration of a topic.pubsub.topics.get on the requested topic
projects.topics.getIamPolicyGets the IAM access control policy for a topic.pubsub.topics.getIamPolicy on the requested topic
projects.topics.listLists all topics.pubsub.topics.list on the requested Cloud project
projects.topics.patchUpdates an existing topic.pubsub.topics.update on the requested topic
projects.topics.publishAdds one or more messages to the topic.pubsub.topics.publish on the requested topic
projects.topics.setIamPolicySets the IAM access control policy for a topic.pubsub.topics.setIamPolicy on the requested topic
projects.topics.testIamPermissionsReturns permissions that a caller has on the specified resource.None

Required permissions for subscriptions

The following table outlines the required permissions for eachPub/Sub API method related to subscriptions.It shows which IAM permission is needed to call each method, along with adescription of what the method does.

MethodDescriptionRequired permission
projects.subscriptions.acknowledgeAcknowledges the messages associated with the ack_ids in the AcknowledgeRequest.pubsub.subscriptions.consume on the requested subscription
projects.subscriptions.createCreates a subscription to a given topic.pubsub.subscriptions.create on the containing Cloud project andpubsub.topics.attachSubscription on the requested topic. For creating a Subscription S in Project A that is attached 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.deleteDeletes an existing subscription.pubsub.subscriptions.delete on the requested subscription
projects.subscriptions.detachDetaches a subscription from this topic.pubsub.subscriptions.detach on the subscription
projects.subscriptions.getGets the configuration details of a subscription.pubsub.subscriptions.get on the requested subscription
projects.subscriptions.getIamPolicyGets the IAM access control policy for a subscription.pubsub.subscriptions.getIamPolicy on the requested subscription
projects.subscriptions.listLists matching subscriptions.pubsub.subscriptions.list on the requested Cloud project
projects.subscriptions.modifyAckDeadlineModifies the ack deadline for a specific message.pubsub.subscriptions.consume on the requested subscription
projects.subscriptions.modifyPushConfigModifies the pushConfig for a specified subscription.pubsub.subscriptions.update on the requested subscription
projects.subscriptions.patchUpdates an existing subscription.pubsub.subscriptions.update on the requested subscription
projects.subscriptions.pullPulls messages from the server.pubsub.subscriptions.consume on the requested subscription
projects.subscriptions.seekSeeks an existing subscription to a point in time or a snapshot.pubsub.subscriptions.consume on the requested subscription andpubsub.snapshots.seek on the requested snapshot, if any.
projects.subscriptions.setIamPolicySets the IAM access control policy for a subscription.pubsub.subscriptions.setIamPolicy on the requested subscription
projects.subscriptions.testIamPermissionsReturns permissions that a caller has on the specified resource.None

Required permissions for schemas

The following table outlines the required permissions for eachPub/Sub API method related to schemas.It shows which IAM permission is needed to call each method, along with adescription of what the method does.

MethodDescriptionRequired permission
projects.schemas.commitCommits a new schema revision.pubsub.schemas.commit on the requested schema
projects.schemas.createCreates a schema.pubsub.schemas.create on the containing Cloud project
projects.schemas.deleteDeletes a schema.pubsub.schemas.delete on the requested schema
projects.schemas.deleteRevisionDeletes a specific schema revision.pubsub.schemas.delete on the requested schema
projects.schemas.getGets a schema.pubsub.schemas.get on the requested schema
projects.schemas.getIamPolicyGets the IAM access control policy for a schema.pubsub.schemas.getIamPolicy on the requested schema
projects.schemas.listLists schemas in a project.pubsub.schemas.list on the requested Cloud project
projects.schemas.listRevisionsLists all schema revisions for the named schema.pubsub.schemas.listRevisions on the requested schema
projects.schemas.rollbackCreates a new schema revision from a previous revision.pubsub.schemas.rollback on the requested schema
projects.schemas.validateValidates a schema definition.pubsub.schemas.validate on the containing Cloud project
projects.schemas.validateMessageValidates a message against a schema.pubsub.schemas.validate on the containing Cloud project

Required permissions for snapshots

The following table outlines the required permissions for eachPub/Sub API method related to snapshots.It shows which IAM permission is needed to call each method, along with adescription of what the method does.

REST methodDescriptionRequired permission
projects.snapshots.createCreates a snapshot from the requested subscription.pubsub.snapshots.create on the containing Cloud project andpubsub.subscriptions.consume permission on the source subscription.
projects.snapshots.deleteRemoves an existing snapshot.pubsub.snapshots.delete on the requested snapshot
projects.snapshots.getIamPolicyGets the IAM access control policy for a snapshot.pubsub.snapshots.getIamPolicy on the requested snapshot
projects.snapshots.listLists the existing snapshots.pubsub.snapshots.list on the requested Cloud project
projects.snapshots.patchUpdates an existing snapshot.pubsub.snapshots.update on the requested snapshot
projects.snapshots.setIamPolicySets the IAM access control policy for a snapshot.pubsub.snapshots.setIamPolicy on the requested snapshot
projects.snapshots.testIamPermissionsReturns permissions that a caller has on the specified resource.None

Available Pub/Sub roles

The following table lists all Pub/Sub roles and thepermissions associated with each role:

RolePermissions

Pub/Sub Admin

(roles/pubsub.admin)

Provides full access to topics and subscriptions.

Lowest-level resources where you can grant this role:

  • Schema
  • Snapshot
  • Subscription
  • Topic

cloudkms.keyHandles.*

  • cloudkms.keyHandles.create
  • cloudkms.keyHandles.get
  • cloudkms.keyHandles.list

cloudkms.operations.get

cloudkms.projects.showEffectiveAutokeyConfig

pubsub.*

  • pubsub.messageTransforms.validate
  • pubsub.schemas.attach
  • pubsub.schemas.commit
  • pubsub.schemas.create
  • pubsub.schemas.delete
  • pubsub.schemas.get
  • pubsub.schemas.getIamPolicy
  • pubsub.schemas.list
  • pubsub.schemas.listRevisions
  • pubsub.schemas.rollback
  • pubsub.schemas.setIamPolicy
  • pubsub.schemas.validate
  • pubsub.snapshots.create
  • pubsub.snapshots.createTagBinding
  • pubsub.snapshots.delete
  • pubsub.snapshots.deleteTagBinding
  • pubsub.snapshots.get
  • pubsub.snapshots.getIamPolicy
  • pubsub.snapshots.list
  • pubsub.snapshots.listEffectiveTags
  • pubsub.snapshots.listTagBindings
  • pubsub.snapshots.seek
  • pubsub.snapshots.setIamPolicy
  • pubsub.snapshots.update
  • pubsub.subscriptions.consume
  • pubsub.subscriptions.create
  • pubsub.subscriptions.createTagBinding
  • pubsub.subscriptions.delete
  • pubsub.subscriptions.deleteTagBinding
  • pubsub.subscriptions.get
  • pubsub.subscriptions.getIamPolicy
  • pubsub.subscriptions.list
  • pubsub.subscriptions.listEffectiveTags
  • pubsub.subscriptions.listTagBindings
  • pubsub.subscriptions.setIamPolicy
  • pubsub.subscriptions.update
  • pubsub.topics.attachSubscription
  • pubsub.topics.create
  • pubsub.topics.createTagBinding
  • pubsub.topics.delete
  • pubsub.topics.deleteTagBinding
  • pubsub.topics.detachSubscription
  • pubsub.topics.get
  • pubsub.topics.getIamPolicy
  • pubsub.topics.list
  • pubsub.topics.listEffectiveTags
  • pubsub.topics.listTagBindings
  • pubsub.topics.publish
  • pubsub.topics.setIamPolicy
  • pubsub.topics.update
  • pubsub.topics.updateTag

resourcemanager.projects.get

serviceusage.consumerpolicy.analyze

serviceusage.consumerpolicy.get

serviceusage.effectivepolicy.get

serviceusage.groups.*

  • serviceusage.groups.list
  • serviceusage.groups.listExpandedMembers
  • serviceusage.groups.listMembers

serviceusage.quotas.get

serviceusage.services.get

serviceusage.services.list

serviceusage.values.test

Pub/Sub Editor

(roles/pubsub.editor)

Provides access to modify topics and subscriptions, and access to publishand consume messages.

Lowest-level resources where you can grant this role:

  • Schema
  • Snapshot
  • Subscription
  • Topic

cloudkms.keyHandles.*

  • cloudkms.keyHandles.create
  • cloudkms.keyHandles.get
  • cloudkms.keyHandles.list

cloudkms.operations.get

cloudkms.projects.showEffectiveAutokeyConfig

pubsub.messageTransforms.validate

pubsub.schemas.attach

pubsub.schemas.commit

pubsub.schemas.create

pubsub.schemas.delete

pubsub.schemas.get

pubsub.schemas.list

pubsub.schemas.listRevisions

pubsub.schemas.rollback

pubsub.schemas.validate

pubsub.snapshots.create

pubsub.snapshots.createTagBinding

pubsub.snapshots.delete

pubsub.snapshots.deleteTagBinding

pubsub.snapshots.get

pubsub.snapshots.list

pubsub.snapshots.listEffectiveTags

pubsub.snapshots.listTagBindings

pubsub.snapshots.seek

pubsub.snapshots.update

pubsub.subscriptions.consume

pubsub.subscriptions.create

pubsub.subscriptions.createTagBinding

pubsub.subscriptions.delete

pubsub.subscriptions.deleteTagBinding

pubsub.subscriptions.get

pubsub.subscriptions.list

pubsub.subscriptions.listEffectiveTags

pubsub.subscriptions.listTagBindings

pubsub.subscriptions.update

pubsub.topics.attachSubscription

pubsub.topics.create

pubsub.topics.createTagBinding

pubsub.topics.delete

pubsub.topics.deleteTagBinding

pubsub.topics.detachSubscription

pubsub.topics.get

pubsub.topics.list

pubsub.topics.listEffectiveTags

pubsub.topics.listTagBindings

pubsub.topics.publish

pubsub.topics.update

pubsub.topics.updateTag

resourcemanager.projects.get

serviceusage.consumerpolicy.analyze

serviceusage.consumerpolicy.get

serviceusage.effectivepolicy.get

serviceusage.groups.*

  • serviceusage.groups.list
  • serviceusage.groups.listExpandedMembers
  • serviceusage.groups.listMembers

serviceusage.quotas.get

serviceusage.services.get

serviceusage.services.list

serviceusage.values.test

Pub/Sub Publisher

(roles/pubsub.publisher)

Provides access to publish messages to a topic.

Lowest-level resources where you can grant this role:

  • Topic

pubsub.topics.publish

Cloud Pub/Sub Service Agent

(roles/pubsub.serviceAgent)

Grants Cloud Pub/Sub Service Account access to manage resources.

Warning: Do not grant service agent roles to any principals exceptservice agents.

iam.serviceAccounts.get

iam.serviceAccounts.getAccessToken

iam.serviceAccounts.getOpenIdToken

iam.serviceAccounts.implicitDelegation

iam.serviceAccounts.list

iam.serviceAccounts.signBlob

iam.serviceAccounts.signJwt

resourcemanager.projects.get

resourcemanager.projects.list

serviceusage.services.use

Pub/Sub Subscriber

(roles/pubsub.subscriber)

Provides access to consume messages from a subscription and to attachsubscriptions to a topic.

Lowest-level resources where you can grant this role:

  • Snapshot
  • Subscription
  • Topic

pubsub.snapshots.seek

pubsub.subscriptions.consume

pubsub.topics.attachSubscription

Pub/Sub Viewer

(roles/pubsub.viewer)

Provides access to view topics and subscriptions.

Lowest-level resources where you can grant this role:

  • Schema
  • Snapshot
  • Subscription
  • Topic

pubsub.messageTransforms.validate

pubsub.schemas.get

pubsub.schemas.list

pubsub.schemas.listRevisions

pubsub.schemas.validate

pubsub.snapshots.get

pubsub.snapshots.list

pubsub.snapshots.listEffectiveTags

pubsub.snapshots.listTagBindings

pubsub.subscriptions.get

pubsub.subscriptions.list

pubsub.subscriptions.listEffectiveTags

pubsub.subscriptions.listTagBindings

pubsub.topics.get

pubsub.topics.list

pubsub.topics.listEffectiveTags

pubsub.topics.listTagBindings

resourcemanager.projects.get

serviceusage.consumerpolicy.analyze

serviceusage.consumerpolicy.get

serviceusage.effectivepolicy.get

serviceusage.groups.*

  • serviceusage.groups.list
  • serviceusage.groups.listExpandedMembers
  • serviceusage.groups.listMembers

serviceusage.quotas.get

serviceusage.services.get

serviceusage.services.list

serviceusage.values.test

Controlling access through the Google Cloud console

You can use the Google Cloud console to manage access control for your topicsand projects.

To set access controls at the project level, follow these steps:

  1. In the Google Cloud console, go to the IAM page.

    Go to IAM

  2. Select your project.

  3. ClickAdd.

  4. Type in one or more principal names.

  5. In theSelect a role list, select the role you want to grant.

  6. ClickSave.

  7. Verify that the principal is listed with the role that you granted.

To set access controls for topics and subscriptions, follow these steps:

  1. In the Google Cloud console, go to the Pub/SubTopics list.

    Go to Topics

  2. If needed, select your Pub/Sub-enabled project.

  3. Perform one of the following steps:

    • To set roles for one or more topics, select the topics.

    • To set roles for a subscription attached to a topic, click the topicID. In theTopic details page, click the subscription ID. TheSubscription details page appears.

  4. If the info panel is hidden, clickShow info panel.

  5. In thePermissions tab, clickAdd principal.

  6. Type in one or more principal names.

  7. In theSelect a role list, select the role you want to grant.

  8. ClickSave.

Controlling access through the IAM API

The Pub/Sub IAM API lets you set and get policies onindividual topics and subscriptions in a project, and test a user's permissionsfor a given resource. As with the regular Pub/Sub methods, youcan invoke the IAM API methods through the client libraries, or the APIExplorer, or directly over HTTP.

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

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

Get a policy

ThegetIamPolicy() method allows you toget an existing policy.This method returns a JSON object containing the policy associated with theresource.

Here is some sample code toget a policy for a subscription:

C#

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

usingGoogle.Cloud.Iam.V1;usingGoogle.Cloud.PubSub.V1;publicclassGetSubscriptionIamPolicySample{publicPolicyGetSubscriptionIamPolicy(stringprojectId,stringsubscriptionId){PublisherServiceApiClientpublisher=PublisherServiceApiClient.Create();SubscriptionNamesubscriptionName=SubscriptionName.FromProjectSubscription(projectId,subscriptionId);Policypolicy=publisher.IAMPolicyClient.GetIamPolicy(newGetIamPolicyRequest{ResourceAsResourceName=subscriptionName});returnpolicy;}}

gcloud

Get the subscription policy:

gcloudpubsubsubscriptionsget-iam-policy\projects/${PROJECT}/subscriptions/${SUBSCRIPTION}\--formatjson

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

The following sample uses the major version of the Go Pub/Sub client library (v2). If you are still using the v1 library, seethe migration guide to v2.To see a list of v1 code samples, seethe deprecated code samples.

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

import("context""fmt""io""cloud.google.com/go/iam/apiv1/iampb""cloud.google.com/go/pubsub/v2")funcgetIAMPolicy(wio.Writer,projectID,subscriptionstring)error{// projectID := "my-project-id"// subscription := "projects/my-project/subscriptions/my-sub"ctx:=context.Background()client,err:=pubsub.NewClient(ctx,projectID)iferr!=nil{returnfmt.Errorf("pubsub.NewClient: %w",err)}deferclient.Close()req:=&iampb.GetIamPolicyRequest{Resource:subscription,}policy,err:=client.SubscriptionAdminClient.GetIamPolicy(ctx,req)iferr!=nil{returnfmt.Errorf("Policy: %w",err)}for_,b:=rangepolicy.Bindings{for_,m:=rangeb.Members{fmt.Fprintf(w,"role: %s, member: %s\n",b.Role,m)}}returnnil}

Java

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

importcom.google.cloud.pubsub.v1.SubscriptionAdminClient;importcom.google.iam.v1.GetIamPolicyRequest;importcom.google.iam.v1.Policy;importcom.google.pubsub.v1.ProjectSubscriptionName;importjava.io.IOException;publicclassGetSubscriptionPolicyExample{publicstaticvoidmain(String...args)throwsException{// TODO(developer): Replace these variables before running the sample.StringprojectId="your-project-id";StringsubscriptionId="your-subscription-id";getSubscriptionPolicyExample(projectId,subscriptionId);}publicstaticvoidgetSubscriptionPolicyExample(StringprojectId,StringsubscriptionId)throwsIOException{try(SubscriptionAdminClientsubscriptionAdminClient=SubscriptionAdminClient.create()){ProjectSubscriptionNamesubscriptionName=ProjectSubscriptionName.of(projectId,subscriptionId);GetIamPolicyRequestgetIamPolicyRequest=GetIamPolicyRequest.newBuilder().setResource(subscriptionName.toString()).build();Policypolicy=subscriptionAdminClient.getIamPolicy(getIamPolicyRequest);System.out.println("Subscription policy: "+policy);}}}

Node.js

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

/** * TODO(developer): Uncomment this variable before running the sample. */// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';// Imports the Google Cloud client libraryconst{PubSub}=require('@google-cloud/pubsub');// Creates a client; cache this for further useconstpubSubClient=newPubSub();asyncfunctiongetSubscriptionPolicy(subscriptionNameOrId){// Retrieves the IAM policy for the subscriptionconst[policy]=awaitpubSubClient.subscription(subscriptionNameOrId).iam.getPolicy();console.log(`Policy for subscription:${JSON.stringify(policy.bindings)}.`);}

Node.js

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

/** * TODO(developer): Uncomment this variable before running the sample. */// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';// Imports the Google Cloud client libraryimport{PubSub,Policy}from'@google-cloud/pubsub';// Creates a client; cache this for further useconstpubSubClient=newPubSub();asyncfunctiongetSubscriptionPolicy(subscriptionNameOrId:string){// Retrieves the IAM policy for the subscriptionconst[policy]:[Policy]=awaitpubSubClient.subscription(subscriptionNameOrId).iam.getPolicy();console.log(`Policy for subscription:${JSON.stringify(policy.bindings)}.`);}

PHP

Before trying this sample, follow the PHP setup instructions inQuickstart: Using Client Libraries. For more information, see thePub/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 inQuickstart: Using Client Libraries. For more information, see thePub/Sub Python API reference documentation.

fromgoogle.cloudimportpubsub_v1# TODO(developer): Choose an existing subscription.# project_id = "your-project-id"# subscription_id = "your-subscription-id"client=pubsub_v1.SubscriberClient()subscription_path=client.subscription_path(project_id,subscription_id)policy=client.get_iam_policy(request={"resource":subscription_path})print("Policy for subscription{}:".format(subscription_path))forbindinginpolicy.bindings:print("Role:{}, Members:{}".format(binding.role,binding.members))client.close()

Ruby

The following sample uses Ruby Pub/Sub client library v3. If you are still using the v2 library, see the migration guide to v3.To see a list of Ruby v2 code samples, seethe deprecated code samples.

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

# subscription_id = "your-subscription-id"pubsub=Google::Cloud::PubSub.newpolicy=pubsub.iam.get_iam_policy\resource:pubsub.subscription_path(subscription_id)puts"Subscription policy:"putspolicy.bindings.first.role
Here is some sample code toget a policy for a topic:

C#

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

usingGoogle.Cloud.Iam.V1;usingGoogle.Cloud.PubSub.V1;publicclassGetTopicIamPolicySample{publicPolicyGetTopicIamPolicy(stringprojectId,stringtopicId){PublisherServiceApiClientpublisher=PublisherServiceApiClient.Create();TopicNametopicName=TopicName.FromProjectTopic(projectId,topicId);Policypolicy=publisher.IAMPolicyClient.GetIamPolicy(newGetIamPolicyRequest{ResourceAsResourceName=topicName});returnpolicy;}}

gcloud

Get the topic policy

gcloudpubsubtopicsget-iam-policy\projects/${PROJECT}/topics/${TOPIC}\--formatjson

Output:

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

Go

The following sample uses the major version of the Go Pub/Sub client library (v2). If you are still using the v1 library, seethe migration guide to v2.To see a list of v1 code samples, seethe deprecated code samples.

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

import("context""fmt""io""cloud.google.com/go/iam/apiv1/iampb""cloud.google.com/go/pubsub/v2")funcgetIAMPolicy(wio.Writer,projectID,topicIDstring)error{// projectID := "my-project-id"// topicID := "my-topic"ctx:=context.Background()client,err:=pubsub.NewClient(ctx,projectID)iferr!=nil{returnfmt.Errorf("pubsub.NewClient: %w",err)}deferclient.Close()req:=&iampb.GetIamPolicyRequest{Resource:fmt.Sprintf("projects/%s/topics/%s",projectID,topicID),}policy,err:=client.TopicAdminClient.GetIamPolicy(ctx,req)iferr!=nil{returnfmt.Errorf("Policy: %w",err)}for_,b:=rangepolicy.Bindings{for_,m:=rangeb.Members{fmt.Fprintf(w,"role: %s, member: %s\n",b.Role,m)}}returnnil}

Java

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

importcom.google.cloud.pubsub.v1.TopicAdminClient;importcom.google.iam.v1.GetIamPolicyRequest;importcom.google.iam.v1.Policy;importcom.google.pubsub.v1.TopicName;importjava.io.IOException;publicclassGetTopicPolicyExample{publicstaticvoidmain(String...args)throwsException{// TODO(developer): Replace these variables before running the sample.StringprojectId="your-project-id";StringtopicId="your-topic-id";getTopicPolicyExample(projectId,topicId);}publicstaticvoidgetTopicPolicyExample(StringprojectId,StringtopicId)throwsIOException{try(TopicAdminClienttopicAdminClient=TopicAdminClient.create()){TopicNametopicName=TopicName.of(projectId,topicId);GetIamPolicyRequestgetIamPolicyRequest=GetIamPolicyRequest.newBuilder().setResource(topicName.toString()).build();Policypolicy=topicAdminClient.getIamPolicy(getIamPolicyRequest);System.out.println("Topic policy: "+policy);}}}

Node.js

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

/** * TODO(developer): Uncomment this variable before running the sample. */// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';// Imports the Google Cloud client libraryconst{PubSub}=require('@google-cloud/pubsub');// Creates a client; cache this for further useconstpubSubClient=newPubSub();asyncfunctiongetTopicPolicy(topicNameOrId){// Retrieves the IAM policy for the topicconst[policy]=awaitpubSubClient.topic(topicNameOrId).iam.getPolicy();console.log('Policy for topic: %j.',policy.bindings);}

PHP

Before trying this sample, follow the PHP setup instructions inQuickstart: Using Client Libraries. For more information, see thePub/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 inQuickstart: Using Client Libraries. For more information, see thePub/Sub Python API reference documentation.

fromgoogle.cloudimportpubsub_v1# TODO(developer): Choose an existing topic.# project_id = "your-project-id"# topic_id = "your-topic-id"client=pubsub_v1.PublisherClient()topic_path=client.topic_path(project_id,topic_id)policy=client.get_iam_policy(request={"resource":topic_path})print("Policy for topic{}:".format(topic_path))forbindinginpolicy.bindings:print("Role:{}, Members:{}".format(binding.role,binding.members))

Ruby

The following sample uses Ruby Pub/Sub client library v3. If you are still using the v2 library, see the migration guide to v3.To see a list of Ruby v2 code samples, seethe deprecated code samples.

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

# topic_id = "your-topic-id"pubsub=Google::Cloud::PubSub.newpolicy=pubsub.iam.get_iam_policyresource:pubsub.topic_path(topic_id)puts"Topic policy:"putspolicy.bindings.first.role

Set a policy

ThesetIamPolicy() method lets youattach a policyto a resource. ThesetIamPolicy() method takes aSetIamPolicyRequest, whichcontains the policy to be set and the resource to which the policy is attached.It returns the resulting policy.

Here is some sample code toset a policy for a subscription:

C#

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

usingGoogle.Cloud.Iam.V1;usingGoogle.Cloud.PubSub.V1;publicclassSetSubscriptionIamPolicySample{publicPolicySetSubscriptionIamPolicy(stringprojectId,stringsubscriptionId,stringrole,stringmember){PublisherServiceApiClientpublisher=PublisherServiceApiClient.Create();stringroleToBeAddedToPolicy=$"roles/{role}";Policypolicy=newPolicy{Bindings={newBinding{Role=roleToBeAddedToPolicy,Members={member}}}};SetIamPolicyRequestrequest=newSetIamPolicyRequest{ResourceAsResourceName=SubscriptionName.FromProjectSubscription(projectId,subscriptionId),Policy=policy};Policyresponse=publisher.IAMPolicyClient.SetIamPolicy(request);returnresponse;}}

gcloud

1. Save the policy for the subscription.

gcloudpubsubsubscriptionsget-iam-policy\projects/${PROJECT}/subscriptions/${SUBSCRIPTION}\--formatjson>subscription_policy.json

2. Opensubscription_policy.json and update bindings by giving appropriate roles to appropriate principals. For more information about working withsubscription_policy.json files, see Policy in the IAM documentation.

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

gcloudpubsubsubscriptionsset-iam-policy\projects/${PROJECT}/subscriptions/${SUBSCRIPTION}\subscription_policy.json

Go

The following sample uses the major version of the Go Pub/Sub client library (v2). If you are still using the v1 library, seethe migration guide to v2.To see a list of v1 code samples, seethe deprecated code samples.

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

import("context""fmt""io""cloud.google.com/go/iam/apiv1/iampb""cloud.google.com/go/pubsub/v2")funcaddUsersToSubscription(wio.Writer,projectID,subIDstring)error{// projectID := "my-project-id"// subID := "my-sub"ctx:=context.Background()client,err:=pubsub.NewClient(ctx,projectID)iferr!=nil{returnfmt.Errorf("pubsub.NewClient: %w",err)}deferclient.Close()subName:=fmt.Sprintf("projects/%s/subscriptions/%s",projectID,subID)req:=&iampb.GetIamPolicyRequest{Resource:subName,}policy,err:=client.SubscriptionAdminClient.GetIamPolicy(ctx,req)iferr!=nil{returnfmt.Errorf("error calling GetIamPolicy: %w",err)}b:=&iampb.Binding{Role:"roles/editor",// Other valid prefixes are "serviceAccount:", "user:"// See the documentation for more values.Members:[]string{"group:cloud-logs@google.com"},}policy.Bindings=append(policy.Bindings,b)setRequest:=&iampb.SetIamPolicyRequest{Resource:subName,Policy:policy,}_,err=client.SubscriptionAdminClient.SetIamPolicy(ctx,setRequest)iferr!=nil{returnfmt.Errorf("error calling SetIamPolicy: %w",err)}fmt.Fprintln(w,"Added roles to subscription.")returnnil}

Java

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

importcom.google.cloud.pubsub.v1.SubscriptionAdminClient;importcom.google.iam.v1.Binding;importcom.google.iam.v1.GetIamPolicyRequest;importcom.google.iam.v1.Policy;importcom.google.iam.v1.SetIamPolicyRequest;importcom.google.pubsub.v1.ProjectSubscriptionName;importjava.io.IOException;publicclassSetSubscriptionPolicyExample{publicstaticvoidmain(String...args)throwsException{// TODO(developer): Replace these variables before running the sample.StringprojectId="your-project-id";StringsubscriptionId="your-subscription-id";setSubscriptionPolicyExample(projectId,subscriptionId);}publicstaticvoidsetSubscriptionPolicyExample(StringprojectId,StringsubscriptionId)throwsIOException{try(SubscriptionAdminClientsubscriptionAdminClient=SubscriptionAdminClient.create()){ProjectSubscriptionNamesubscriptionName=ProjectSubscriptionName.of(projectId,subscriptionId);GetIamPolicyRequestgetIamPolicyRequest=GetIamPolicyRequest.newBuilder().setResource(subscriptionName.toString()).build();PolicyoldPolicy=subscriptionAdminClient.getIamPolicy(getIamPolicyRequest);// Create new role -> members bindingBindingbinding=Binding.newBuilder().setRole("roles/pubsub.editor").addMembers("domain:google.com").build();// Add new binding to updated policyPolicyupdatedPolicy=Policy.newBuilder(oldPolicy).addBindings(binding).build();SetIamPolicyRequestsetIamPolicyRequest=SetIamPolicyRequest.newBuilder().setResource(subscriptionName.toString()).setPolicy(updatedPolicy).build();PolicynewPolicy=subscriptionAdminClient.setIamPolicy(setIamPolicyRequest);System.out.println("New subscription policy: "+newPolicy);}}}

Node.js

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

/** * TODO(developer): Uncomment this variable before running the sample. */// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';// Imports the Google Cloud client libraryconst{PubSub}=require('@google-cloud/pubsub');// Creates a client; cache this for further useconstpubSubClient=newPubSub();asyncfunctionsetSubscriptionPolicy(subscriptionNameOrId){// The new IAM policyconstnewPolicy={bindings:[{// Add a group as editorsrole:'roles/pubsub.editor',members:['group:cloud-logs@google.com'],},{// Add all users as viewersrole:'roles/pubsub.viewer',members:['allUsers'],},],};// Updates the IAM policy for the subscriptionconst[updatedPolicy]=awaitpubSubClient.subscription(subscriptionNameOrId).iam.setPolicy(newPolicy);console.log('Updated policy for subscription: %j',updatedPolicy.bindings);}

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 inQuickstart: Using Client Libraries. For more information, see thePub/Sub Python API reference documentation.

fromgoogle.cloudimportpubsub_v1# TODO(developer): Choose an existing subscription.# project_id = "your-project-id"# subscription_id = "your-subscription-id"client=pubsub_v1.SubscriberClient()subscription_path=client.subscription_path(project_id,subscription_id)policy=client.get_iam_policy(request={"resource":subscription_path})# Add all users as viewers.policy.bindings.add(role="roles/pubsub.viewer",members=["domain:google.com"])# Add a group as an editor.policy.bindings.add(role="roles/editor",members=["group:cloud-logs@google.com"])# Set the policypolicy=client.set_iam_policy(request={"resource":subscription_path,"policy":policy})print("IAM policy for subscription{} set:{}".format(subscription_id,policy))client.close()

Ruby

The following sample uses Ruby Pub/Sub client library v3. If you are still using the v2 library, see the migration guide to v3.To see a list of Ruby v2 code samples, seethe deprecated code samples.

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

# subscription_id       = "your-subscription-id"# role                  = "roles/pubsub.subscriber"# service_account_email =# "serviceAccount:account_name@project_name.iam.gserviceaccount.com"pubsub=Google::Cloud::PubSub.newbindings=Google::Iam::V1::Binding.new\role:role,members:[service_account_email]pubsub.iam.set_iam_policyresource:pubsub.subscription_path(subscription_id),policy:{bindings:[bindings]}

Here is some sample code toset a policy for a topic:

C#

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

usingGoogle.Cloud.Iam.V1;usingGoogle.Cloud.PubSub.V1;publicclassSetTopicIamPolicySample{publicPolicySetTopicIamPolicy(stringprojectId,stringtopicId,stringrole,stringmember){PublisherServiceApiClientpublisher=PublisherServiceApiClient.Create();stringroleToBeAddedToPolicy=$"roles/{role}";Policypolicy=newPolicy{Bindings={newBinding{Role=roleToBeAddedToPolicy,Members={member}}}};SetIamPolicyRequestrequest=newSetIamPolicyRequest{ResourceAsResourceName=TopicName.FromProjectTopic(projectId,topicId),Policy=policy};Policyresponse=publisher.IAMPolicyClient.SetIamPolicy(request);returnresponse;}}

gcloud

1. Save the policy for the topic.

gcloudpubsubtopicsget-iam-policy\projects/${PROJECT}/topics/${TOPIC}\--formatjson>topic_policy.json

2. Opentopic_policy.json and update bindings by giving appropriate roles to appropriate principals. For more information about working withsubscription_policy.json files, see Policy in the IAM documentation.

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

3. Apply the new topic policy.

gcloudpubsubtopicsset-iam-policy\projects/${PROJECT}/topics/${TOPIC}\topic_policy.json

Go

The following sample uses the major version of the Go Pub/Sub client library (v2). If you are still using the v1 library, seethe migration guide to v2.To see a list of v1 code samples, seethe deprecated code samples.

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

import("context""fmt""io""cloud.google.com/go/iam/apiv1/iampb""cloud.google.com/go/pubsub/v2")funcaddUsersToTopic(wio.Writer,projectID,topicIDstring)error{// projectID := "my-project-id"// topicID := "my-topic"ctx:=context.Background()client,err:=pubsub.NewClient(ctx,projectID)iferr!=nil{returnfmt.Errorf("pubsub.NewClient: %w",err)}deferclient.Close()topicName:=fmt.Sprintf("projects/%s/topics/%s",projectID,topicID)req:=&iampb.GetIamPolicyRequest{Resource:topicName,}policy,err:=client.TopicAdminClient.GetIamPolicy(ctx,req)iferr!=nil{returnfmt.Errorf("error calling GetIamPolicy: %w",err)}b:=&iampb.Binding{Role:"roles/editor",// Other valid prefixes are "serviceAccount:", "user:"// See the documentation for more values.Members:[]string{"group:cloud-logs@google.com"},}policy.Bindings=append(policy.Bindings,b)setRequest:=&iampb.SetIamPolicyRequest{Resource:topicName,Policy:policy,}_,err=client.TopicAdminClient.SetIamPolicy(ctx,setRequest)iferr!=nil{returnfmt.Errorf("error calling SetIamPolicy: %w",err)}fmt.Fprintln(w,"Added roles to topic.")returnnil}

Java

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

importcom.google.cloud.pubsub.v1.TopicAdminClient;importcom.google.iam.v1.Binding;importcom.google.iam.v1.GetIamPolicyRequest;importcom.google.iam.v1.Policy;importcom.google.iam.v1.SetIamPolicyRequest;importcom.google.pubsub.v1.TopicName;importjava.io.IOException;publicclassSetTopicPolicyExample{publicstaticvoidmain(String...args)throwsException{// TODO(developer): Replace these variables before running the sample.StringprojectId="your-project-id";StringtopicId="your-topic-id";setTopicPolicyExample(projectId,topicId);}publicstaticvoidsetTopicPolicyExample(StringprojectId,StringtopicId)throwsIOException{try(TopicAdminClienttopicAdminClient=TopicAdminClient.create()){TopicNametopicName=TopicName.of(projectId,topicId);GetIamPolicyRequestgetIamPolicyRequest=GetIamPolicyRequest.newBuilder().setResource(topicName.toString()).build();PolicyoldPolicy=topicAdminClient.getIamPolicy(getIamPolicyRequest);// Create new role -> members bindingBindingbinding=Binding.newBuilder().setRole("roles/pubsub.editor").addMembers("domain:google.com").build();// Add new binding to updated policyPolicyupdatedPolicy=Policy.newBuilder(oldPolicy).addBindings(binding).build();SetIamPolicyRequestsetIamPolicyRequest=SetIamPolicyRequest.newBuilder().setResource(topicName.toString()).setPolicy(updatedPolicy).build();PolicynewPolicy=topicAdminClient.setIamPolicy(setIamPolicyRequest);System.out.println("New topic policy: "+newPolicy);}}}

Node.js

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

/** * TODO(developer): Uncomment this variable before running the sample. */// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';// Imports the Google Cloud client libraryconst{PubSub}=require('@google-cloud/pubsub');// Creates a client; cache this for further useconstpubSubClient=newPubSub();asyncfunctionsetTopicPolicy(topicNameOrId){// The new IAM policyconstnewPolicy={bindings:[{// Add a group as editorsrole:'roles/pubsub.editor',members:['group:cloud-logs@google.com'],},{// Add all users as viewersrole:'roles/pubsub.viewer',members:['allUsers'],},],};// Updates the IAM policy for the topicconst[updatedPolicy]=awaitpubSubClient.topic(topicNameOrId).iam.setPolicy(newPolicy);console.log('Updated policy for topic: %j',updatedPolicy.bindings);}

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 inQuickstart: Using Client Libraries. For more information, see thePub/Sub Python API reference documentation.

fromgoogle.cloudimportpubsub_v1# TODO(developer): Choose an existing topic.# project_id = "your-project-id"# topic_id = "your-topic-id"client=pubsub_v1.PublisherClient()topic_path=client.topic_path(project_id,topic_id)policy=client.get_iam_policy(request={"resource":topic_path})# Add all users as viewers.policy.bindings.add(role="roles/pubsub.viewer",members=["domain:google.com"])# Add a group as a publisher.policy.bindings.add(role="roles/pubsub.publisher",members=["group:cloud-logs@google.com"])# Set the policypolicy=client.set_iam_policy(request={"resource":topic_path,"policy":policy})print("IAM policy for topic{} set:{}".format(topic_id,policy))

Ruby

The following sample uses Ruby Pub/Sub client library v3. If you are still using the v2 library, see the migration guide to v3.To see a list of Ruby v2 code samples, seethe deprecated code samples.

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

# topic_id              = "your-topic-id"# role                  = "roles/pubsub.publisher"# service_account_email =# "serviceAccount:account_name@project_name.iam.gserviceaccount.com"pubsub=Google::Cloud::PubSub.newbindings=Google::Iam::V1::Binding.new\role:role,members:[service_account_email]pubsub.iam.set_iam_policyresource:pubsub.topic_path(topic_id),policy:{bindings:[bindings]}

Test permissions

You can use thetestIamPermissions() method to check which of the givenpermissions can be added or removed for the given resource. It takesas parameters a resource name and a set of permissions, and returns the subsetof permissions.

Note: ThetestIamPermissions is designed to test permission-awareUIs and command-line tools, not authorization. This operationmightfail open without warning.

Here is some sample code totest permissions for a subscription:

C#

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

usingGoogle.Cloud.Iam.V1;usingGoogle.Cloud.PubSub.V1;publicclassTestSubscriptionIamPermissionsSample{publicTestIamPermissionsResponseTestSubscriptionIamPermissionsResponse(stringprojectId,stringsubscriptionId){TestIamPermissionsRequestrequest=newTestIamPermissionsRequest{ResourceAsResourceName=SubscriptionName.FromProjectSubscription(projectId,subscriptionId),Permissions={"pubsub.subscriptions.get","pubsub.subscriptions.update"}};PublisherServiceApiClientpublisher=PublisherServiceApiClient.Create();TestIamPermissionsResponseresponse=publisher.IAMPolicyClient.TestIamPermissions(request);returnresponse;}}

gcloud

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

The following sample uses the major version of the Go Pub/Sub client library (v2). If you are still using the v1 library, seethe migration guide to v2.To see a list of v1 code samples, seethe deprecated code samples.

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

import("context""fmt""io""cloud.google.com/go/iam/apiv1/iampb""cloud.google.com/go/pubsub/v2")functestPermissions(wio.Writer,projectID,subIDstring)([]string,error){// projectID := "my-project-id"// subID := "my-sub"ctx:=context.Background()client,err:=pubsub.NewClient(ctx,projectID)iferr!=nil{returnnil,fmt.Errorf("pubsub.NewClient: %w",err)}req:=&iampb.TestIamPermissionsRequest{Resource:fmt.Sprintf("projects/%s/subscriptions/%s",projectID,subID),Permissions:[]string{"pubsub.subscriptions.consume","pubsub.subscriptions.update",},}resp,err:=client.SubscriptionAdminClient.TestIamPermissions(ctx,req)iferr!=nil{returnnil,fmt.Errorf("error calling TestIamPermissions: %w",err)}for_,perm:=rangeresp.Permissions{fmt.Fprintf(w,"Allowed: %v\n",perm)}returnresp.Permissions,nil}

Java

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

importcom.google.cloud.pubsub.v1.SubscriptionAdminClient;importcom.google.iam.v1.TestIamPermissionsRequest;importcom.google.iam.v1.TestIamPermissionsResponse;importcom.google.pubsub.v1.ProjectSubscriptionName;importjava.io.IOException;importjava.util.LinkedList;importjava.util.List;publicclassTestSubscriptionPermissionsExample{publicstaticvoidmain(String...args)throwsException{// TODO(developer): Replace these variables before running the sample.StringprojectId="your-project-id";StringsubscriptionId="your-subscription-id";testSubscriptionPermissionsExample(projectId,subscriptionId);}publicstaticvoidtestSubscriptionPermissionsExample(StringprojectId,StringsubscriptionId)throwsIOException{try(SubscriptionAdminClientsubscriptionAdminClient=SubscriptionAdminClient.create()){ProjectSubscriptionNamesubscriptionName=ProjectSubscriptionName.of(projectId,subscriptionId);List<String>permissions=newLinkedList<>();permissions.add("pubsub.subscriptions.consume");permissions.add("pubsub.subscriptions.update");TestIamPermissionsRequesttestIamPermissionsRequest=TestIamPermissionsRequest.newBuilder().setResource(subscriptionName.toString()).addAllPermissions(permissions).build();TestIamPermissionsResponsetestedPermissionsResponse=subscriptionAdminClient.testIamPermissions(testIamPermissionsRequest);System.out.println("Tested:\n"+testedPermissionsResponse);}}}

Node.js

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

/** * TODO(developer): Uncomment this variable before running the sample. */// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';// Imports the Google Cloud client libraryconst{PubSub}=require('@google-cloud/pubsub');// Creates a client; cache this for further useconstpubSubClient=newPubSub();asyncfunctiontestSubscriptionPermissions(subscriptionNameOrId){constpermissionsToTest=['pubsub.subscriptions.consume','pubsub.subscriptions.update',];// Tests the IAM policy for the specified subscriptionconst[permissions]=awaitpubSubClient.subscription(subscriptionNameOrId).iam.testPermissions(permissionsToTest);console.log('Tested permissions for subscription: %j',permissions);}

PHP

Before trying this sample, follow the PHP setup instructions inQuickstart: Using Client Libraries. For more information, see thePub/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 inQuickstart: Using Client Libraries. For more information, see thePub/Sub Python API reference documentation.

fromgoogle.cloudimportpubsub_v1# TODO(developer): Choose an existing subscription.# project_id = "your-project-id"# subscription_id = "your-subscription-id"client=pubsub_v1.SubscriberClient()subscription_path=client.subscription_path(project_id,subscription_id)permissions_to_check=["pubsub.subscriptions.consume","pubsub.subscriptions.update",]allowed_permissions=client.test_iam_permissions(request={"resource":subscription_path,"permissions":permissions_to_check})print("Allowed permissions for subscription{}:{}".format(subscription_path,allowed_permissions))client.close()

Ruby

The following sample uses Ruby Pub/Sub client library v3. If you are still using the v2 library, see the migration guide to v3.To see a list of Ruby v2 code samples, seethe deprecated code samples.

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

# subscription_id = "your-subscription-id"pubsub=Google::Cloud::PubSub.newsubscription_admin=pubsub.subscription_adminpermissions=["pubsub.subscriptions.consume","pubsub.subscriptions.update"]response=pubsub.iam.test_iam_permissions\resource:pubsub.subscription_path(subscription_id),permissions:permissionsputs"Permission to consume"\ifresponse.permissions.include?"pubsub.subscriptions.consume"puts"Permission to update"\ifresponse.permissions.include?"pubsub.subscriptions.update"

Here is some sample code totest permissions for a topic:

C#

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

usingGoogle.Cloud.Iam.V1;usingGoogle.Cloud.PubSub.V1;publicclassTestTopicIamPermissionsSample{publicTestIamPermissionsResponseTestTopicIamPermissions(stringprojectId,stringtopicId){TestIamPermissionsRequestrequest=newTestIamPermissionsRequest{ResourceAsResourceName=TopicName.FromProjectTopic(projectId,topicId),Permissions={"pubsub.topics.get","pubsub.topics.update"}};PublisherServiceApiClientpublisher=PublisherServiceApiClient.Create();TestIamPermissionsResponseresponse=publisher.IAMPolicyClient.TestIamPermissions(request);returnresponse;}}

gcloud

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.detachSubscription",     "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

The following sample uses the major version of the Go Pub/Sub client library (v2). If you are still using the v1 library, seethe migration guide to v2.To see a list of v1 code samples, seethe deprecated code samples.

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

import("context""fmt""io""cloud.google.com/go/iam/apiv1/iampb""cloud.google.com/go/pubsub/v2")functestPermissions(wio.Writer,projectID,topicIDstring)([]string,error){// projectID := "my-project-id"// topicID := "my-topic"ctx:=context.Background()client,err:=pubsub.NewClient(ctx,projectID)iferr!=nil{returnnil,fmt.Errorf("pubsub.NewClient: %w",err)}req:=&iampb.TestIamPermissionsRequest{Resource:fmt.Sprintf("projects/%s/topics/%s",projectID,topicID),Permissions:[]string{"pubsub.topics.publish","pubsub.topics.update",},}resp,err:=client.TopicAdminClient.TestIamPermissions(ctx,req)iferr!=nil{returnnil,fmt.Errorf("error calling TestIamPermissions: %w",err)}for_,perm:=rangeresp.Permissions{fmt.Fprintf(w,"Allowed: %v\n",perm)}returnresp.Permissions,nil}

Java

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

importcom.google.cloud.pubsub.v1.TopicAdminClient;importcom.google.iam.v1.TestIamPermissionsRequest;importcom.google.iam.v1.TestIamPermissionsResponse;importcom.google.pubsub.v1.ProjectTopicName;importjava.io.IOException;importjava.util.LinkedList;importjava.util.List;publicclassTestTopicPermissionsExample{publicstaticvoidmain(String...args)throwsException{// TODO(developer): Replace these variables before running the sample.StringprojectId="your-project-id";StringtopicId="your-topic-id";testTopicPermissionsExample(projectId,topicId);}publicstaticvoidtestTopicPermissionsExample(StringprojectId,StringtopicId)throwsIOException{try(TopicAdminClienttopicAdminClient=TopicAdminClient.create()){ProjectTopicNametopicName=ProjectTopicName.of(projectId,topicId);List<String>permissions=newLinkedList<>();permissions.add("pubsub.topics.attachSubscription");permissions.add("pubsub.topics.publish");permissions.add("pubsub.topics.update");TestIamPermissionsRequesttestIamPermissionsRequest=TestIamPermissionsRequest.newBuilder().setResource(topicName.toString()).addAllPermissions(permissions).build();TestIamPermissionsResponsetestedPermissionsResponse=topicAdminClient.testIamPermissions(testIamPermissionsRequest);System.out.println("Tested:\n"+testedPermissionsResponse);}}}

Node.js

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

/** * TODO(developer): Uncomment this variable before running the sample. */// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';// Imports the Google Cloud client libraryconst{PubSub}=require('@google-cloud/pubsub');// Creates a client; cache this for further useconstpubSubClient=newPubSub();asyncfunctiontestTopicPermissions(topicNameOrId){constpermissionsToTest=['pubsub.topics.attachSubscription','pubsub.topics.publish','pubsub.topics.update',];// Tests the IAM policy for the specified topicconst[permissions]=awaitpubSubClient.topic(topicNameOrId).iam.testPermissions(permissionsToTest);console.log('Tested permissions for topic: %j',permissions);}

PHP

Before trying this sample, follow the PHP setup instructions inQuickstart: Using Client Libraries. For more information, see thePub/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 inQuickstart: Using Client Libraries. For more information, see thePub/Sub Python API reference documentation.

fromgoogle.cloudimportpubsub_v1# TODO(developer): Choose an existing topic.# project_id = "your-project-id"# topic_id = "your-topic-id"client=pubsub_v1.PublisherClient()topic_path=client.topic_path(project_id,topic_id)permissions_to_check=["pubsub.topics.publish","pubsub.topics.update"]allowed_permissions=client.test_iam_permissions(request={"resource":topic_path,"permissions":permissions_to_check})print("Allowed permissions for topic{}:{}".format(topic_path,allowed_permissions))

Ruby

The following sample uses Ruby Pub/Sub client library v3. If you are still using the v2 library, see the migration guide to v3.To see a list of Ruby v2 code samples, seethe deprecated code samples.

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

# topic_id = "your-topic-id"pubsub=Google::Cloud::PubSub.newtopic_admin=pubsub.topic_adminpermissions=["pubsub.topics.attachSubscription","pubsub.topics.publish","pubsub.topics.update"]response=pubsub.iam.test_iam_permissions\resource:pubsub.topic_path(topic_id),permissions:permissionsputs"Permission to attach subscription"\ifpermissions.include?"pubsub.topics.attachSubscription"puts"Permission to publish"\ifresponse.permissions.include?"pubsub.topics.publish"puts"Permission to update"\ifresponse.permissions.include?"pubsub.topics.update"

Cross-project communication

Pub/Sub IAM is useful for fine-tuning access incross-project communication.

Suppose a service account in Cloud Project A wants to publish messages to atopic in Cloud Project B. First, enable the Pub/Sub APIin Project A.

Second, grant the service accountEdit permission inCloud Project B. However, this approach is often too coarse. You can use theIAM API to achieve a more fine-grained level of access.

Cross-project communication

For example, this snippet uses thesetIamPolicy() method inproject-b and a preparedtopic_policy.json file to grant the service accountfoobar@project-a.iam.gserviceaccount.com ofproject-a the publisher role on the topicprojects/project-b/topics/topic-b:

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

Partial availability behavior

Authorization checks depend on the IAM subsystem. In order tooffer consistently low response latency for data operations (publishing andmessage consumption), the system may fall back on cached IAMpolicies. For information about when your changes will take effect, see theIAM documentation.

What's Next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-16 UTC.