Cloud Identity and Access Management recommender

This page describes the Cloud Identity and Access Management recommender.

Overview

The Cloud IAM recommender helps you enforce the security principle of least privilege by comparing granted permissions with permissions that the users actually need.

This recommender evaluates permission usage for each user over the last 90 days. Using machine learning, it predicts the permissions users need. Based on those predictions, it suggests revoking unused roles or replacing underutilized roles with more restrictive ones that still include the needed permissions.

Recommendations based on machine learning provide insight into larger patterns that cannot be captured by reviewing the isolated usage of a single user over a limited time period. For example, some required permissions might be used less often than every 90 days. Basing a prediction solely on 90-day window of usage would result suggestions to revoke necessary permissions.

The following are examples of recommendations generated by this recommender:

  • A user was initially granted the Project Editor (roles/editor) role on a project. However, they haven't accessed any resources in the project during the past 60 days. The Cloud IAM role recommender suggests that you remove this role binding.

  • A user was initially granted the BigQuery Data Owner (roles/bigquery.dataOwner) role on a project. However, they have only read data from the dataset and haven't performed any write operations during the past 60 days. The Cloud IAM role recommender suggests that you replace the BigQuery Data Owner role binding with the less permissive BigQuery Data Viewer (roles/bigquery.dataViewer) role.

More information about the recommender is available in the Cloud IAM documentation.

Recommender ID

The Cloud IAM role recommender ID is:

google.iam.policy.Recommender

You use this ID when you view and modify recommendations using gcloud commands, or the REST and RPC APIs.

Location

The Recommender gcloud commands and APIs require you to specify a location for recommendations that you view or modify. A location is a region, zone, or multi-regional area. For Cloud Identity and Access Management role recommendations, use global as the location in gcloud and API interactions.

Permissions

To view or update recommendations from the Cloud Identity and Access Management role recommender, you must have the required permissions.

Required permissions

To view Cloud Identity and Access Management recommendations:

  • recommender.iamPolicyRecommendations.get
  • recommender.iamPolicyRecommendations.list

To modify Cloud Identity and Access Management recommendations:

  • recommender.iamPolicyRecommendations.update

Granting permissions

To grant the required permissions to view or modify Cloud Identity and Access Management recommendations, assign roles as follows:

  • To view recommendations only, grant one of the following roles:
    • IAM Recommender Viewer (roles/recommender.iamViewer) role
    • IAM Security Reviewer (roles/iam.securityReviewer) role
  • To view and modify recommendations, grant the IAM Recommender Admin (roles/recommender.iamAdmin) role.
  • To grant the serviceusage.services.use permission, grant the Service Usage Consumer role (roles/serviceusage.serviceUsageConsumer).

As an alternative, you can also grant the following primitive roles:

  • To view recommendations only, grant the Viewer (roles/viewer) role.
  • To view and modify recommendations, grant the Owner (roles/owner) or Editor (roles/editor) role.
    • These roles also include the serviceusage.services.use permission.

Recommendation Subtypes

This Recommender supports the following subtypes:

  • REMOVE_ROLE - Recommends removing a user's current role.
  • REPLACE_ROLE - Recommends replacing a user's current role with one or more roles.

Operations

Each recommendation generated by the Cloud Identity and Access Management role recommender has one or more operation groups that describe a set of actions that must be taken in order to apply the recommendation.

Cloud Identity and Access Management role recommendations can have the following actions:

Action Description
add Adds a role to a user.
remove Remove a role from a user.

These actions may appear in combination, depending on the operations required to apply a recommendation.

Examples

The following example shows how to list Cloud Identity and Access Management role recommendations:

  1. Set required environment variables:

    PROJECT=TARGET_PROJECT_ID
    LOCATION=global
    RECOMMENDER=google.iam.policy.Recommender
    

    where TARGET_PROJECT_ID is the project whose recommendations you want to list. This can be a different project than your current project.

    • For gcloud commands, you must use the project ID
    • For API requests, you can use the project number or project ID. Project number is recommended. The project number is returned in responses from both the API and gcloud commands.
  2. List Cloud Identity and Access Management role recommendations:

    gcloud

    Enter the following:

    gcloud beta recommender recommendations list \
        --project=${PROJECT} \
        --location=${LOCATION} \
        --recommender=${RECOMMENDER} \
        --format=json
    

    REST

    Enter the following:

    curl \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
        -H "x-goog-user-project: ${PROJECT}" \
        "https://recommender.googleapis.com/v1beta1/projects/${PROJECT}/locations/${LOCATION}/recommenders/${RECOMMENDER}/recommendations"
    

The output is similar to the following:

[
  {
    "content": {
      "operationGroups": [
        {
          "operations": [
            {
              "action": "remove",
              "path": "/iamPolicy/bindings/*/members/*",
              "pathFilter": {
                "/iamPolicy/bindings/*/condition/expression": "",
                "/iamPolicy/bindings/*/members/*": "serviceAccount:id-7201362145@example-project.iam.gserviceaccount.com",
                "/iamPolicy/bindings/*/role": "roles/iam.roleAdmin"
              },
              "resource": "//cloudresourcemanager.googleapis.com/projects/example-project",
              "resourceType": "cloudresourcemanager.googleapis.com/Project"
            }
          ]
        }
      ]
    },
    "description": "This role has not been used during the observation window.",
    "etag": "\"770237e2c0decf40\"",
    "lastRefreshTime": "2019-07-02T06:06:17Z",
    "name": "projects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/f27dcb91-9695-4436-8abe-f085007cf20f",
    "primaryImpact": {
      "category": "SECURITY"
    },
    "stateInfo": {
      "state": "ACTIVE"
    }
  }
]

See Using the API for instructions on performing additional tasks on recommendations using the Recommender gcloud commands and APIs.

Was this page helpful? Let us know how we did:

Send feedback about...

Recommender Documentation