Access Control for Organizations using IAM

Google Cloud Platform offers Cloud Identity Access Management (IAM), which lets you give more granular access to specific Google Cloud Platform 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 Identity and Access Management (IAM) roles that are available at the organization level, and how to create and manage IAM policies for organizations using the Google Cloud Resource Manager API. For a detailed description of Cloud Identity Access Management, read the IAM documentation. In particular, see Granting, Changing, and Revoking Access.

Permissions and roles

With Cloud Identity Access Management, every Google Cloud Platform method requires that the account making the API request has appropriate permissions to access the resource. Permissions allow users to perform specific actions on Cloud resources. For example, the resourcemanager.organizations.list permission allows a user to list the organizations they own, while resourcemanager.organizations.update allows a user to update an organization's metadata.

The following table lists the permissions that the caller must have to call an organization method:

Method Required Permission(s)
resourcemanager.organizations.get() resourcemanager.organizations.get.
resourcemanager.organizations.search() Returns all Organizations for which the user has the resourcemanager.organizations.get permission.
resourcemanager.organizations.getIamPolicy() resourcemanager.organizations.getIamPolicy
resourcemanager.organizations.setIamPolicy() resourcemanager.organizations.setIamPolicy
resourcemanager.organizations.testIamPermissions() Does not require any permission.

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.

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 Description Permissions
roles/
resourcemanager.organizationAdmin
Access to administer all resources belonging to the organization
  • resourcemanager.organizations.get
  • resourcemanager.organizations.update
  • resourcemanager.organizations.getIamPolicy
  • resourcemanager.organizations.setIamPolicy
  • resourcemanager.projects.get
  • resourcemanager.projects.list
  • resourcemanager.projects.getIamPolicy
  • resourcemanager.projects.setIamPolicy
  • resourcemanager.projectInvites.get
roles/
resourcemanager.organizationViewer
Access to view the organization's display name. Granting this role to a user will allow that user to see the organization in the Cloud Console without having access to view all resources in the organization.
  • resourcemanager.organizations.get
roles/
browser
Access to browse resources in an organization
  • resourcemanager.organizations.get
  • resourcemanager.projects.get
  • resourcemanager.projects.getIamPolicy
  • resourcemanager.projects.list
  • resourcemanager.projectInvites.get

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 Platform Console, the gcloud command-line tool, or the getIamPolicy() method.

Console

To get access control at the organization level using Cloud Platform Console:

  1. Go to the Google Cloud Platform Console:

    Go to Google Cloud Platform Console

  2. Click on the Organization drop-down on top of the page.

  3. Select your organization in the organization drop-down and then select IAM/Permissions.

  4. The IAM page is displayed, which lists all the members and their corresponding roles for the organization.

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/v1/organizations/12345.

Request:

POST
https://cloudresourcemanager.googleapis.com/v1/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', 'v1', 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 access to team members to access an organization's resources and APIs by granting IAM roles to team members. You can grant a role to a team member using the Cloud Platform Console, the gcloud tool, or the setIamPolicy() method.

Console

To set access control at the organization level using Cloud Platform Console:

  1. Go to the Google Cloud Platform Console:

    Go to Google Cloud Platform Console

  2. Click on the Organization drop-down on top of the page.

  3. Select your organization in the organization drop-down and then select IAM/Permissions. The IAM page is displayed.

  4. Click Add member to add new members to the organization and set their permissions.

gcloud

To set a organization's IAM policy using the gcloud command:

  1. 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]
    
  2. 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="
    }
    
  3. 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="
    }
    
  4. 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/v1/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 a Cloud IAM policy to the organization. The Cloud 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. Cloud Identity Access Management solves this problem using an etag property in Cloud IAM policies. This property is used to verify whether the policy has changed since the last request. When you make a request to Cloud IAM with an etag value, Cloud 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', 'v1', 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

testIamPermissions() allows you to test Cloud IAM permissions on a user for the organization. It takes the resource URL and a set of permissions as input parameters, and returns the set of permissions that the caller is allowed.

You typically don't invoke testIamPermission() if you're using Cloud Platform 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 Platform 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/v1/organization/12345:testIamPermissions

{
    "permissions":  [
        "resourcemanager.organizations.get",
        "resourcemanager.organizations.update"
    ]
}

Response:

{
    "permissions": [
        "resourcemanager.organizations.get"
    ]
}

Python

...

crm = discovery.build(
    'cloudresourcemanager', 'v1', http=creds.authorize(httplib2.Http()))

response = crm.organizations().testIamPermissions(
    resource=flags.organizationId,
    body={
        'resource': flags.organizationId,
        'permissions': [
            'resourcemanager.organizations.setIamPolicy',
            'resourcemanager.projects.update'
        ]
    }).execute()

print json.dumps(response, indent=2)

...

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Google Cloud Resource Manager Documentation