Reviewing and applying recommendations

This page explains how to view, understand, and apply role recommendations. Role recommendations help you enforce the principle of least privilege by ensuring that members have only the permissions that they actually need.

Before you begin

Required IAM permissions

This section describes the IAM permissions that you need in order to work with role recommendations.

View recommendations

To view role recommendations, you must have the following permissions for the project, folder, or organization you are viewing, where RESOURCE_TYPE is the resource type you're viewing recommendations for (projects, folders, or organizations).

  • iam.roles.get
  • iam.roles.list
  • recommender.iamPolicyRecommendations.get
  • recommender.iamPolicyRecommendations.list
  • resourcemanager.RESOURCE_TYPE.getIamPolicy

To gain these permissions while following the principle of least privilege, ask your administrator to grant you the following predefined roles:

  • Role Viewer (roles/iam.roleViewer)
  • Either IAM Recommender Viewer (roles/recommender.iamViewer) or IAM Security Reviewer (roles/iam.securityReviewer)

Alternatively, your administrator can grant you a different role that includes the required permissions, such as a custom role or a more permissive predefined role.

Apply and dismiss recommendations

To apply and dismiss recommendations role recommendations, you must have the following permissions for the project, folder, or organization you are managing, where RESOURCE_TYPE is the resource type you're managing recommendations for (projects, folders, or organizations).

  • iam.roles.get
  • iam.roles.list
  • recommender.iamPolicyRecommendations.get
  • recommender.iamPolicyRecommendations.list
  • recommender.iamPolicyRecommendations.update
  • resourcemanager.RESOURCE_TYPE.getIamPolicy
  • resourcemanager.RESOURCE_TYPE.setIamPolicy

To gain these permissions while following the principle of least privilege, ask your administrator to grant you the following predefined roles:

  • Role Viewer (roles/iam.roleViewer)
  • IAM Recommender Admin (roles/recommender.iamAdmin)
  • One of the following roles, depending on the resource type you're managing recommendations for:

    • Projects: Project IAM Admin (roles/resourcemanager.projectIamAdmin)
    • Folders: Folder IAM Admin (roles/resourcemanager.folderIamAdmin)
    • Organizations: Organization Admin (roles/resourcemanager.organizationAdmin)

Alternatively, your administrator can grant you a different role that includes the required permissions, such as a custom role or a more permissive predefined role.

Reviewing and applying recommendations

The easiest way to review and apply your recommendations is to use the Google Cloud Console. Additionally, if you want to automatically create a custom role when you apply a recommendation, you must use the Cloud Console.

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

Recommendations for folder- and organization-level role bindings are not available in the Cloud Console. To view those recommendations, use the gcloud tool or REST API.

Console

  1. In the Cloud Console, go to the IAM page.

    Go to the IAM page

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

    For each role granted to a member, this column shows the number of excess permissions, or permissions that the member does not need, 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.

  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 role recommendation always suggests a set of predefined roles that you can apply.

    In some cases, the role recommendation 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. Except in the case of recommendations for Google-managed service accounts, a recommendation will never increase a member's level of access. See How role recommendations are generated for more information.

    To help you understand the impact of the recommendation, the Cloud Console shows and a color- and symbol-coded list of permissions. This list indicates how the member's permissions will change if you apply the recommendation.

    The types of permissions associated with each color and symbol are as follows:

    • Gray with no symbol: Permissions that are in both the member's current role and the recommended roles.

    • Red with a minus sign : Permissions that are in the member's current role, but not in the recommended roles because the member hasn't used them in the past 90 days.

    • Green with a plus sign : Permissions that are not in the member's current role, but are in the recommended roles. This type of permission appears only in recommendations for Google-managed service accounts.

    • Blue with a Machine learning icon : Permissions that are in both the member's current role and the recommended roles, not because the member has used the permissions in the past 90 days, but because Recommender has determined through machine learning that they are likely to need those permissions in the future.

  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. If you change your mind in the next 90 days, use the recommendations history 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

Review your recommendations:

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

gcloud recommender recommendations list \
    --location=global \
    --recommender=google.iam.policy.Recommender \
    --RESOURCE_TYPE=RESOURCE_ID \
    --format=FORMAT

Replace the following values:

  • RESOURCE_TYPE: The resource type that you want to list recommendations for. Use the value project, folder, or organization.
  • RESOURCE_ID: The ID of the Google Cloud project, folder, or organization that you want to list recommendations for. Project IDs are alphanumeric strings, like my-project. Folder and organization IDs are numeric, like 123456789012.
  • 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 role recommendation suggests that you revoke the role:

[
  {
    "associatedInsights": [
      {
        "insight": "projects/123456789012/locations/global/insightTypes/google.iam.policy.Insight/insights/279ef748-408f-44db-9a4a-1ff8865b9839"
      }
    ],
    "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/123456789012/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f",
    "primaryImpact": {
      "category": "SECURITY",
      "securityProjection": {
        "details": {
          "revokedIamPermissionsCount": 708
        }
      }
    },
    "priority": "P4",
    "stateInfo": {
      "state": "ACTIVE"
    }
  }
]

To learn more about the fields in a recommendation, see the Recommendation reference.

Review each recommendation carefully, and consider how it will change the member's access to Google Cloud resources. For details on the fields of a recommendation, see the Recommendation reference.

To see the permission usage that this recommendation is based on, view the insights that are associated with the recommendation. These insights are listed in the associatedInsights field. To view an insight, do the following:

  • Copy the insight ID. The insight ID is everything after insights/ in the insight field. In the preceding example, the insight ID is 279ef748-408f-44db-9a4a-1ff8865b9839.
  • Follow the instructions to get an insight, using the insight ID you copied and the insight type ID google.iam.policy.Insight.

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 \
        --RESOURCE_TYPE=RESOURCE_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.
    • RESOURCE_TYPE: The resource type that you want to manage recommendations for. Use the value project, folder, or organization.
    • RESOURCE_ID: The ID of the Google Cloud project, folder, or organization that you want to manage recommendations for. Project IDs are alphanumeric strings, like my-project. Folder and organization IDs are numeric, like 123456789012.
    • 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/123456789012/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f",
        "stateInfo": {
          "state": "CLAIMED",
          "stateMetadata": {
            "reviewedBy": "alice",
            "priority": "high"
          }
        }
      }
    ]
  2. Get the 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 \
        --RESOURCE_TYPE=RESOURCE_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.
    • RESOURCE_TYPE: The resource type that you want to manage recommendations for. Use the value project, folder, or organization.
    • RESOURCE_ID: The ID of the Google Cloud project, folder, or organization that you want to manage recommendations for. Project IDs are alphanumeric strings, like my-project. Folder and organization IDs are numeric, like 123456789012.
    • 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/123456789012/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f",
        "stateInfo": {
          "state": "SUCCEEDED",
          "stateMetadata": {
            "reviewedBy": "alice",
            "priority": "high"
          }
        }
      }
    ]

REST

These instructions assume that you have authenticated and set the GOOGLE_APPLICATION_CREDENTIALS environment variable.

Review your recommendations:

The Recommender API's recommendations.list method lists all available recommendations for your project.

Before using any of the request data below, make the following replacements:

  • RESOURCE_TYPE: The resource type that you want to manage recommendations for. Use the value projects, folders, or organizations.
  • RESOURCE_ID: The ID of the Google Cloud project, folder, or organization that you want to manage recommendations for. Project IDs are alphanumeric strings, like my-project. Folder and organization IDs are numeric, like 123456789012.
  • PAGE_SIZE: Optional. The maximum number of results to return from this request. If not specified, the server will determine the number of results to return. If the number of recommendations is greater than the page size, the response contains a pagination token that you can use to retrieve the next page of results.
  • PAGE_TOKEN: Optional. The pagination token returned in an earlier response from this method. If specified, the list of recommendations will start where the previous request ended.
  • FILTER: Optional. A filter expression to restrict the recommendations returned. You can filter recommendations based on the stateInfo.state field. For example, stateInfo.state:"DISMISSED" or stateInfo.state:"FAILED".

HTTP method and URL:

GET https://recommender.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/locations/global/recommenders/google.iam.policy.Recommender/recommendations?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN&filter=FILTER

To send your request, expand one of these options:

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

{
  "recommendations": [
    "name": "projects/123456789012/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f",
    "description": "This role has not been used during the observation window.",
    "lastRefreshTime": "2020-01-09T06:06:17Z",
    "primaryImpact": {
      "category": "SECURITY",
      "securityProjection": {
        "details": {
          "revokedIamPermissionsCount": 708
        }
      }
    },
    "priority": "P4",
    "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"
            }
          ]
        }
      ]
    },
    "stateInfo": {
      "state": "ACTIVE"
    }
    "etag": "\"770237e2c0decf40\"",
    "recommenderSubtype": "REMOVE_ROLE",
    "associatedInsights": [
      {
        "insight": "projects/123456789012/locations/global/insightTypes/google.iam.policy.Insight/insights/279ef748-408f-44db-9a4a-1ff8865b9839"
      }
  ]
}

To learn more about the fields in a recommendation, see the Recommendation reference.

Review each recommendation carefully, and consider how it will change the member's access to Google Cloud resources. For details on the fields of a recommendation, see the Recommendation reference.

To see the permission usage that this recommendation is based on, view the insights that are associated with the recommendation. These insights are listed in the associatedInsights field. To view an insight, do the following:

  • Copy the insight ID. The insight ID is everything after insights/ in the insight field. In the preceding example, the insight ID is 279ef748-408f-44db-9a4a-1ff8865b9839.
  • Follow the instructions to get an insight, using the insight ID you copied and the insight type ID google.iam.policy.Insight.

To apply a recommendation:

  1. Mark the recommendation as CLAIMED:

    The Recommender API's recommendations.markClaimed method marks a recommendation as CLAIMED, which prevents the recommendation from changing while you apply it.

    Before using any of the request data below, make the following replacements:

    • RESOURCE_TYPE: The resource type that you want to manage recommendations for. Use the value projects, folders, or organizations.
    • RESOURCE_ID: The ID of the Google Cloud project, folder, or organization that you want to manage recommendations for. Project IDs are alphanumeric strings, like my-project. Folder and organization IDs are numeric, like 123456789012.
    • RECOMMENDATION_ID: The unique identifier for the recommendation. This value appears at the end of the name field in the recommendation. For example, if the name field is projects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f, the recommendation ID is fb927dc1-9695-4436-0000-f0f285007c0f.
    • ETAG: The value of the etag field in the recommendation, such as "dd0686e7136a4cbb". Use backslashes to escape quotes, for example, "\"df7308cca9719dcc\"".
    • 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.

    HTTP method and URL:

    POST https://recommender.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/locations/global/recommenders/google.iam.policy.Recommender/recommendations/RECOMMENDATION_ID:markClaimed

    Request JSON body:

    {
      "etag": "ETAG"
      "stateMetadata": {
        "STATE_METADATA"
    }
    

    To send your request, expand one of these options:

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

    {
      "description": "This role has not been used during the observation window.",
      "stateInfo": {
        "state": "CLAIMED",
        "stateMetadata": {
          "reviewedBy": "alice",
          "priority": "high"
        }
      }
      "etag": "\"dd0686e7136a4cbb\"",
      "recommenderSubtype": "REMOVE_ROLE"
    }
    

  2. Get the 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:

    SUCCEEDED

    The Recommender API's recommendations.markSucceeded method marks a recommendation as SUCCEEDED, indicating that you were able to apply it.

    Before using any of the request data below, make the following replacements:

    • RESOURCE_TYPE: The resource type that you want to manage recommendations for. Use the value projects, folders, or organizations.
    • RESOURCE_ID: The ID of the Google Cloud project, folder, or organization that you want to manage recommendations for. Project IDs are alphanumeric strings, like my-project. Folder and organization IDs are numeric, like 123456789012.
    • RECOMMENDATION_ID: The unique identifier for the recommendation. This value appears at the end of the name field in the recommendation. For example, if the name field is projects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f, the recommendation ID is fb927dc1-9695-4436-0000-f0f285007c0f.
    • ETAG: The value of the etag field in the recommendation, such as "dd0686e7136a4cbb". Use backslashes to escape quotes, for example, "\"df7308cca9719dcc\"".
    • 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.

    HTTP method and URL:

    POST https://recommender.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/locations/global/recommenders/google.iam.policy.Recommender/recommendations/RECOMMENDATION_ID:markSucceeded

    Request JSON body:

    {
      "etag": "ETAG"
      "stateMetadata": {
        "STATE_METADATA"
    }
    

    To send your request, expand one of these options:

    The response shows the recommendation in a SUCCEEDED state, as shown in the following example. For clarity, this example omits most fields:

    {
      "description": "This role has not been used during the observation window.",
      "stateInfo": {
        "state": "SUCCEEDED",
        "stateMetadata": {
          "reviewedBy": "alice",
          "priority": "high"
        }
      }
      "etag": "\"dd0686e7136a4cbb\"",
      "recommenderSubtype": "REMOVE_ROLE"
    }
    

    FAILED

    The Recommender API's recommendations.markFailed method marks a recommendation as FAILED, indicating that you were not able to apply it.

    Before using any of the request data below, make the following replacements:

    • RESOURCE_TYPE: The resource type that you want to manage recommendations for. Use the value projects, folders, or organizations.
    • RESOURCE_ID: The ID of the Google Cloud project, folder, or organization that you want to manage recommendations for. Project IDs are alphanumeric strings, like my-project. Folder and organization IDs are numeric, like 123456789012.
    • RECOMMENDATION_ID: The unique identifier for the recommendation. This value appears at the end of the name field in the recommendation. For example, if the name field is projects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f, the recommendation ID is fb927dc1-9695-4436-0000-f0f285007c0f.
    • ETAG: The value of the etag field in the recommendation, such as "dd0686e7136a4cbb". Use backslashes to escape quotes, for example, "\"df7308cca9719dcc\"".
    • 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.

    HTTP method and URL:

    POST https://recommender.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/locations/global/recommenders/google.iam.policy.Recommender/recommendations/RECOMMENDATION_ID:markFailed

    Request JSON body:

    {
      "etag": "ETAG"
      "stateMetadata": {
        "STATE_METADATA"
    }
    

    To send your request, expand one of these options:

    The response shows the recommendation in a FAILED state, as shown in the following example. For clarity, this example omits most fields:

    {
      "description": "This role has not been used during the observation window.",
      "stateInfo": {
        "state": "FAILED",
        "stateMetadata": {
          "reviewedBy": "alice",
          "priority": "high"
        }
      }
      "etag": "\"dd0686e7136a4cbb\"",
      "recommenderSubtype": "REMOVE_ROLE"
    }
    

Viewing, reverting, and restoring changes

After you apply or dismiss a recommendation for a project-level role binding, that action appears in the recommendations history.

To view the recommendations history:

  1. In the Cloud Console, go to the IAM page.

    Go to the IAM page

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

    The Cloud Console shows a list of previous actions on your 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