Reviewing and applying recommendations

This page explains how to view, understand, and apply recommendations made by the Cloud IAM recommender. The Cloud IAM recommender helps you enforce the principle of least privilege by ensuring that members have only the permissions that they actually need.

Before you read this page, you should be familiar with the overview of the Cloud IAM recommender. Also, make sure you have the Cloud IAM permissions that you need in order to work with the Cloud IAM recommender.

Reviewing and applying recommendations

The easiest way to review and apply your recommendations is to use the Google Cloud Console. You must use the Cloud Console to complete some tasks:

  • Viewing details about why you received a recommendation
  • Dismissing recommendations
  • Automatically creating a custom role when you apply a recommendation

You can also review and apply recommendations with the gcloud command-line tool and the Recommender API.

Console

  1. Go to the IAM page in the Cloud Console.

    Go to the IAM page

  2. In the list of members of your project, find the Over granted permissions column.

    For each role granted to a member, this column shows the number of unused permissions in the role over the past 90 days, followed by the total number of permissions in the role:

    The Recommendation available icon indicates that a recommendation is available for a role, either to revoke the role or to replace it with a role that includes fewer permissions.

    The Recommendation not available icon indicates that there are no recommended changes to the role. To find out why, hold the pointer over the icon.

  3. If there are recommendations to review, click a Recommendation available icon to get details about the recommendation.

    If the recommendation is to replace the role, the Cloud IAM recommender always suggests a set of predefined roles that you can apply.

    In some cases, the Cloud IAM recommender also suggests creating a new custom role at the project level. If a custom role recommendation is available, the Cloud Console shows it by default. To switch to the predefined role recommendation, click View recommended predefined role.

  4. Review the recommendation carefully, and make sure you understand how it will change the member's access to Google Cloud resources. See Reviewing recommendations to understand the types of changes that a recommendation can include.

  5. (Optional) If the recommendation is to create a custom role, update the Title, Description, ID, and Role launch stage as needed.

    If you need to add permissions to the custom role, click Add permissions.

    If you need to remove permissions from the custom role, clear the checkbox for each permission that you want to remove.

  6. Take action on the recommendation.

    To apply the recommendation, click Apply or Create and apply, then confirm your choice. If you change your mind in the next 90 days, use the Cloud IAM recommender logs to revert your choice.

    To dismiss the recommendation, click Dismiss, then confirm your choice. You can restore a dismissed recommendation as long as the recommendation is still valid.

  7. Repeat the previous steps until you have reviewed all of your recommendations.

gcloud command

To list your recommendations, run the gcloud recommender recommendations list command:

gcloud recommender recommendations list \
    --location=global \
    --recommender=google.iam.policy.Recommender \
    --project=project-id \
    --format=format

Replace the following values:

  • project-id: The project identifier, such as project-123.
  • format: The format of the response. Use json or yaml.

The response is similar to the following example. In this example, a service account has not used any permissions from the Compute Admin role (roles/compute.admin) in the past 90 days. As a result, the Cloud IAM recommender suggests that you revoke the role:

[
  {
    "content": {
      "operationGroups": [
        {
          "operations": [
            {
              "action": "remove",
              "path": "/iamPolicy/bindings/*/members/*",
              "pathFilter": {
                "/iamPolicy/bindings/*/condition/expression": "",
                "/iamPolicy/bindings/*/members/*": "serviceAccount:id-1234567890@example-project.iam.gserviceaccount.com",
                "/iamPolicy/bindings/*/role": "roles/compute.admin"
              },
              "resource": "//cloudresourcemanager.googleapis.com/projects/example-project",
              "resourceType": "cloudresourcemanager.googleapis.com/Project"
            }
          ]
        }
      ]
    },
    "description": "This role has not been used during the observation window.",
    "recommenderSubtype": "REMOVE_ROLE",
    "etag": "\"770237e2c0decf40\"",
    "lastRefreshTime": "2020-01-09T06:06:17Z",
    "name": "projects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f",
    "primaryImpact": {
      "category": "SECURITY",
        "securityProjection": {
          "revokedIamPermissionsCount": 708
        }
    },
    "stateInfo": {
      "state": "ACTIVE"
    }
  }
]

Review each recommendation carefully, and consider how it will change the member's access to Google Cloud resources.

To apply a recommendation:

  1. Use the gcloud recommender recommendations mark-claimed command to change the recommendation's state to CLAIMED, which prevents the recommendation from changing while you apply it:

    gcloud recommender recommendations mark-claimed \
        recommendation-id \
        --location=global \
        --recommender=google.iam.policy.Recommender \
        --project=project-id \
        --format=format \
        --etag=etag \
        --state-metadata=state-metadata
    

    Replace the following values:

    • recommendation-id: The unique identifier for the recommendation. This value appears at the end of the name field in the recommendation. In the example shown above, the ID is fb927dc1-9695-4436-0000-f0f285007c0f.
    • project-id: The project identifier, such as project-123.
    • format: The format of the response. Use json or yaml.
    • etag: The value of the etag field in the recommendation, such as "dd0686e7136a4cbb". Note that this value can include quotes.
    • state-metadata: Optional. Comma-separated key-value pairs that contain your choice of metadata about the recommendation. For example, --state-metadata=reviewedBy=alice,priority=high. The metadata replaces the stateInfo.stateMetadata field in the recommendation.

    If the command succeeds, the response shows the recommendation in a CLAIMED state, as shown in the following example. For clarity, the example omits most fields:

    [
      {
        "description": "This role has not been used during the observation window.",
        "recommenderSubtype": "REMOVE_ROLE",
        "etag": "\"df7308cca9719dcc\"",
        "name": "projects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f",
        "stateInfo": {
          "state": "CLAIMED",
          "stateMetadata": {
            "reviewedBy": "alice",
            "priority": "high"
          }
        }
      }
    ]

  2. Get the Cloud IAM policy for the project, then modify the policy so that it reflects the recommendation.

  3. Update the recommendation's state to SUCCEEDED, if you were able to apply the recommendation, or FAILED, if you could not apply the recommendation:

    gcloud recommender recommendations command \
        recommendation-id \
        --location=global \
        --recommender=google.iam.policy.Recommender \
        --project=project-id \
        --format=format \
        --etag=etag \
        --state-metadata=state-metadata
    

    Replace the following values:

    • command: Use mark-succeeded, if you were able to apply the recommendation, or mark-failed, if you could not apply the recommendation.
    • recommendation-id: The unique identifier for the recommendation. This value appears at the end of the name field in the recommendation. In the example shown above, the ID is fb927dc1-9695-4436-0000-f0f285007c0f.
    • project-id: The project identifier, such as project-123.
    • format: The format of the response. Use json or yaml.
    • etag: The value of the etag field in the recommendation, such as "dd0686e7136a4cbb". Note that this value can include quotes.
    • state-metadata: Optional. Comma-separated key-value pairs that contain your choice of metadata about the recommendation. For example, --state-metadata=reviewedBy=alice,priority=high. The metadata replaces the stateInfo.stateMetadata field in the recommendation.

    For example, if you marked the recommendation as having succeeded, the response shows the recommendation in a SUCCEEDED state. For clarity, this example omits most fields:

    [
      {
        "description": "This role has not been used during the observation window.",
        "recommenderSubtype": "REMOVE_ROLE",
        "etag": "\"dd0686e7136a4cbb\"",
        "name": "projects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f",
        "stateInfo": {
          "state": "SUCCEEDED",
          "stateMetadata": {
            "reviewedBy": "alice",
            "priority": "high"
          }
        }
      }
    ]

REST API

To review your recommendations, use the curl tool to call the REST API. Replace project-id with your project ID:

curl -H "Authorization: Bearer "$(gcloud auth print-access-token) \
    "https://recommender.googleapis.com/v1/projects/project-id/locations/global/recommenders/google.iam.policy.Recommender/recommendations"

The response is similar to the following example. In this example, a service account has not used any permissions from the Compute Admin role (roles/compute.admin) in the past 90 days. As a result, the Cloud IAM recommender suggests that you revoke the role:

[
  {
    "content": {
      "operationGroups": [
        {
          "operations": [
            {
              "action": "remove",
              "path": "/iamPolicy/bindings/*/members/*",
              "pathFilter": {
                "/iamPolicy/bindings/*/condition/expression": "",
                "/iamPolicy/bindings/*/members/*": "serviceAccount:id-1234567890@example-project.iam.gserviceaccount.com",
                "/iamPolicy/bindings/*/role": "roles/compute.admin"
              },
              "resource": "//cloudresourcemanager.googleapis.com/projects/example-project",
              "resourceType": "cloudresourcemanager.googleapis.com/Project"
            }
          ]
        }
      ]
    },
    "description": "This role has not been used during the observation window.",
    "recommenderSubtype": "REMOVE_ROLE",
    "etag": "\"770237e2c0decf40\"",
    "lastRefreshTime": "2020-01-09T06:06:17Z",
    "name": "projects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f",
    "primaryImpact": {
      "category": "SECURITY",
        "securityProjection": {
          "revokedIamPermissionsCount": 708
        }
    },
    "stateInfo": {
      "state": "ACTIVE"
    }
  }
]

Review each recommendation carefully, and consider how it will change the member's access to Google Cloud resources.

To apply a recommendation:

  1. Run the following command to change the recommendation's state to CLAIMED, which prevents the recommendation from changing while you apply it:

    curl -X POST \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "X-Goog-User-Project: project-id" \
        --data-binary @- \
        "https://recommender.googleapis.com/v1/projects/project-id/locations/global/recommenders/google.iam.policy.Recommender/recommendations/recommendation-id:markClaimed" \
    << EOM
    {
      "etag": "etag",
      "stateMetadata": state-metadata
    }
    EOM
    

    Replace every occurrence of the following values:

    • recommendation-id: The unique identifier for the recommendation. This value appears at the end of the name field in the recommendation. In the example shown above, the ID is fb927dc1-9695-4436-0000-f0f285007c0f.
    • project-id: The project identifier, such as project-123.
    • format: The format of the response. Use json or yaml.
    • etag: The value of the etag field in the recommendation, such as "dd0686e7136a4cbb". Use backslashes to escape quotes.
    • state-metadata: Optional. An object that contains key-value pairs with your choice of metadata about the recommendation. For example, {"reviewedBy": "alice", "priority": "high"}. The metadata replaces the stateInfo.stateMetadata field in the recommendation.

    If the command succeeds, the response shows the recommendation in a CLAIMED state, as shown in the following example. For clarity, the example omits most fields:

    [
      {
        "description": "This role has not been used during the observation window.",
        "recommenderSubtype": "REMOVE_ROLE",
        "etag": "\"df7308cca9719dcc\"",
        "name": "projects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f",
        "stateInfo": {
          "state": "CLAIMED",
          "stateMetadata": {
            "reviewedBy": "alice",
            "priority": "high"
          }
        }
      }
    ]

  2. Get the Cloud IAM policy for the project, then modify the policy so that it reflects the recommendation.

  3. Update the recommendation's state to SUCCEEDED, if you were able to apply the recommendation, or FAILED, if you could not apply the recommendation:

    curl -X POST \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "X-Goog-User-Project: project-id" \
        --data-binary @- \
        "https://recommender.googleapis.com/v1/projects/project-id/locations/global/recommenders/google.iam.policy.Recommender/recommendations/recommendation-id:command" \
    << EOM
    {
      "etag": "etag",
      "stateMetadata": state-metadata
    }
    EOM
    

    Replace every occurrence of the following values:

    • command: Use markSucceeded, if you were able to apply the recommendation, or markFailed, if you could not apply the recommendation.
    • recommendation-id: The unique identifier for the recommendation. This value appears at the end of the name field in the recommendation. In the example shown above, the ID is fb927dc1-9695-4436-0000-f0f285007c0f.
    • project-id: The project identifier, such as project-123.
    • format: The format of the response. Use json or yaml.
    • etag: The value of the etag field in the recommendation, such as "dd0686e7136a4cbb". Use backslashes to escape quotes.
    • state-metadata: Optional. An object that contains key-value pairs with your choice of metadata about the recommendation. For example, {"reviewedBy": "alice", "priority": "high"}. The metadata replaces the stateInfo.stateMetadata field in the recommendation.

    For example, if you marked the recommendation as having succeeded, the response shows the recommendation in a SUCCEEDED state. For clarity, this example omits most fields:

    [
      {
        "description": "This role has not been used during the observation window.",
        "recommenderSubtype": "REMOVE_ROLE",
        "etag": "\"dd0686e7136a4cbb\"",
        "name": "projects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f",
        "stateInfo": {
          "state": "SUCCEEDED",
          "stateMetadata": {
            "reviewedBy": "alice",
            "priority": "high"
          }
        }
      }
    ]

Viewing, reverting, and restoring changes

After you apply or dismiss a recommendation, that action appears in the recommendations log. To view the recommendations log:

  1. Go to the IAM page in the Cloud Console.

    Go to the IAM page

  2. Near the top of the screen, click Recommendations log.

    The Cloud Console shows a list of previous actions on your Cloud IAM recommendations.

  3. To view details about a recommendation, click the expander arrow.

    The Cloud Console shows details about the action that was taken, including the member that took the action:

  4. (Optional) If necessary, you can revert the recommendation, which undoes the changes in the recommendation, or restore a recommendation that you dismissed.

    To revert a previously applied change for a recommendation, click Revert. The Cloud Console reverts the changes to the member's roles. The recommendation no longer appears in the Cloud Console.

    To restore a recommendation that was dismissed, click Restore. The recommendation becomes visible on the IAM page in the Cloud Console. No roles or permissions are changed.

What's next