This document describes the access control options available to you in Pub/Sub.
Overview
Pub/Sub uses Identity and Access Management (IAM) for access control.
In Pub/Sub, access control can be configured at the project level and at the individual resource level. For example:
- Grant access on a per-topic or per-subscription basis, rather than for the whole Cloud project.
- Grant access with limited capabilities, such as to only publish messages to a topic, or to only consume messages from a subscription, but not to delete the topic or subscription.
- Grant access to all Pub/Sub resources within a project to a group of developers.
For a detailed description of IAM and its features, see the IAM documentation. In particular, see Granting, changing, and revoking access to resources.
Every Pub/Sub method requires the caller to have the necessary permissions. For a list of the permissions and roles that Pub/Sub IAM supports, see the Roles section, below.
Permissions and roles
This section summarizes the permissions and roles that Pub/Sub IAM supports.
Required permissions
The following table lists the permissions that the caller must have to call each method:
Method | Required Permission(s) |
---|---|
projects.snapshots.create |
pubsub.snapshots.create on the containing Cloud project and pubsub.subscriptions.consume permission on the source subscription. |
projects.snapshots.delete |
pubsub.snapshots.delete on the requested snapshot. |
projects.snapshots.getIamPolicy |
pubsub.snapshots.getIamPolicy on the requested snapshot. |
projects.snapshots.list |
pubsub.snapshots.list on the requested Cloud project. |
projects.snapshots.patch |
pubsub.snapshots.update on the requested snapshot. |
projects.snapshots.setIamPolicy |
pubsub.snapshots.setIamPolicy on the requested snapshot. |
projects.snapshots.testIamPermissions |
None. |
projects.subscriptions.acknowledge |
pubsub.subscriptions.consume on the requested subscription. |
projects.subscriptions.create |
pubsub.subscriptions.create on the containing Cloud project
and pubsub.topics.attachSubscription on the requested topic.
Note that for creating a subscription in Project A to a Topic T in Project
B, the appropriate permissions must be granted on both Project A and on
Topic T. In this case, user identity info can be captured in Project B's
audit logs. |
projects.subscriptions.delete |
pubsub.subscriptions.delete on the requested subscription. |
projects.subscriptions.get |
pubsub.subscriptions.get on the requested subscription. |
projects.subscriptions.getIamPolicy |
pubsub.subscriptions.getIamPolicy on the requested subscription. |
projects.subscriptions.list |
pubsub.subscriptions.list on the requested Cloud project. |
projects.subscriptions.modifyAckDeadline |
pubsub.subscriptions.consume on the requested subscription. |
projects.subscriptions.modifyPushConfig |
pubsub.subscriptions.update on the requested subscription. |
projects.subscriptions.patch |
pubsub.subscriptions.update on the requested subscription. |
projects.subscriptions.pull |
pubsub.subscriptions.consume on the requested subscription. |
projects.subscriptions.seek |
pubsub.subscriptions.consume on the requested subscription and pubsub.snapshots.seek on the requested snapshot, if any. |
projects.subscriptions.setIamPolicy |
pubsub.subscriptions.setIamPolicy on the requested subscription. |
projects.subscriptions.testIamPermissions |
None. |
projects.topics.create |
pubsub.topics.create on the containing Cloud project. |
projects.topics.delete |
pubsub.topics.delete on the requested topic. |
projects.topics.detachSubscription |
pubsub.topics.detachSubscription on the requested topic. |
projects.topics.get |
pubsub.topics.get on the requested topic. |
projects.topics.getIamPolicy |
pubsub.topics.getIamPolicy on the requested topic. |
projects.topics.list |
pubsub.topics.list on the requested Cloud project. |
projects.topics.patch |
pubsub.topics.update on the requested topic. |
projects.topics.publish |
pubsub.topics.publish on the requested topic. |
projects.topics.setIamPolicy |
pubsub.topics.setIamPolicy on the requested topic. |
projects.topics.subscriptions.list |
pubsub.topics.get on the requested topic. |
projects.topics.testIamPermissions |
None. |
Roles
The following table lists the Pub/Sub IAM roles with a corresponding list of all the permissions each role includes. Note that every permission is applicable to a particular resource type.
These preconfigured roles address many typical use cases. However, you might need a role that includes a custom set of permissions. For instance, you may wish to create a role that allows a user to create a subscription in a project, without letting them delete or update existing topics or subscriptions in the project. In those cases, you may be able to create an IAM custom role that meets your needs.
Role | includes permission(s): | for resource type: |
---|---|---|
roles/pubsub.publisher |
pubsub.topics.publish |
Topic |
roles/pubsub.subscriber |
pubsub.snapshots.seek |
Snapshot |
pubsub.subscriptions.consume |
Subscription | |
pubsub.topics.attachSubscription |
Topic | |
roles/pubsub.viewer orroles/viewer |
pubsub.snapshots.get |
Snapshot |
pubsub.snapshots.list |
Project | |
pubsub.subscriptions.get |
Subscription | |
pubsub.subscriptions.list |
Project | |
pubsub.topics.get |
Topic | |
pubsub.topics.list |
Project | |
resourcemanager.projects.get |
Project | |
servicemanagement.projectSettings.get |
Project | |
serviceusage.quotas.get |
Project | |
serviceusage.services.get |
Project | |
serviceusage.services.list |
Project | |
roles/pubsub.editor orroles/editor |
All of the above, as well as: | |
pubsub.snapshots.create |
Project | |
pubsub.snapshots.delete |
Snapshot | |
pubsub.snapshots.update |
Snapshot | |
pubsub.subscriptions.create
|
Project | |
pubsub.subscriptions.delete |
Subscription | |
pubsub.subscriptions.update |
Subscription | |
pubsub.topics.create |
Project | |
pubsub.topics.delete |
Topic | |
pubsub.topics.detachSubscription |
Topic | |
pubsub.topics.update |
Topic | |
pubsub.topics.updateTag |
Topic | |
roles/pubsub.admin orroles/owner |
All of the above, as well as: | |
pubsub.snapshots.getIamPolicy |
Snapshot | |
pubsub.snapshots.setIamPolicy |
Snapshot | |
pubsub.subscriptions.getIamPolicy |
Subscription | |
pubsub.subscriptions.setIamPolicy |
Subscription | |
pubsub.topics.getIamPolicy |
Topic | |
pubsub.topics.setIamPolicy |
Topic |
The roles roles/owner, roles/editor, and roles/viewer include also permissions for other Google Cloud services.
Controlling access via the Google Cloud Console
You can use the GCP Console to manage access control for your topics and projects.
To set access controls at the project level:
- Open the IAM page in the Cloud Console.
- Select your project, and click Continue.
- Click Add Member.
- Enter the email address of a new member to whom you have not granted any IAM role previously.
- Select a role from the drop-down menu.
- Click Add.
- Verify that the member is listed under the role that you granted.
To set access controls for topics and subscriptions:
- Navigate to the Pub/Sub topics page in the console.
- Select your Pub/Sub-enabled project.
Select the topic or subscription.
You can set permissions for multiple topics at one time. To set permissions for a topic's subscription, expand the topic and click the subscription to open it in its own page.
Click Permissions. In the pane that appears:
- Type in a member name or names.
- Select a role from the drop-down menu.
- Click Add.
Controlling access via the IAM API
The Pub/Sub IAM API lets you set and get policies on individual topics and subscriptions in a project, and test a user's permissions for a given resource. As with the regular Pub/Sub methods, you can invoke the IAM API methods via the client libraries, or the API Explorer, or directly over HTTP.
Note that you cannot use the Pub/Sub IAM API to manage policies at the Google Cloud project level.
The following sections give examples for how to set and get a policy, and how to test what permissions a caller has for a given resource.
Getting a policy
The getIamPolicy()
method allows you to get an existing policy.
This method returns a JSON object containing the policy associated with the
resource.
Here is some sample code to get a policy for a subscription:
C#
Before trying this sample, follow the C# setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub C# API reference documentation.
gcloud
Get the subscription policy:
gcloud pubsub subscriptions get-iam-policy \ projects/${PROJECT}/subscriptions/${SUBSCRIPTION} \ --format json
Output:
{ "etag": "BwUjMhCsNvY=", "bindings": [ { "role": "roles/pubsub.admin", "members": [ "user:user-1@gmail.com" ] }, { "role": "roles/pubsub.editor", "members": [ "serviceAccount:service-account-2@appspot.gserviceaccount.com", "user:user-3@gmail.com" } ] }
Go
Before trying this sample, follow the Go setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Go API reference documentation.
Java
Before trying this sample, follow the Java setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Java API reference documentation.
Node.js
Before trying this sample, follow the Node.js setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Node.js API reference documentation.
PHP
Before trying this sample, follow the PHP setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub PHP API reference documentation.
Python
Before trying this sample, follow the Python setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Python API reference documentation.
Ruby
Before trying this sample, follow the Ruby setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Ruby API reference documentation.
Here is some sample code to get a policy for a topic:
C#
Before trying this sample, follow the C# setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub C# API reference documentation.
gcloud
Get the topic policy
gcloud pubsub topics get-iam-policy \ projects/${PROJECT}/topics/${TOPIC} \ --format json
Output:
{ "etag": "BwUjMhCsNvY=", "bindings": [ { "role":" roles/pubsub.viewer", "members": [ "user:user-1@gmail.com" ] } ] }
Go
Before trying this sample, follow the Go setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Go API reference documentation.
Java
Before trying this sample, follow the Java setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Java API reference documentation.
Node.js
Before trying this sample, follow the Node.js setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Node.js API reference documentation.
PHP
Before trying this sample, follow the PHP setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub PHP API reference documentation.
Python
Before trying this sample, follow the Python setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Python API reference documentation.
Ruby
Before trying this sample, follow the Ruby setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Ruby API reference documentation.
Setting a policy
The setIamPolicy()
method lets you attach a policy
to a resource. The setIamPolicy()
method takes a SetIamPolicyRequest
, which
contains the policy to be set and the resource to which the policy is attached.
It returns the resulting policy.
Here is some sample code to set a policy for a subscription:
C#
Before trying this sample, follow the C# setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub C# API reference documentation.
gcloud
1. Save the policy for the subscription.
gcloud pubsub subscriptions get-iam-policy \ projects/${PROJECT}/subscriptions/${SUBSCRIPTION} \ --format json > subscription_policy.json
2. Open subscription_policy.json
and update bindings by giving appropriate roles to appropriate members.
For more information about working with subscription_policy.json
files, see
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.
gcloud pubsub subscriptions set-iam-policy \ projects/${PROJECT}/subscriptions/${SUBSCRIPTION} \ subscription_policy.json
Go
Before trying this sample, follow the Go setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Go API reference documentation.
Java
Before trying this sample, follow the Java setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Java API reference documentation.
Node.js
Before trying this sample, follow the Node.js setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Node.js API reference documentation.
PHP
Python
Before trying this sample, follow the Python setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Python API reference documentation.
Ruby
Before trying this sample, follow the Ruby setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Ruby API reference documentation.
Here is some sample code to set a policy for a topic:
C#
Before trying this sample, follow the C# setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub C# API reference documentation.
gcloud
1. Save the policy for the topic.
gcloud pubsub topics get-iam-policy \ projects/${PROJECT}/topics/${TOPIC} \ --format json > topic_policy.json
2. Open topic_policy.json
and update bindings by giving appropriate roles to appropriate members.
For more information about working with subscription_policy.json
files, see
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.
gcloud pubsub topics set-iam-policy \ projects/${PROJECT}/topics/${TOPIC} \ topic_policy.json
Go
Before trying this sample, follow the Go setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Go API reference documentation.
Java
Before trying this sample, follow the Java setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Java API reference documentation.
Node.js
Before trying this sample, follow the Node.js setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Node.js API reference documentation.
PHP
Python
Before trying this sample, follow the Python setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Python API reference documentation.
Ruby
Before trying this sample, follow the Ruby setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Ruby API reference documentation.
Testing permissions
You can use the testIamPermissions()
method to check which of the given
permissions the caller has for the given resource. It takes as parameters a
resource name and a set of permissions, and returns the caller's subset of
permissions.
Here is some sample code to test permissions for a subscription:
C#
Before trying this sample, follow the C# setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub C# API reference documentation.
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
Before trying this sample, follow the Go setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Go API reference documentation.
Java
Before trying this sample, follow the Java setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Java API reference documentation.
Node.js
Before trying this sample, follow the Node.js setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Node.js API reference documentation.
PHP
Before trying this sample, follow the PHP setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub PHP API reference documentation.
Python
Before trying this sample, follow the Python setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Python API reference documentation.
Ruby
Before trying this sample, follow the Ruby setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Ruby API reference documentation.
Here is some sample code to test permissions for a topic:
C#
Before trying this sample, follow the C# setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub C# API reference documentation.
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
Before trying this sample, follow the Go setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Go API reference documentation.
Java
Before trying this sample, follow the Java setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Java API reference documentation.
Node.js
Before trying this sample, follow the Node.js setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Node.js API reference documentation.
PHP
Before trying this sample, follow the PHP setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub PHP API reference documentation.
Python
Before trying this sample, follow the Python setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Python API reference documentation.
Ruby
Before trying this sample, follow the Ruby setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Ruby API reference documentation.
Sample use case: cross-project communication
Pub/Sub IAM is useful for fine-tuning access in cross-project communication. For example, suppose a service account in Cloud Project A wants to publish messages to a topic in Cloud Project B. You could accomplish this by granting the service account Edit permission in Cloud Project B. However, this approach is often too coarse. You can use the IAM API to achieve a more fine-grained level of access.
For example, this snippet uses the setIamPolicy()
method in project-b and a prepared
topic_policy.json
file to grant the service account
foobar@
project-a.iam.gserviceaccount.com
of project-a the publisher role on the topic
projects/
project-b/topics/
topic-b:
gcloud pubsub topics set-iam-policy \ projects/project-b/topics/topic-b \ topic_policy.jsonOutput:
Updated IAM policy for topic topic-b. bindings: - members: - serviceAccount:foobar@project-a.iam.gserviceaccount.com role: roles/pubsub.publisher etag: BwWGrQYX6R4=
Partial availability behavior
Authorization checks depend on the IAM subsystem. In order to offer consistently low response latency for data operations (publishing and message consumption), the system may fall back on cached IAM policies. For information about when your changes will take effect, see the IAM documentation.