Access control with Identity and Access Management Stay organized with collections Save and categorize content based on your preferences.
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:
Basic roles: Basic roles are highly permissive roles that existed priorto the introduction of IAM. For more information aboutbasic roles, seeBasic roles.
Predefined roles: Predefined roles give granular access to specificGoogle Cloud resources. For more information aboutpredefined roles, seePredefined roles.The Pub/Sub predefined roles are included in alater part of this section.
Custom roles: Custom roles help you enforce the principle of leastprivilege. For more information about custom roles, seeCustom 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.
| Method | Description | Required permission |
|---|---|---|
projects.topics.create | Creates the given topic with the given name. | pubsub.topics.create on the containing Cloud project |
projects.topics.delete | Deletes the topic with the given name. | pubsub.topics.delete on the requested topic |
projects.topics.get | Gets the configuration of a topic. | pubsub.topics.get on the requested topic |
projects.topics.getIamPolicy | Gets the IAM access control policy for a topic. | pubsub.topics.getIamPolicy on the requested topic |
projects.topics.list | Lists all topics. | pubsub.topics.list on the requested Cloud project |
projects.topics.patch | Updates an existing topic. | pubsub.topics.update on the requested topic |
projects.topics.publish | Adds one or more messages to the topic. | pubsub.topics.publish on the requested topic |
projects.topics.setIamPolicy | Sets the IAM access control policy for a topic. | pubsub.topics.setIamPolicy on the requested topic |
projects.topics.testIamPermissions | Returns 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.
| Method | Description | Required permission |
|---|---|---|
projects.subscriptions.acknowledge | Acknowledges the messages associated with the ack_ids in the AcknowledgeRequest. | pubsub.subscriptions.consume on the requested subscription |
projects.subscriptions.create | Creates 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.delete | Deletes an existing subscription. | pubsub.subscriptions.delete on the requested subscription |
projects.subscriptions.detach | Detaches a subscription from this topic. | pubsub.subscriptions.detach on the subscription |
projects.subscriptions.get | Gets the configuration details of a subscription. | pubsub.subscriptions.get on the requested subscription |
projects.subscriptions.getIamPolicy | Gets the IAM access control policy for a subscription. | pubsub.subscriptions.getIamPolicy on the requested subscription |
projects.subscriptions.list | Lists matching subscriptions. | pubsub.subscriptions.list on the requested Cloud project |
projects.subscriptions.modifyAckDeadline | Modifies the ack deadline for a specific message. | pubsub.subscriptions.consume on the requested subscription |
projects.subscriptions.modifyPushConfig | Modifies the pushConfig for a specified subscription. | pubsub.subscriptions.update on the requested subscription |
projects.subscriptions.patch | Updates an existing subscription. | pubsub.subscriptions.update on the requested subscription |
projects.subscriptions.pull | Pulls messages from the server. | pubsub.subscriptions.consume on the requested subscription |
projects.subscriptions.seek | Seeks 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.setIamPolicy | Sets the IAM access control policy for a subscription. | pubsub.subscriptions.setIamPolicy on the requested subscription |
projects.subscriptions.testIamPermissions | Returns 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.
| Method | Description | Required permission |
|---|---|---|
projects.schemas.commit | Commits a new schema revision. | pubsub.schemas.commit on the requested schema |
projects.schemas.create | Creates a schema. | pubsub.schemas.create on the containing Cloud project |
projects.schemas.delete | Deletes a schema. | pubsub.schemas.delete on the requested schema |
projects.schemas.deleteRevision | Deletes a specific schema revision. | pubsub.schemas.delete on the requested schema |
projects.schemas.get | Gets a schema. | pubsub.schemas.get on the requested schema |
projects.schemas.getIamPolicy | Gets the IAM access control policy for a schema. | pubsub.schemas.getIamPolicy on the requested schema |
projects.schemas.list | Lists schemas in a project. | pubsub.schemas.list on the requested Cloud project |
projects.schemas.listRevisions | Lists all schema revisions for the named schema. | pubsub.schemas.listRevisions on the requested schema |
projects.schemas.rollback | Creates a new schema revision from a previous revision. | pubsub.schemas.rollback on the requested schema |
projects.schemas.validate | Validates a schema definition. | pubsub.schemas.validate on the containing Cloud project |
projects.schemas.validateMessage | Validates 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 method | Description | Required permission |
|---|---|---|
projects.snapshots.create | Creates a snapshot from the requested subscription. | pubsub.snapshots.create on the containing Cloud project andpubsub.subscriptions.consume permission on the source subscription. |
projects.snapshots.delete | Removes an existing snapshot. | pubsub.snapshots.delete on the requested snapshot |
projects.snapshots.getIamPolicy | Gets the IAM access control policy for a snapshot. | pubsub.snapshots.getIamPolicy on the requested snapshot |
projects.snapshots.list | Lists the existing snapshots. | pubsub.snapshots.list on the requested Cloud project |
projects.snapshots.patch | Updates an existing snapshot. | pubsub.snapshots.update on the requested snapshot |
projects.snapshots.setIamPolicy | Sets the IAM access control policy for a snapshot. | pubsub.snapshots.setIamPolicy on the requested snapshot |
projects.snapshots.testIamPermissions | Returns 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:
| Role | Permissions |
|---|---|
Pub/Sub Admin( Provides full access to topics and subscriptions. Lowest-level resources where you can grant this role:
|
|
Pub/Sub Editor( Provides access to modify topics and subscriptions, and access to publishand consume messages. Lowest-level resources where you can grant this role:
|
|
Pub/Sub Publisher( Provides access to publish messages to a topic. Lowest-level resources where you can grant this role:
|
|
Cloud Pub/Sub Service Agent( Grants Cloud Pub/Sub Service Account access to manage resources. Warning: Do not grant service agent roles to any principals exceptservice agents. |
|
Pub/Sub Subscriber( Provides access to consume messages from a subscription and to attachsubscriptions to a topic. Lowest-level resources where you can grant this role:
|
|
Pub/Sub Viewer( Provides access to view topics and subscriptions. Lowest-level resources where you can grant this role:
|
|
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:
In the Google Cloud console, go to the IAM page.
Select your project.
ClickAdd.
Type in one or more principal names.
In theSelect a role list, select the role you want to grant.
ClickSave.
Verify that the principal is listed with the role that you granted.
To set access controls for topics and subscriptions, follow these steps:
In the Google Cloud console, go to the Pub/SubTopics list.
If needed, select your Pub/Sub-enabled project.
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.
If the info panel is hidden, clickShow info panel.
In thePermissions tab, clickAdd principal.
Type in one or more principal names.
In theSelect a role list, select the role you want to grant.
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.roleC#
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.
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.
testIamPermissions 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 jsonOutput:
[ { "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 jsonOutput
[ { "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.
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
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
- If you are having issues accessing or authenticating Pub/Sub resources,seeGeneral troubleshooting.
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.