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.
If you have view-only access to a single topic or subscription, you cannot view the topic or subscription using the Google Cloud console. Instead, you can use Google Cloud CLI.
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 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 required to call each method:
Roles
The following table lists all Pub/Sub roles and the
permissions associated with each role:
Role
|
Permissions
|
Pub/Sub Admin
(
roles/
pubsub.admin
)
Provides full access to topics and subscriptions.
Lowest-level resources where you can grant this role:
-
Schema
-
Snapshot
-
Subscription
-
Topic
|
pubsub.*
pubsub.schemas.attach
pubsub.schemas.commit
pubsub.schemas.create
pubsub.schemas.delete
pubsub.schemas.get
pubsub.schemas.getIamPolicy
pubsub.schemas.list
pubsub.schemas.listRevisions
pubsub.schemas.rollback
pubsub.schemas.setIamPolicy
pubsub.schemas.validate
pubsub.snapshots.create
pubsub.snapshots.delete
pubsub.snapshots.get
pubsub.snapshots.getIamPolicy
pubsub.snapshots.list
pubsub.snapshots.seek
pubsub.snapshots.setIamPolicy
pubsub.snapshots.update
pubsub.subscriptions.consume
pubsub.subscriptions.create
pubsub.subscriptions.delete
pubsub.subscriptions.get
pubsub.
subscriptions.
getIamPolicy
pubsub.subscriptions.list
pubsub.
subscriptions.
setIamPolicy
pubsub.subscriptions.update
pubsub.
topics.
attachSubscription
pubsub.topics.create
pubsub.topics.delete
pubsub.
topics.
detachSubscription
pubsub.topics.get
pubsub.topics.getIamPolicy
pubsub.topics.list
pubsub.topics.publish
pubsub.topics.setIamPolicy
pubsub.topics.update
pubsub.topics.updateTag
resourcemanager.projects.get
serviceusage.quotas.get
serviceusage.services.get
serviceusage.services.list
|
Pub/Sub Editor
(
roles/
pubsub.editor
)
Provides access to modify topics and subscriptions, and access to publish
and consume messages.
Lowest-level resources where you can grant this role:
-
Schema
-
Snapshot
-
Subscription
-
Topic
|
pubsub.schemas.attach
pubsub.schemas.commit
pubsub.schemas.create
pubsub.schemas.delete
pubsub.schemas.get
pubsub.schemas.list
pubsub.schemas.listRevisions
pubsub.schemas.rollback
pubsub.schemas.validate
pubsub.snapshots.create
pubsub.snapshots.delete
pubsub.snapshots.get
pubsub.snapshots.list
pubsub.snapshots.seek
pubsub.snapshots.update
pubsub.subscriptions.consume
pubsub.subscriptions.create
pubsub.subscriptions.delete
pubsub.subscriptions.get
pubsub.subscriptions.list
pubsub.subscriptions.update
pubsub.
topics.
attachSubscription
pubsub.topics.create
pubsub.topics.delete
pubsub.
topics.
detachSubscription
pubsub.topics.get
pubsub.topics.list
pubsub.topics.publish
pubsub.topics.update
pubsub.topics.updateTag
resourcemanager.projects.get
serviceusage.quotas.get
serviceusage.services.get
serviceusage.services.list
|
Pub/Sub Publisher
(
roles/
pubsub.publisher
)
Provides access to publish messages to a topic.
Lowest-level resources where you can grant this role:
|
pubsub.topics.publish
|
Pub/Sub Subscriber
(
roles/
pubsub.subscriber
)
Provides access to consume messages from a subscription and to attach
subscriptions to a topic.
Lowest-level resources where you can grant this role:
-
Snapshot
-
Subscription
-
Topic
|
pubsub.snapshots.seek
pubsub.subscriptions.consume
pubsub.
topics.
attachSubscription
|
Pub/Sub Viewer
(
roles/
pubsub.viewer
)
Provides access to view topics and subscriptions.
Lowest-level resources where you can grant this role:
-
Schema
-
Snapshot
-
Subscription
-
Topic
|
pubsub.schemas.get
pubsub.schemas.list
pubsub.schemas.listRevisions
pubsub.schemas.validate
pubsub.snapshots.get
pubsub.snapshots.list
pubsub.subscriptions.get
pubsub.subscriptions.list
pubsub.topics.get
pubsub.topics.list
resourcemanager.projects.get
serviceusage.quotas.get
serviceusage.services.get
serviceusage.services.list
|
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:
In the Google Cloud console, go to the IAM page.
Go
to IAM
Select your project.
Click
person_add
Add
.
Type in one or more principal names.
In the
Select a role
list, select the role you want to grant.
Click
Save
.
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/Sub
Topics
list.
Go
to Topics
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 topic
ID. In the
Topic details
page, click the subscription ID. The
Subscription details
page appears.
If the info panel is hidden, click
Show info panel
.
In the
Permissions
tab, click
person_add
Add principal
.
Type in one or more principal names.
In the
Select a role
list, select the role you want to grant.
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.
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
:
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"
}
]
}
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"
]
}
]
}
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
:
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
Here is some sample code to
set a policy for a topic
:
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
Testing 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
:
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"
}
]
Here is some sample code to
test permissions for a topic
:
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"
}
]
Sample use case: 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.
![Cross-project communication](/static/pubsub/images/cross_project.svg)
For example, this snippet uses the
setIamPolicy()
method in
project-b
and a prepared
topic_policy.json
file to grant the service account
foobar@
project-a
.iam.gserviceaccount.com
of
project-a
the publisher role on the topic
projects/
project-b
/topics/
topic-b
:
gcloud pubsub topics set-iam-policy \
projects/
project-b
/topics/
topic-b
\
topic_policy.json
Output:
Updated 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
.