Google Cloud offers Identity and Access Management (IAM), which lets you give moregranular access to specific Google Cloud resources and prevents unwantedaccess to other resources. IAM lets you adopt the securityprinciple of leastprivilege, so yougrant 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 usercertain permissions.
This page explains the IAM roles thatare available at the organization resource level, and how to create and manageIAM policies for organization resources using the Cloud Resource Manager API.For a detailed description of IAM, read theIAM documentation. In particular, seeGranting, Changing, and Revoking Access.
Permissions and roles
To control access to resources, Google Cloud requires that accounts making APIrequests have appropriate IAM roles. IAM rolesinclude permissions that allow users to perform specific actions onGoogle Cloud resources. For example, theresourcemanager.organizations.get permission allows a user to get detailsabout their organization resource.
You don't directly give users permissions; instead, you grant themroles, 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 anorganization resource's properties, the description of what the role does, and thepermissions bundled within that role.
| Role | Permissions |
|---|---|
Organization Administrator( Access to manage IAM policies and view organization policies for organizations, folders, and projects. Lowest-level resources where you can grant this role:
|
|
Organization Viewer( Provides access to view an organization. Lowest-level resources where you can grant this role:
|
|
Organization Policy Administrator( Provides access to define what restrictions an organization wants to placeon the configuration of cloud resources by setting Organization Policies. Lowest-level resources where you can grant this role:
|
|
Browser( Read access to browse the hierarchy for a project, including the folder, organization, and allowpolicy. This role doesn't include permission to view resources in the project. Lowest-level resources where you can grant this role:
|
|
Creating custom roles
In addition to the predefined roles described in this topic, you can also createcustom roles that are collections ofpermissions that you tailor to your needs. When creating a custom role for usewith 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.listandfolders.getpermissions, it should also includeprojects.listandprojects.get. - Be aware that the
setIamPolicypermission for organization, folder, and project resources allows the user to grant all other permissions, and so should be assigned with care.
Viewing existing access for an organization resource
You can view what roles a user is granted for an organization resource to bygetting the organization-resource-level IAM policy. You can view a policyof an organization resource using the Google Cloud console, the Google Cloud CLI,or the getIamPolicy()method.
Console
To view granted roles at the organization resource level using the Google Cloud console:
Go to the Manage resources page in the Google Cloud console:
Open the Manage resourcespage
On the Organization drop-down list, select your organization resource.
Select the check box for the organization resource.
On the right side Info Panel, under Permissions, click to expanda role and display all members who have that role.
gcloud
Get the IAM policy for the organization resource using theget-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.comrole: roles/editor- members:- user:admin@gcp-test.comrole:roles/resourcemanager.organizationAdmin- members:- user:testuser2@gcp-test.comrole: roles/resourcemanager.projectCreatoretag": "BwU1aRxWk30="API
The following code snippet returns the policy for the organization resourcehttps://cloudresourcemanager.googleapis.com/v3/organizations/12345.
Request:
POSThttps://cloudresourcemanager.googleapis.com/v3/organizations/12345:getIamPolicyResponse:
{ "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:[email protected]" ] }, { "role": "roles/resourcemanager.projectCreator", "members": [ "user:[email protected]", "user:[email protected]", "serviceAccount:my-other-app@appspot.gserviceaccount.com" ] } ] "etag": "BwUjHYKHHiQ="}Python
The methodgetIamPolicy()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 resource
Organization Administrators can grant IAM roles to team membersso that they can access an organization's resources and APIs. You can grantroles to a Google Account email, a Google Group, a service account, or a G Suitedomain. You can use the Google Cloud console, the gcloud CLI, orthesetIamPolicy()method to grant roles.
Console
To set access control at the organization resource level using the Google Cloud console:
Go to the Manage resources page in the Google Cloud console:
Open the Manage resourcespage
On the Organization drop-down list, select your organization resource.
Select the check box for the organization resource. If you do not have aFolder resource, the organization resource will not be visible. Tocontinue, see the instructions for granting roles through theIAMpage.
If the Info Panel pane on the right is hidden, click Show InfoPanel in the top right corner.
In the Info Panel pane, in the Permissions tab, clickAdd 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 serviceaccount, or a G Suite domain.
In the Select a role drop-down list, select the role you want togrant to the team members.
Click Add.
gcloud
To set an organization resource's IAM policy using the gcloud command:
Get the IAM policy for the organization resource usingthe
get-iam-policycommand 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 thefollowing:
{ "bindings": [ { "members": [ "user:[email protected]" ], "role": "roles/editor" }, { "members": [ "user:[email protected]", ], "role": "roles/resourcemanager.organizationAdmin" }, { "members": [ "user:[email protected]" ], "role": "roles/resourcemanager.projectCreator" }, ], "etag": "BwU1aRxWk30="}Using a text editor, open the JSON file and add a new entry to thebindings array that defines Organization Administrator. For example to make
[email protected]an Organization Administrator, you would change theexample shown above as follows:{ "bindings": [ { "members": [ "user:[email protected]" ], "role": "roles/editor" }, { "members": [ "user:[email protected]", "user:[email protected]" ], "role": "roles/resourcemanager.organizationAdmin" }, { "members": [ "user:[email protected]" ], "role": "roles/resourcemanager.projectCreator" }, ], "etag": "BwU1aRxWk30="}Update the organization resource'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:[email protected]" ] }, { "role": "roles/resourcemanager.projectCreator", "members": [ "user:[email protected]", "user:[email protected]", "serviceAccount:my-other-app@appspot.gserviceaccount.com" ] } ] "etag": "BwUjHYKHHiQ=" }}Response:
{ "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:[email protected]" ] }, { "role": "roles/resourcemanager.projectCreator", "members": [ "user:[email protected]", "user:[email protected]", "serviceAccount:my-other-app@appspot.gserviceaccount.com" ] } ] "etag": "BwUjHYKJUiQ="}The setIamPolicy() method allows you grant roles to users by attaching anIAM policy to the organization resource. The IAMpolicy 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 aconflict if two or more independent processes attempt the sequencesimultaneously. For example, say there are two owners for a project and bothof them are attempting to make conflicting changes to the policy at the sametime. The changes made by one of the project owners could fail in somecases. IAM solves this problem using an etag property inIAM policies. This property is used to verify whether thepolicy has changed since the last request. When you make a request toIAM with an etag value, IAM compares theetag value in the request with the existing etag value associated with thepolicy. 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 policyin GetPolicyResponse contains an etag value.
Python
ThesetIamPolicy()method lets you attach a policy to a resource. The setIamPolicy method takes aSetIamPolicyRequest, which contains a policy to be set and the resource towhich the policy is attached. It returns the resulting policy. It is recommendedto follow the read-modify-writepattern when updating a policy using setIamPolicy().
Here is some sample code to set a policy for an organization resource:
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 Administrator 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.adminEmailif 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)Restricting project visibility for users
Users can see all projects they have access to in the Google Cloud console andin search queries, regardless of whether or not they are in the user's currentlyselected organization resource. You can use the Organization Policy Service to restrict theset of projects that are returned in queries and in the Google Cloud console.This can be used to restrict users to only see projects within your own domain.
The Organization Policy constraintconstraints/resourcemanager.accessBoundaries is alist constraint that is enforced on your organization resource. The constraint accepts a list oforganization resource IDs, which define the set of organization resources thatmake their resources visible to users in a query or the Google Cloud console.
Projects appear under No organization if the user does not have theresourcemanager.organizations.get permission on the parent organizationresource of the project. This can make it seem like a project that is not partof your organization resource is not associated with an organization resource atall. If you use the resourcemanager.accessBoundaries constraint to disallow anorganization resource, projects that belong to that organization resource willnot appear at all in queries or in the Google Cloud console. Any project thathas not yet been migrated to an organization resource will not be visible ifthis constraint is enforced.
We recommend migrating projects that are under No organization to yourorganization resource before enforcing this constraint. For information aboutmigrating projects into an organization resource, seeMoving a project.
For information on setting an organization policy, seeUsing constraints.
Testing permissions
You can test IAM permissions on a user for an organizationresource with thetestIamPermissions()method. This method takes the resource URL and the set of permissions you wantto test as input parameters, and returns the subset of these permissions thatthe user has access to.
You typically don't invoke testIamPermission() if you're using theGoogle Cloud console directly to manage permissions. testIamPermissions() isintended for integration with your proprietary software such as a customizedgraphical user interface. For example, the Google Cloud console usestestIamPermissions() internally to determine which UI should be available tothe logged-in user.
API
You can use thetestIamPermissions()method to check which of the given permissions the caller has for the givenresource. This method takes a resource name and a set of permissions asparameters, and returns the subset of permissions that the caller has.
Here is some sample code to test permissions for an organization resource:
Request:POST https://cloudresourcemanager.googleapis.com/v3/organizations/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)