Cloud IAM

Establish fine-grained identity and access management for Google Cloud resources

• Google Cloud's Identity and Access Management (IAM) service lets you create and manage permissions for Google Cloud resources.

• Cloud IAM unifies access control for Google Cloud services into a single system and provides a consistent set of operations.

IAM Custom Roles

• To get the list of permissions available for your project.

gcloud iam list-testable-permissions 
//cloudresourcemanager.googleapis.com/projects/$DEVSHELL_PROJECT_ID

• To view the role metadata For example: roles/viewer or roles/editor

gcloud iam roles describe [ROLE_NAME]

• To list grantable roles from your project:

gcloud iam list-grantable-roles 
//cloudresourcemanager.googleapis.com/projects/$DEVSHELL_PROJECT_ID

Creating a custom role

Use the gcloud iam roles create command to create new custom roles. You can use this command in two ways:

• By providing a YAML file that contains the role definition

• By using flags to specify the role definition When creating a custom role, you must specify whether it applies to the organization level or project level by using the --organization [ORGANIZATION_ID] or --project [PROJECT_ID] flags. Each example below creates a custom role at the project level.

To create a custom role using a YAML file

Create a YAML file that contains the definition for your custom role. The file must be structured in the following way:

title: [ROLE_TITLE]
description: [ROLE_DESCRIPTION]
stage: [LAUNCH_STAGE]
includedPermissions:
- [PERMISSION_1]
- [PERMISSION_2]
content_copy

Each of the placeholder values is described below:

• [ROLE_TITLE] is a friendly title for the role, such as Role Viewer.

• [ROLE_DESCRIPTION] is a short description about the role, such as My custom role description.

• [LAUNCH_STAGE] indicates the stage of a role in the launch lifecycle, such as ALPHA, BETA, or GA.

• includedPermissions specifies the list of one or more permissions to include in the custom role, such as iam.roles.get.

Time to get started! Create your role definition YAML file by running:

nano role-definition.yaml

Add this custom role definition to the YAML file:

title: "Role Editor"
description: "Edit access for App Versions"
stage: "ALPHA"
includedPermissions:
- appengine.versions.create
- appengine.versions.delete
content_copy

Then save and close the file.

Execute the following gcloud command:

gcloud iam roles create editor \
--project $DEVSHELL_PROJECT_ID \
--file role-definition.yaml

Create a custom role using flags

Execute the following gcloud command to create a new role using flags:

gcloud iam roles create viewer \
--project $DEVSHELL_PROJECT_ID \
--title "Role Viewer" \
--description "Custom role description." \
--permissions compute.instances.get,compute.instances.list \
--stage ALPHA

Listing the custom roles

• To list custom roles, specifying either project-level or organization-level custom roles:

gcloud iam roles list --project $DEVSHELL_PROJECT_ID

Editing an existing custom role

Use the gcloud iam roles update command to update custom roles. You can use this command in two ways:

• By providing a YAML file that contains the updated role definition

• By using flags to specify the updated role definition

When updating a custom role, you must specify whether it applies to the organization level or project level by using the --organization [ORGANIZATION_ID] or --project [PROJECT_ID] flags.

The describe command returns the role's definition and includes an etag value that uniquely identifies the current version of the role. The etag value should be provided in the updated role definition to ensure that any concurrent role changes are not overwritten.

To update a custom role using a YAML file

Get the current definition for the role by executing the following gcloud command, replacing [ROLE_ID] with editor.

gcloud iam roles describe [ROLE_ID] \
--project $DEVSHELL_PROJECT_ID

You’ll create a new YAML file with the outputted value. Copy the output from this command.

Create a new-role-definition.yaml file with your editor.

nano new-role-definition.yaml

Paste in the outputted value from the last command and add these two permissions under includedPermissions:

- storage.buckets.get
- storage.buckets.list

Your YAML file will look like this when you're finished:

description: Edit access for App Versions
etag: BwVxIAbRq_I=
includedPermissions:
- appengine.versions.create
- appengine.versions.delete
- storage.buckets.get
- storage.buckets.list
name: projects/[PROJECT_ID]/roles/editor
stage: ALPHA
title: Role Editor

Save and close the file.

Now you’ll use the update command to update the role. Execute the following gcloud command, replacing [ROLE_ID] with editor:

gcloud iam roles update [ROLE_ID] \
--project $DEVSHELL_PROJECT_ID \
--file new-role-definition.yaml

To update a custom role using flags

You can use the following flags to add or remove permissions:

• --add-permissions: Adds one or more comma-separated permissions to the role.

• --remove-permissions: Removes one or more comma-separated permissions from the role.

Alternatively, you can simply specify the new permissions using the --permissions [PERMISSIONS] flag and providing a comma-separated list of permissions to replace the existing permissions list.

Execute the following gcloud command to add permissions to the viewer role using flags:

gcloud iam roles update viewer \
--project $DEVSHELL_PROJECT_ID \
--add-permissions storage.buckets.get,storage.buckets.list

Disabling a custom role

• To disable the viewer role:

gcloud iam roles update viewer \
--project $DEVSHELL_PROJECT_ID \
--stage DISABLED

Deleting a custom role

• To delete a custom role. Once deleted the role is inactive and cannot be used to create new IAM policy bindings.

gcloud iam roles delete viewer --project $DEVSHELL_PROJECT_ID

After the role has been deleted, existing bindings remain but are inactive. The role can be undeleted within 7 days. After 7 days, the role enters a permanent deletion process that lasts 30 days. After 37 days, the Role ID is available to be used again.

Note: If a role is being phased out, change its role.stage property to DEPRECATED, and set the deprecation_message to let users know what alternative roles should be used or where to get more information.

Undeleting a custom role

Within the 7 days window, you can undelete a role. Deleted roles are in a DISABLED state. You can make it available again by updating the --stage flag:

gcloud iam roles undelete viewer --project $DEVSHELL_PROJECT_ID

Service Accounts and Roles: Fundamentals

Service accounts are a special type of Google account that grant permissions to virtual machines instead of end users.

For example, a Compute Engine VM may run as a service account, and that account can be given permissions to access the resources it needs. This way the service account is the identity of the service, and the service account's permissions control which resources the service can access.

A service account is identified by its email address, which is unique to the account.

Types of Service Accounts

User-managed service accounts

When you create a new Cloud project using Cloud Console and if Compute Engine API is enabled for your project, a Compute Engine Service account is created for you by default. It is identifiable using the email:

[e-mail]
content_copy

If your project contains an App Engine application, the default App Engine service account is created in your project by default. It is identifiable using the email:

[e-mail]
content_copy

Google-managed service accounts

In addition to the user-managed service accounts, you might see some additional service accounts in your project’s IAM policy or in the Cloud Console. These service accounts are created and owned by Google. These accounts represent different Google services and each account is automatically granted IAM roles to access your Google Cloud project.

Google APIs service account

An example of a Google-managed service account is a Google API service account identifiable using the email:

[e-mail]

Creating and Managing Service Accounts

• To create a service account

gcloud iam service-accounts create my-sa-123 --display-name "my service account"

• To grant roles to the service account

gcloud projects add-iam-policy-binding $DEVSHELL_PROJECT_ID \
--member serviceAccount:my-sa-123@$DEVSHELL_PROJECT_ID.iam.gserviceaccount.com \
--role roles/editor

Understanding Roles

Types of Roles

There are three types of roles in Cloud IAM:

• Primitive roles, which include the Owner, Editor, and Viewer roles that existed prior to the introduction of Cloud IAM.

• Predefined roles, which provide granular access for a specific service and are managed by Google Cloud.

• Custom roles, which provide granular access according to a user-specified list of permissions.