Google Cloud offers Identity and Access Management (IAM), which lets you give more granular access to specific Google Cloud resources and prevents unwanted access to other resources. IAM lets you adopt the security principle of least privilege, so you grant only the necessary access to your resources.
IAM lets you control who (users) has what access (roles) to which resources by setting IAM policies. IAM policies grant specific role(s) to a user giving the user certain permissions.
This page explains the IAM roles that are available at the organization level, and how to create and manage IAM policies for organizations using the Resource Manager API. For a detailed description of IAM, read the IAM documentation. In particular, see Granting, Changing, and Revoking Access.
Permissions and roles
To control access to resources, Google Cloud requires that accounts making API
requests have appropriate IAM roles. IAM roles
include permissions that allow users to perform specific actions on
Google Cloud resources. For example, the
resourcemanager.organizations.list
permission allows a user to list the
organizations they own.
You don't directly give users permissions; instead, you grant them roles, which have one or more permissions bundled within them.
You can grant one or more roles on the same resource.
Using predefined roles
The following table lists the roles that you can grant to access an organization's properties, the description of what the role does, and the permissions bundled within that role.
Role | Role name | Description | Permissions |
---|---|---|---|
roles/ |
Organization Administrator | Access to administer all resources belonging to the organization. |
|
roles/ |
Organization Viewer | Provides access to view an organization. |
|
roles/ |
Organization Policy Administrator | Provides access to define what restrictions an organization wants to place on the configuration of cloud resources by setting Organization Policies. |
|
roles/ |
Browser | Read access to browse the hierarchy for a project, including the folder, organization, and IAM policy. This role doesn't include permission to view resources in the project. |
|
Creating Custom Roles
In addition to the predefined roles described in this topic, you can also create Custom Roles that are collections of permissions that you tailor to your needs. When creating a Custom Role for use with Resource Manager, be aware of the following points:- List and get permissions, such as
resourcemanager.projects.get/list
, should always be granted as a pair. - When your Custom Role includes the
folders.list
andfolders.get
permissions, it should also includeprojects.list
andprojects.get
. - Be aware that the
setIamPolicy
permission for organizations, folders, and projects allows the user to grant all other permissions, and so should be assigned with care.
Viewing existing access for an organization
You can view what roles a user is granted for an organization to by getting the
organization-level IAM policy. You can view a policy of an organization using
the Cloud Console, the gcloud
command-line tool, or the
getIamPolicy()
method.
Console
To view granted roles at the organization level using the Cloud Console:
Go to the Manage resources page in the Cloud Console:
On the Organization drop-down list, select your organization.
Select the check box for the Organization resource.
On the right side Info Panel, under Permissions, click to expand a role and display all members who have that role.
gcloud
Get the IAM policy for the Organization using the get-iam-policy command:
gcloud alpha organizations get-iam-policy [ORGANIZATION_ID] --format json >
[FILENAME.JSON]
The command outputs the policy, which will be similar to the following:
bindings:
- members:
- user:testuser1@gcp-test.com
role: roles/editor
- members:
- user:admin@gcp-test.com
role:roles/resourcemanager.organizationAdmin
- members:
- user:testuser2@gcp-test.com
role: roles/resourcemanager.projectCreator
etag": "BwU1aRxWk30="
API
The following code snippet returns the policy for the Organization resource
https://cloudresourcemanager.googleapis.com/v3/organizations/12345
.
Request:
POST
https://cloudresourcemanager.googleapis.com/v3/organizations/12345:getIamPolicy
Response:
{
"bindings": [
{
"role": "roles/resourcemanager.organizationAdmin",
"members": [
"user:email1@gmail.com"
]
},
{
"role": "roles/resourcemanager.projectCreator",
"members": [
"user:email2@gmail.com",
"user:email3@gmail.com",
"serviceAccount:my-other-app@appspot.gserviceaccount.com"
]
}
]
"etag": "BwUjHYKHHiQ="
}
Python
The method
getIamPolicy()
allows you to get a policy that was previously set.
...
crm = discovery.build(
'cloudresourcemanager', 'v3', http=creds.authorize(httplib2.Http()))
policy = crm.organizations().getIamPolicy(
resource=flags.organizationId, body={}).execute()
print json.dumps(policy, indent=2)
...
Granting access to an organization
Organization Admins can grant IAM roles to team members so that they can access
an organization's resources and APIs. You can grant roles to a Google Account
email, a Google Group, a service account, or a G Suite domain. You can use
the Cloud Console, the gcloud
tool, or the
setIamPolicy()
method to grant roles.
Console
To set access control at the organization level using the Cloud Console:
Go to the Manage resources page in the Cloud Console:
On the Organization drop-down list, select your organization.
Select the check box for the Organization resource. If you do not have a Folder resource, the Organization resource will not be visible. To continue, see the instructions for granting roles through the IAM page.
If the Info Panel pane on the right is hidden, click Show Info Panel in the top right corner.
In the Info Panel pane, in the Permissions tab, click Add Member.
In the New members field, enter the team members you want to add. You can designate a Google Account email, a Google Group, a service account, or a G Suite domain.
In the Select a role drop-down list, select the role you want to grant to the team members.
Click Add.
gcloud
To set an organization's IAM policy using the gcloud
command:
Get the IAM policy for the Organization using the
get-iam-policy
command and output the policy to a JSON file:gcloud alpha organizations get-iam-policy [ORGANIZATION_ID] --format json > [FILENAME.JSON]
The contents of the JSON file will look similar to the following:
{ "bindings": [ { "members": [ "user:testuser1@gcp-test.com" ], "role": "roles/editor" }, { "members": [ "user:admin@gcp-test.com", ], "role": "roles/resourcemanager.organizationAdmin" }, { "members": [ "user:testuser2@gcp-test.com" ], "role": "roles/resourcemanager.projectCreator" }, ], "etag": "BwU1aRxWk30=" }
Using a text editor, open the JSON file and add a new entry to the bindings array that defines Organization Admin. For example to make
anotheradmin@gcp-test.com
an Organization Admin, you would change the example shown above as follows:{ "bindings": [ { "members": [ "user:testuser1@gcp-test.com" ], "role": "roles/editor" }, { "members": [ "user:admin@gcp-test.com", "user:anotheradmin@gcp-test.com" ], "role": "roles/resourcemanager.organizationAdmin" }, { "members": [ "user:testuser20@gcp-test.com" ], "role": "roles/resourcemanager.projectCreator" }, ], "etag": "BwU1aRxWk30=" }
Update the organization's policy by running the following command:
gcloud alpha organizations set-iam-policy [ORGANIZATION_ID] policy.json
API
Request:
POST https://cloudresourcemanager.googleapis.com/v3/organizations/12345:setIamPolicy
{
"policy": {
"version": "0",
"bindings": [
{
"role": "roles/resourcemanager.organizationAdmin",
"members": [
"user:email1@gmail.com"
]
},
{
"role": "roles/resourcemanager.projectCreator",
"members": [
"user:email2@gmail.com",
"user:email3@gmail.com",
"serviceAccount:my-other-app@appspot.gserviceaccount.com"
]
}
]
"etag": "BwUjHYKHHiQ="
}
}
Response:
{
"bindings": [
{
"role": "roles/resourcemanager.organizationAdmin",
"members": [
"user:email1@gmail.com"
]
},
{
"role": "roles/resourcemanager.projectCreator",
"members": [
"user:email2@gmail.com",
"user:email3@gmail.com",
"serviceAccount:my-other-app@appspot.gserviceaccount.com"
]
}
]
"etag": "BwUjHYKJUiQ="
}
The setIamPolicy()
method allows you grant roles to users by attaching an
IAM policy to the organization. The IAM
policy is a collection of statements that define who has what access.
Read-Modify-Write: A common pattern for updating a resource's metadata, such as the Policy is to read its current state, update the data locally, and then send the modified data for writing. This pattern may result in a conflict if two or more independent processes attempt the sequence simultaneously. For example, say there are two owners for a project and both of them are attempting to make conflicting changes to the policy at the same time. The changes made by one of the project owners could fail in some cases. IAM solves this problem using an etag property in IAM policies. This property is used to verify whether the policy has changed since the last request. When you make a request to IAM with an etag value, IAM compares the etag value in the request with the existing etag value associated with the policy. It writes the policy only if the etag values match.
When you update a policy, first get the policy using getIamPolicy()
,
update the policy, and then write the updated policy using setIamPolicy()
.
Use the etag value when setting the policy only if the corresponding policy
in GetPolicyResponse
contains an etag value.
Python
The
setIamPolicy()
method lets you attach a policy to a resource. The setIamPolicy
method takes a
SetIamPolicyRequest
, which contains a policy to be set and the resource to
which the policy is attached. It returns the resulting policy. It is recommended
to follow the read-modify-write
pattern when updating a policy using setIamPolicy()
.
Here is some sample code to set a policy for an organization:
...
crm = discovery.build(
'cloudresourcemanager', 'v3', http=creds.authorize(httplib2.Http()))
policy = crm.organizations().getIamPolicy(
resource=flags.organizationId, body={}).execute()
admin_binding = next(
(binding
for binding in policy['bindings']
if binding['role'] == 'roles/resourcemanager.organizationAdmin'),
None)
# Add an empty Organization Admin binding if not present.
if not admin_binding:
admin_binding = {
'role': 'roles/resourcemanager.organizationAdmin',
'members': []
}
policy['bindings'].append(admin_binding)
# Add the new Admin (if necessary).
new_admin = 'user:' + flags.adminEmail
if new_admin not in admin_binding['members']:
admin_binding['members'].append(new_admin)
policy = crm.organizations().setIamPolicy(
resource=flags.organizationId,
body={
'resource': flags.organizationId,
'policy': policy
}).execute()
print json.dumps(policy, indent=2)
...
Testing permissions
You can test IAM permissions on a user for an organization with
the
testIamPermissions()
method. This method takes the resource URL and the set of permissions you want
to test as input parameters, and returns the subset of these permissions that
the user has access to.
You typically don't invoke testIamPermission()
if you're using the
Cloud Console directly to manage permissions. testIamPermissions()
is
intended for integration with your proprietary software such as a customized
graphical user interface. For example, the Cloud Console uses
testIamPermissions()
internally to determine which UI should be available to
the logged-in user.
API
You can use the
testIamPermissions()
method to check which of the given permissions the caller has for the given
resource. This method takes a resource name and a set of permissions as
parameters, and returns the subset of permissions that the caller has.
Here is some sample code to test permissions for an organization:
Request:
POST https://cloudresourcemanager.googleapis.com/v3/organization/12345:testIamPermissions
{
"permissions": [
"resourcemanager.organizations.get",
"resourcemanager.organizations.setIamPolicy"
]
}
Response:
{
"permissions": [
"resourcemanager.organizations.get"
]
}
Python
...
crm = discovery.build(
'cloudresourcemanager', 'v3', http=creds.authorize(httplib2.Http()))
response = crm.organizations().testIamPermissions(
resource=flags.organizationId,
body={
'resource': flags.organizationId,
'permissions': [
'resourcemanager.organizations.setIamPolicy',
'resourcemanager.projects.patch'
]
}).execute()
print json.dumps(response, indent=2)
...