Access control with Identity and Access Management (original) (raw)

Skip to main content

• Technology areas

  • Overview
  • Guides
  • Reference
  • Samples
  • Resources

• Cross-product tools

• Console

• Discover

• Product overview

• Choose Pub/Sub or Cloud Managed Service for Apache Kafka

• Choose Pub/Sub or Cloud Tasks

• Pub/Sub architectural overview

• Pub/Sub reliability

• Pub/Sub Lite documentation

• Get started

• Pub/Sub service overview

• Publish and subscribe with client libraries

• Publish and subscribe with the gcloud CLI

• Publish and subscribe with the console

• Secure and control access

• Authenticate to Pub/Sub

• Access control for Pub/Sub

• Configure message encryption

• Configure message storage policies

• Create and manage tags

• Publish messages

• Publish message overview

• Create a topic

  • Standard topic
  • Amazon Kinesis Data Streams import topic
  • Cloud Storage import topic
  • Azure Event Hubs import topic
  • Amazon Managed Streaming for Apache Kafka (MSK) import topic
  • Confluent Cloud import topic

• Publish messages

• Best practices for publishing

• Receive messages

• Subscription overview

• Choose a subscription type

• Best practices for subscribing

• Validate and transform messages

• Schemas

  • Schema overview
  • Create a schema
  • Commit a schema revision
  • Delete a schema
  • Delete a schema revision
  • List schemas
  • List revisions of a schema
  • Roll back a schema revision
  • View schema details
  • Validate a schema definition
  • Validate a message for a schema

• Monitor and audit

• Monitor Pub/Sub in Cloud Monitoring

• Monitor topics within Pub/Sub

• Monitor subscriptions within Pub/Sub

• View Pub/Sub audit logs

• View Pub/Sub reports with labels

• Use OpenTelemetry tracing

• Best practices for metrics in scaling

• Build Pub/Sub systems

• Build a one-to-many Pub/Sub system

• Replay messages with seek

• Migrate from Kafka to Pub/Sub

• Use the Pub/Sub remote MCP server

• Test and integrate

• Test locally with Pub/Sub emulator

• Connect Pub/Sub to Apache Kafka

• Pub/Sub in Spring applications

• Pub/Sub with Cloud Run

• Work with messages in App Engine

• Stream Pub/Sub messages over WebSockets

• Troubleshoot

• General troubleshooting

• Troubleshooting with audit logs

• Troubleshoot topics

  • Troubleshoot standard topics
  • Troubleshoot import topics
    * Use platform logs to troubleshoot import topics
    * Troubleshoot Amazon Kinesis Data Streams import topics
    * Troubleshoot Cloud Storage import topics
    * Troubleshoot Azure Events Hub import topics
    * Troubleshoot Amazon MSK import topics
    * Troubleshoot Confluent Cloud import topics

• Code samples

• Pub/Sub code samples

Access control with Identity and Access Management

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.

IAM allows you to grant specific roles to users, groups, and service accounts, giving them the necessary permissions to perform their tasks. You can grant these IAM roles using the Google Cloud console or the IAM API.

In Pub/Sub, access control can be configured at the project level and at the individual resource level. Here are some examples for using 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 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.

If you have view-only access to a single resource such as a topic or a subscription, 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.

Types of roles in Pub/Sub

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

• Basic roles: Basic roles are highly permissive roles that existed prior to the introduction of IAM. For more information about basic roles, see Basic roles.
• Predefined roles: Predefined roles give granular access to specific Google Cloud resources. For more information about predefined roles, see Predefined roles. The Pub/Sub predefined roles are included in a later part of this section.
• Custom roles: Custom roles help you enforce the principle of least privilege. For more information about custom roles, seeCustom roles.

Required Pub/Sub permissions

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

Required permissions for topics

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

Required permissions for subscriptions

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

Required permissions for schemas

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

Required permissions for snapshots

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

Available Pub/Sub roles

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

Controlling access through the Google Cloud console

You can use the Google Cloud console to manage access control for your topics and 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. Click Add.
4. Type in one or more principal names.
5. In the Select a role list, select the role you want to grant.
6. Click Save.
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/Sub Topics 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 topic ID. In the Topic details page, click the subscription ID. TheSubscription details page appears.
4. If the info panel is hidden, click Show info panel.
5. In the Permissions tab, clickAdd principal.
6. Type in one or more principal names.
7. In the Select a role list, select the role you want to grant.
8. Click Save.

Controlling access through 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 through 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.

Get 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 inQuickstart: 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

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, see the deprecated code samples.

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

Java

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

Node.js

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

Python

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

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, see the deprecated code samples.

Before trying this sample, follow the Ruby setup instructions inQuickstart: 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 inQuickstart: 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

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, see the deprecated code samples.

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

Java

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

Python

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

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, see the deprecated code samples.

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

Set a policy

The setIamPolicy() method lets you attach a policyto 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 inQuickstart: 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 principals. 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

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, see the deprecated code samples.

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

Java

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

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, see the deprecated code samples.

Before trying this sample, follow the Ruby setup instructions inQuickstart: 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 inQuickstart: 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 principals. 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

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, see the deprecated code samples.

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

Java

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

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, see the deprecated code samples.

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

Test permissions

You can use the testIamPermissions() method to check which of the given permissions can be added or removed for the given resource. It takes as parameters a resource name and a set of permissions, and returns the subset of permissions.

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

C#

Before trying this sample, follow the C# setup instructions inQuickstart: 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

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, see the deprecated code samples.

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

Java

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

Python

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

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, see the deprecated code samples.

Before trying this sample, follow the Ruby setup instructions inQuickstart: 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 inQuickstart: 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

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, see the deprecated code samples.

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

Java

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

Python

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

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, see the deprecated code samples.

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

Cross-project communication

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

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

Second, grant 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 preparedtopic_policy.json file to grant the service accountfoobar@project-a.iam.gserviceaccount.com of project-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 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 theIAM documentation.

What's Next

• If you are having issues accessing or authenticating Pub/Sub resources, see General troubleshooting.

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

Last updated 2026-04-08 UTC.