Background

Identity and Access Management custom roles enable you to grant granular permissions to useraccounts and service accounts. Unlike predefined roles, which are maintained byGoogle and updated accordingly, custom roles are maintained by your organizationas new permissions become available.

Cloud Deployment Manager can make it easier to configure and maintainyour custom roles. You can use Deployment Manager to describe rolesusing configuration files, that can then be checked in to your source controlsystem of choice. Together, Deployment Manager and source control canmake it easier to make "config-as-code" for:

• Tracking custom roles as they change over time
• Promoting custom roles through launch stages as they are tested andvalidated
• Automating how roles are deployed throughout your organization

Before you begin

• Enable the IAM and Cloud Deployment Manager APIs.

  Roles required to enable APIs

  To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

  Enable the APIs

Scenarios for maintaining custom roles using Deployment Manager

Consider the following scenarios that demonstrate the benefits of usingDeployment Manager to maintain custom roles:

• Controlling access to new permissions: You have a custom role thatcontains permissions for a Google Cloud service. The service addsnew Beta features and exposes new permissions. Your custom role will notautomatically inherit these new permissions -- they must be added manually.Until the new permissions are added to your custom role, users in yourorganization will not have access to the Beta features. You can useDeployment Manager's configuration files and source control to helpaudit existing permissions, update your custom roles as necessary, andmaintain a revision history.
• Role lifecycle management: You have a new custom role to which you haveassigned anALPHA launch stage. After the custom role has been tested andvalidated, you can use Deployment Manager to update the customrole's configuration and advance it toBETA stage without using theGoogle Cloud console.
• Understanding custom roles adoption: By having more of yourorganization's custom role definitions in source control, it makes it easierto share, learn from patterns of usage, and enforce access controls acrossmultiple projects.

Understanding Deployment Manager configuration files

Deployment Manager uses three different file types to describe adeployment. Each type is described below:

• Configurations are YAML files that describe resources and theirproperties. For Identity and Access Management (IAM) custom roles, each YAML file specifiesall of the properties for one or more custom roles, such as its name,description, and permissions.
• Schemas specify all possible properties for a given resource and theirdefault values. For IAM custom roles, there areschemas for project-level and organization-level custom roles.
• Templates, which are Jinja or Python files that enhance configurationsby allowing you to break down a configuration into reusable parts. ForIAM custom roles, there are two provided templates:one for project-level custom roles, and one for organization-level customroles.

For more information about these types, seeDeployment Manager Fundamentals.

Before you begin

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Deployment Manager and IAM APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

Enable the APIs

Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:

gcloudinit

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Deployment Manager and IAM APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

Enable the APIs

Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:

gcloudinit

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

Once these prerequisite steps have been completed, you can start usingDeployment Manager with IAM to maintain yourcustom roles.

Grant permissions to the Google APIs service account

To maintain custom roles using Deployment Manager, you must first grantthe appropriate permissions to the Google APIs service account. This account iscreated by default for each organization and project.

1. In the Google Cloud console, go to theIAM page.

   Go to the IAM page

2. From the list of principals, locate the principal with the nameGoogleAPIs service agent.

3. To edit the service account's roles, click theEditedit button, and then add theRoles > Role Administrator role.

4. ClickSave to apply the role.

Now that the Google APIs service account has been granted the permission tomaintain custom roles, you can deploy a sample custom role usingDeployment Manager.

Deploy custom roles to your project

As described in thesection above,Deployment Manager uses a combination of configuration files todescribe a deployment. For IAM, consider the following twoexample files for a project's custom roles:

project_custom_role.yaml

imports:-path:project_custom_role.jinjaresources:-name:custom-roletype:project_custom_role.jinjaproperties:roleId:myCustomRoletitle:My Titledescription:My description.includedPermissions:-iam.roles.get-iam.roles.list

This YAML file specifies the properties about a custom role namedcustom-role,which grants permissions toiam.roles.get andiam.roles.list.Note that it references a.jinja file twice; these references use the valuesprovided by the Jinja template as described below.

project_custom_role.jinja

# Copyright 2017 Google LLC. All rights reserved.# Licensed under the Apache License, Version 2.0 (the "License");# you may not use this file except in compliance with the License.# You may obtain a copy of the License at#     http://www.apache.org/licenses/LICENSE-2.0# Unless required by applicable law or agreed to in writing, software# distributed under the License is distributed on an "AS IS" BASIS,# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.# See the License for the specific language governing permissions and# limitations under the License.resources:-name:custom-roletype:gcp-types/iam-v1:projects.rolesproperties:parent:projects/{{ env["project"] }}roleId:{{properties["roleId"]}}role:title:{{properties["title"]}}description:{{properties["description"]}}stage:{{properties["stage"]}}includedPermissions:{{properties["includedPermissions"]}}

This Jinja file provides a template for a custom role to minimize duplicationof the same properties across many roles. Default values are inserted from a.schema file if the corresponding YAML file does not specify values foreach property.

To deploy this custom role with Deployment Manager:

1. Download the contents ofthis GitHub repositoryto your local machine.
2. In a terminal window, navigate to theexamples/v2/iam_custom_role/jinjadirectory in the downloaded repository. It contains theproject_custom_role.yaml file and the associated Jinja files.

3. Execute the following command to deploy the example custom role, replacingtheyour-deployment-nameplaceholder value with a deployment name of your choice:

   gclouddeployment-managerdeploymentscreate\your-deployment-name--configproject_custom_role.yaml

4. Wait for the operation to complete. The deployment fingerprint and aprogress indicator are shown:

   The fingerprint of the deployment is PUo2fmKdoFdJqiLViHjT3Q==Waiting for create [operation-1513228867042-560460d157ad1-b4ababb8-c6a7dddc]...done.

5. If the operation was successful, you will see the following status message:

   Create operation operation-1513228867042-560460d157ad1-b4ababb8-c6a7dddc completed successfully.NAME         TYPE                             STATE      ERRORS  INTENTcustom-role  gcp-types/iam-v1:projects.roles  COMPLETED  []

View your deployed custom role

To view your custom role in Deployment Manager:

1. In a terminal window, execute the following command:

   gclouddeployment-managerdeploymentsdescribeyour-deployment-name

2. You will see a description of the deployment, including comprehensiveinformation about its status, any errors, and more.

   fingerprint: oaJoGesEFYvsAldP2bm5jQ==id: '3222872306422524501'insertTime: '2018-01-29T13:40:10.822-08:00'manifest: manifest-1517262010855name:your-deployment-nameoperation:endTime: '2018-01-29T13:40:26.500-08:00'name: operation-1517262010573-563f1172be0c9-ce5f0242-239fe1afoperationType: insertprogress: 100startTime: '2018-01-29T13:40:11.535-08:00'status: DONEuser: id-7201362145@my-example-project.iam.gserviceaccount.comNAME         TYPE                             STATE      INTENTcustom-role  gcp-types/iam-v1:projects.roles  COMPLETED

3. You can also see the detailed information about the custom role'sconfiguration by retrieving the deployment'smanifest. In the output fromthedescribe command in step 2 above, note themanifest ID. Copy this ID,including themanifest- prefix, and use it to replace the placeholder valuebelow:

   gclouddeployment-managermanifestsdescribeyour-manifest-id\--deploymentyour-deployment-name

4. The manifest contains exhaustive information about the custom roledeployment, including the raw contents of the sourceproject_custom_role.yaml andproject_custom_role.jinja files. Inparticular, note theresources block near the bottom of the manifest,which summarizes the details about the custom role:

   ...resources:-name:custom-roleproperties:description:My description.includedPermissions:-iam.roles.get-iam.roles.listroleId:aCustomRolestage:ALPHAtitle:My Titleresources:-name:custom-roletype:gcp-types/iam-v1:projects.rolestype:project_custom_role.jinja...

To view your custom role in the Google Cloud console:

1. In the Google Cloud console, go to theIAM page.

   Go to the IAM page

2. Select a project and clickOpen.

3. On the left menu, clickRoles.

4. Click the name of the newly created custom role from the list. It should look similar to the screenshot below: