This page explains how to view, understand, and apply recommendations made by the IAM recommender. The IAM recommender helps you enforce the principle of least privilege by ensuring that members have only the permissions that they actually need.
Before you begin
- Understand the IAM recommender.
- Make sure you have the IAM permissions that you need in order to work with the IAM recommender.
- Review the IAM recommender best practices.
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
In the Cloud Console, go to the IAM page.
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, 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.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 IAM recommender always suggests a set of predefined roles that you can apply.
In some cases, the 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.
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.
(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.
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 IAM recommender 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.
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 \
--project=project-id \
--format=format
Replace the following values:
project-id
: The project identifier, such asproject-123
.format
: The format of the response. Usejson
oryaml
.
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 IAM recommender 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": {
"revokedIamPermissionsCount": 708
}
},
"stateInfo": {
"state": "ACTIVE"
}
}
]
Review each recommendation carefully, and consider how it will change the member's access to Google Cloud resources.
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 theinsight
field. In the preceding example, the insight ID is279ef748-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:
Use the
gcloud recommender recommendations mark-claimed
command to change the recommendation's state toCLAIMED,
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 thename
field in the recommendation. In the example shown above, the ID isfb927dc1-9695-4436-0000-f0f285007c0f
. -
project-id
: The project identifier, such asproject-123
. -
format
: The format of the response. Usejson
oryaml
. -
etag
: The value of theetag
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 thestateInfo.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" } } } ]
-
Get the IAM policy for the project, then modify the policy so that it reflects the recommendation.
Update the recommendation's state to
SUCCEEDED
, if you were able to apply the recommendation, orFAILED
, 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
: Usemark-succeeded
, if you were able to apply the recommendation, ormark-failed
, if you could not apply the recommendation. -
recommendation-id
: The unique identifier for the recommendation. This value appears at the end of thename
field in the recommendation. In the example shown above, the ID isfb927dc1-9695-4436-0000-f0f285007c0f
. -
project-id
: The project identifier, such asproject-123
. -
format
: The format of the response. Usejson
oryaml
. -
etag
: The value of theetag
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 thestateInfo.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
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:
project-id
: Your Google Cloud project ID.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 thestateInfo.state
field. For example,stateInfo.state:"DISMISSED"
orstateInfo.state:"FAILED"
.
HTTP method and URL:
GET https://recommender.googleapis.com/v1/projects/project-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 has not used any permissions from the Compute Admin role
(roles/compute.admin
) in the past 90 days. As a result,
the IAM 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": { "revokedIamPermissionsCount": 708 } }, "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" } ] }
Review each recommendation carefully, and consider how it will change the member's access to Google Cloud resources.
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 theinsight
field. In the preceding example, the insight ID is279ef748-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:
Mark the recommendation as
CLAIMED
:The Recommender API's
recommendations.markClaimed
method marks a recommendation asCLAIMED
, which prevents the recommendation from changing while you apply it.Before using any of the request data below, make the following replacements:
project-id
: Your Google Cloud project ID.recommendation-id
: The unique identifier for the recommendation. This value appears at the end of thename
field in the recommendation. For example, if thename
field isprojects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f
, the recommendation ID isfb927dc1-9695-4436-0000-f0f285007c0f
.etag
: The value of theetag
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 thestateInfo.stateMetadata
field in the recommendation.
HTTP method and URL:
POST https://recommender.googleapis.com/v1/projects/project-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" }
Get the IAM policy for the project, then modify the policy so that it reflects the recommendation.
Update the recommendation's state to
SUCCEEDED
, if you were able to apply the recommendation, orFAILED
, if you could not apply the recommendation:SUCCEEDED
The Recommender API's
recommendations.markSucceeded
method marks a recommendation asSUCCEEDED
, indicating that you were able to apply it.Before using any of the request data below, make the following replacements:
project-id
: Your Google Cloud project ID.recommendation-id
: The unique identifier for the recommendation. This value appears at the end of thename
field in the recommendation. For example, if thename
field isprojects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f
, the recommendation ID isfb927dc1-9695-4436-0000-f0f285007c0f
.etag
: The value of theetag
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 thestateInfo.stateMetadata
field in the recommendation.
HTTP method and URL:
POST https://recommender.googleapis.com/v1/projects/project-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 asFAILED
, indicating that you were not able to apply it.Before using any of the request data below, make the following replacements:
project-id
: Your Google Cloud project ID.recommendation-id
: The unique identifier for the recommendation. This value appears at the end of thename
field in the recommendation. For example, if thename
field isprojects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f
, the recommendation ID isfb927dc1-9695-4436-0000-f0f285007c0f
.etag
: The value of theetag
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 thestateInfo.stateMetadata
field in the recommendation.
HTTP method and URL:
POST https://recommender.googleapis.com/v1/projects/project-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, that action appears in the recommendations history. To view the recommendations history:
In the Cloud Console, go to the IAM page.
Near the top of the screen, click Recommendations history.
The Cloud Console shows a list of previous actions on your IAM recommendations.
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:
(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
- Read the IAM recommender overview.
- Learn more about Recommender.
- Understand best practices for using the IAM recommender.
- Learn how to use IAM insights.
- Understand predefined roles and custom roles in IAM.