This page describes how to grant, change, and revoke access to a resource. You can grant varying levels of access for resources you own to different users by using fine-grained IAM roles.
You can manage user roles with the Cloud Console, the gcloud
command-line tool, the REST API, or the
client libraries. Using the
Cloud Console is the easiest method and is covered in the first half of
this article, as is making quick updates using the
gcloud
command-line tool.
Using programmatic methods for more complex scenarios is covered
in the second half.
If you want to use IAM with Identity-Aware Proxy (IAP) to secure access to your applications, see the IAP documentation.
Before you begin
- Read about the available IAM roles.
Required permissions
To manage access to a project, you need a role that includes the following permissions:
resourcemanager.projects.get
resourcemanager.projects.getIamPolicy
resourcemanager.projects.setIamPolicy
To gain these permissions while following the principle of least privilege, ask your administrator to grant you one of the following roles:
- Project IAM Admin (
roles/resourcemanager.projectIamAdmin
) - Security Admin (
roles/iam.securityAdmin
)
Alternatively, your administrator can grant you a different role with the required permissions, such as a custom role or a more permissive predefined role.
Using the Cloud Console
Using the Cloud Console is a quick and easy way to manage your members' roles. IAM members include users, service accounts, Google groups, and domains.
Viewing current access
To see which IAM roles your members have for a project and its resources, do the following:
In the Cloud Console, go to the IAM page.
The page shows all the members in your project that have IAM roles on your project.
Optional. To view role grants for Google-managed service accounts, select Include Google-provided role grants.
Granting access
To grant an IAM role to a member on a project, do the following:
In the Cloud Console, go to the IAM page.
Click Add.
Enter an email address. You can add individuals, service accounts, or Google Groups as members, but every project must have at least one individual as a member.
Select a role. Roles give members the appropriate level of permission. For best security practices, we strongly recommend giving the member the least amount of privilege needed. Members with Owner-level permissions are also project owners and can manage all aspects of the project, including shutting it down.
Click Save.
To grant a role to a member for more than one project, do the following:
In the Cloud Console, go to the Manage resources page.
Select all the projects for which you want to grant permissions.
Click Show info panel, followed by the Permissions tab.
Enter an email address in the New members field, and select the desired role from the dropdown menu.
Click Save. The member is granted the selected role in each of the selected projects.
Revoking access
In the Cloud Console, go to the IAM page.
Locate the member for whom you want to revoke access, and then click the Edit
button on the right.Click the Delete
button for each role you want to revoke, and then click Save.
Modifying access
There is no special procedure for modifying access. Follow the steps for granting and revoking access until the member has the desired roles.
Using gcloud for quick updates
You can add or revoke a single role using the gcloud
command-line tool's
add-iam-policy-binding
and
remove-iam-policy-binding
commands.
Granting access
To quickly grant a role to a member, run the gcloud
tool's
add-iam-policy-binding
command:
gcloud group add-iam-policy-binding resource \ --member=member --role=role-id
Provide the following values:
group
: Thegcloud
tool group for the resource you want to update. For example, you can useprojects
ororganizations
.resource
: The name of the resource.member
: An identifier for the member, which usually has the following form:member-type:id
. For example,user:my-user@example.com
. For a full list of the values thatmember
can have, see the Policy Binding reference.role-id
: The name of the role.
For example, to grant the Viewer role to the user my-user@example.com
for the
project my-project
:
gcloud projects add-iam-policy-binding my-project \ --member=user:my-user@example.com --role=roles/viewer
Revoking access
To quickly revoke a role from a user, run the gcloud
tool's
remove-iam-policy-binding
command:
gcloud group remove-iam-policy-binding resource \ --member=member --role=role-id
Provide the following values:
group
: Thegcloud
tool group for the resource you want to update. For example, you can useprojects
ororganizations
.resource
: The name of the resource.member
: An identifier for the member, which usually has the following form:member-type:id
. For example,user:my-user@example.com
. For a full list of the values thatmember
can have, see the Policy Binding reference.role-id
: The name of the role.
For example, to revoke the Viewer role from the user my-user@example.com
for
the project my-project
:
gcloud projects remove-iam-policy-binding my-project \ --member=user:my-user@example.com --role=roles/viewer
Controlling access programmatically
In some use cases, it's easier to manage access control programmatically. You
can use the gcloud
command-line tool, the
REST API, or the
client libraries to control access
programmatically. Programmatic methods are useful when making large-scale or
automatic updates that would be time-consuming to perform in the
Cloud Console, or by running gcloud
commands for each member.
Overview of IAM policy
Access to a resource is managed through an IAM policy. A policy is a collection of bindings that associate a member, such as a user account or service account, with a role. Policies are represented using JSON or YAML.
The following example shows a policy where fatima@example.com
has been granted
the Owner role, and wei@example.com
and
service-account-13@appspot.gserviceaccount.com
have been granted the Editor
role:
{
"bindings": [
{
"role": "roles/owner",
"members": [
"user:fatima@example.com"
]
},
{
"role": "roles/editor",
"members": [
"serviceAccount:service-account-13@appspot.gserviceaccount.com",
"user:wei@example.com"
]
}
],
"etag": "BwUjMhCsNvY=",
"version": 1
}
You update a policy for a resource by using the read-modify-write pattern. This means there are no distinct methods for creating, modifying, or revoking user access. Instead, all modifications are made by:
- Reading the current policy by calling
getIamPolicy()
. - Editing the returned policy, either by using a text editor or programmatically, to add or remove any desired members and their role grants.
- Writing the updated policy by calling
setIamPolicy()
.
It's common to grant permissions for an entire project or organization. However, you can also set policies at a more granular level on a wide range of Google Cloud resources, such as Compute Engine instances or Cloud Storage buckets. For a full list of roles and the lowest resource level you can grant each role at, see Understanding Roles.
Getting the current policy
gcloud
Run the get-iam-policy
command for the resource. The following example
shows the
get-iam-policy
command for projects:
gcloud projects get-iam-policy project-id --format=format > filepath
Provide the following values:
project-id
: The project you are updating (for example,my-project
).format
: The valuejson
oryaml
.filepath
: The path to a new output file for the policy.
For example, the following command gets the policy for the project my-project
in JSON format and saves it to the user's home directory:
gcloud projects get-iam-policy my-project --format json > ~/policy.json
REST
The Resource Manager API's
projects.getIamPolicy
method gets a project's IAM policy.
Before using any of the request data below, make the following replacements:
project-id
: Your Google Cloud project ID.policy-version
: The policy version to be returned. Requests should specify the most recent policy version, which is policy version 3. See Specifying a policy version when getting a policy for details.
HTTP method and URL:
POST https://cloudresourcemanager.googleapis.com/v1/projects/project-id:getIamPolicy
Request JSON body:
{ "options": { "requestedPolicyVersion": policy-version } }
To send your request, expand one of these options:
You should receive a JSON response similar to the following:
{ "version": 1, "etag": "BwWKmjvelug=", "bindings": [ { "role": "roles/owner", "members": [ "user:project-owner@example.com" ] }, { "role": "roles/iam.securityReviewer", "members": [ "user:fatima@example.com" ] } ] }
C#
Before trying this sample, follow the C# setup instructions in the IAM Quickstart Using Client Libraries. For more information, see the IAM C# API reference documentation.
Java
Before trying this sample, follow the Java setup instructions in the IAM Quickstart Using Client Libraries. For more information, see the IAM Java API reference documentation.
Python
Before trying this sample, follow the Python setup instructions in the IAM Quickstart Using Client Libraries. For more information, see the IAM Python API reference documentation.
Modifying a policy
Programmatically or using a text editor, modify the local copy of your project's policy to reflect the roles you want to grant or revoke to given users.
Granting a role
To grant roles to your members, modify the role bindings in the policy. To learn what roles you can grant, see Understanding roles.
To grant a role that is already included in the policy:
gcloud
Grant a role by editing the JSON or YAML policy returned by the
get-iam-policy
command. Note that this policy change will not
take effect until you set the updated policy.
The following example grants the Security Reviewer role
(roles/iam.securityReviewer
) to wei@example.com
.
To grant this role, append the user to the members
array for the binding:
{
"role": "roles/iam.securityReviewer",
"members": [
"user:fatima@example.com",
"user:wei@example.com"
]
}
REST
Grant a role by editing the JSON or YAML policy returned by the
get-iam-policy
command. Note that this policy change will not
take effect until you set the updated policy.
The following example grants the Security Reviewer role
(roles/iam.securityReviewer
) to wei@example.com
. To grant this role,
append the user to the members
array for the binding:
{
"role": "roles/iam.securityReviewer",
"members": [
"user:fatima@example.com",
"user:wei@example.com"
]
}
C#
Before trying this sample, follow the C# setup instructions in the IAM Quickstart Using Client Libraries. For more information, see the IAM C# API reference documentation.
Java
Before trying this sample, follow the Java setup instructions in the IAM Quickstart Using Client Libraries. For more information, see the IAM Java API reference documentation.
Python
Before trying this sample, follow the Python setup instructions in the IAM Quickstart Using Client Libraries. For more information, see the IAM Python API reference documentation.
To grant a role that is not yet included in the policy, add a new binding
.
gcloud
Add a new binding by editing the JSON or YAML policy returned by the
get-iam-policy
command. Note that this policy change will not
take effect until you set the updated policy.
The following example grants the Reader role to fatima@example.com
. To grant this
role, add a new binding to the bindings
array for the policy:
{
"role": "roles/reader",
"members": [
"user:fatima@example.com"
]
}
REST
Add a new binding by editing the JSON or YAML policy returned by the
get-iam-policy
command. Note that this policy change will not
take effect until you set the updated policy.
The following example grants the Reader role to fatima@example.com
. To grant this
role, add a new binding to the bindings
array for the policy:
{
"role": "roles/reader",
"members": [
"user:fatima@example.com"
]
}
C#
Before trying this sample, follow the C# setup instructions in the IAM Quickstart Using Client Libraries. For more information, see the IAM C# API reference documentation.
Java
Before trying this sample, follow the Java setup instructions in the IAM Quickstart Using Client Libraries. For more information, see the IAM Java API reference documentation.
Python
Before trying this sample, follow the Python setup instructions in the IAM Quickstart Using Client Libraries. For more information, see the IAM Python API reference documentation.
You can only grant roles related to activated API services. If a service, such as Compute Engine, is not active, you cannot grant roles exclusively related to Compute Engine. For more information, see Enable and disable APIs.
There are some unique constraints when granting permissions on projects,
especially when granting the Owner role. See the
projects.setIamPolicy()
reference documentation
for more information.
Revoking a role
To revoke a role:
gcloud
Revoke a role by editing the JSON or YAML policy returned by the
get-iam-policy
command. This policy change will not
take effect until you set the updated policy.
To revoke a role from a member, delete the desired members or bindings
from the bindings
array for the policy.
REST
Revoke a role by editing the JSON or YAML policy returned by the
get-iam-policy
command. This policy change will not
take effect until you set the updated policy.
To revoke a role from a member, delete the desired members or bindings
from the bindings
array for the policy.
C#
Before trying this sample, follow the C# setup instructions in the IAM Quickstart Using Client Libraries. For more information, see the IAM C# API reference documentation.
Java
Before trying this sample, follow the Java setup instructions in the IAM Quickstart Using Client Libraries. For more information, see the IAM Java API reference documentation.
Python
Before trying this sample, follow the Python setup instructions in the IAM Quickstart Using Client Libraries. For more information, see the IAM Python API reference documentation.
Setting a policy
Once you have modified the policy to grant the desired roles, call
setIamPolicy()
to make the updates.
gcloud
Use the set-iam-policy
command, and provide a path to the JSON file that
contains the updated policy. The following example shows the
set-iam-policy
command for projects:
gcloud projects set-iam-policy project-id filepath
Provide the following values:
project-id
: The project you are updating (for example,my-project
).filepath
: The path to a file that contains the new policy.
The response contains the updated policy.
REST
The Resource Manager API's
projects.setIamPolicy
method sets the policy in the request as the project's new IAM policy.
Before using any of the request data below, make the following replacements:
project-id
: Your Google Cloud project ID.policy
: A JSON representation of the policy that you want to set. For more information about the format of a policy, see the Policy reference.
HTTP method and URL:
POST https://cloudresourcemanager.googleapis.com/v1/projects/project-id:setIamPolicy
Request JSON body:
{ "policy": { policy } }
To send your request, expand one of these options:
The response contains the updated policy.
C#
Java
Before trying this sample, follow the Java setup instructions in the IAM Quickstart Using Client Libraries. For more information, see the IAM Java API reference documentation.
Python
Before trying this sample, follow the Python setup instructions in the IAM Quickstart Using Client Libraries. For more information, see the IAM Python API reference documentation.
To prevent collisions if multiple sources try to update policy simultaneously,
the policy contains an etag
value. When you call setIamPolicy()
,
IAM compares the etag
value in the request with the
existing etag
, and only writes the policy if the values match.
What's next
- Learn how to manage access to folders.
- Learn how to manage access to organizations.
- Read about the available IAM roles.
- Use the Policy Troubleshooter to understand why a user does or doesn't have access to a resource or have permission to call an API.
- Discover how to view the roles that you can grant on a particular resource.
- Learn how to make a member's access conditional with conditional role bindings.
- Explore ways to secure your applications with Identity-Aware Proxy.