This page provides an overview of 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.
How the IAM recommender works
IAM uses Recommender to compare role grants with the permissions that each member used during the past 90 days. If you grant a role to a member, and the member does not use all of that role's permissions, then the IAM recommender is likely to recommend that you revoke the role. If necessary, the IAM recommender also recommends less permissive roles as a replacement. This suggested replacement could be a new custom role, an existing custom role, or one or more predefined roles. Except in the case of recommendations for Google-managed service accounts, the IAM recommender never suggests a change that increases a member's level of access.
The IAM recommender also uses machine learning to identify permissions in a member's current role that the member is likely to need in the future, even if the member did not use those permissions in the past 90 days.
The IAM recommender does not apply recommendations automatically. Instead, you must review each recommendation, then either apply or dismiss the recommendation.
The IAM recommender evaluates only role grants that were made at the project, folder, or organization level, and that have existed for at least 90 days. It does not evaluate any of the following items:
- Role grants made below the project level; that is, role grants on service-specific resources within a project
- Conditional role grants
- Role grants for Google-managed service accounts for roles other than Owner, Editor, and Viewer
- Access controls that are separate from IAM
Permissions used by each member
To create recommendations, the IAM recommender identifies the permissions that each member used in the past 90 days. There are a few ways in which a member can use a permission:
Directly, by calling an API that requires the permission
For example, the
roles.listmethod in the IAM REST API requires the
iam.roles.listpermission. When you call the
roles.listmethod, you use the
Similarly, when you call the
testIamPermissionsmethod for a resource, you effectively use all of the permissions that you are testing.
Indirectly, by using the Google Cloud Console to work with Google Cloud resources
For example, in the Cloud Console, you can edit a Compute Engine virtual machine (VM) instance, which requires different permissions based on which settings you change. However, the Cloud Console also displays the existing settings, which requires the
As a result, when you edit a VM instance in the Cloud Console, you use the
In some cases, a member is likely to need certain permissions that are included in their current roles, but that they haven't used in the last 90 days. To identify these permissions, the IAM recommender uses a machine learning (ML) model.
The IAM recommender's machine learning model is trained on multiple sets of signals:
Common co-occurrence patterns in the observed history: The fact that a user used permission A, B, and C in the past provides a hint that A, B, and C might be related in some way and that they are needed together to carry out a task on Google Cloud. If the ML model observes this pattern frequently enough, the next time a different user uses permission A and B, the model will suggest that the user might need permission C as well.
Domain knowledge as encoded in the role definitions: IAM provides hundreds of different predefined roles that are service-specific. If a predefined role contains a set of permissions, it is a strong signal that those permissions should be granted together.
In addition to these signals, the model also uses word embedding to calculate how semantically similar the permissions are. Semantically similar permissions will be "close" to each other after embedding, and more likely to be granted together. For example, bigquery.datasets.get and bigquery.tables.list will be very close to each other after embedding.
All data used in the IAM recommender machine learning pipeline has k-anonymity, meaning that individuals in the anonymized data set cannot be re-identified. To achieve this level of anonymity, we drop all personally identifiable information (PII) such as the user ID related to each permission usage pattern. Then we drop all usage patterns that do not show up frequently enough across Google Cloud. The global model is trained on this anonymized data.
The global model can be further customized for each organization using federated learning, a machine learning process that trains machine learning models without exporting data.
Recommendations are assigned priority levels based their perceived urgency.
Priority levels range from
P0 (highest priority) to
P4 (lowest priority).
IAM recommendations can have priority levels of either
P4. Recommendations for role bindings with basic roles (Owner, Editor, and
Viewer) have a priority of
P2. These recommendations have a high priority
because basic roles are highly permissive, and applying recommendations for
these roles can greatly reduce your over-granted permissions. All other
recommendations have a priority of
You can see your recommendations' priority levels by listing your
recommendations using the
gcloud tool or REST
The recommendations that the IAM recommender generates are split into
several different subtypes. If you're using the
gcloud tool or the
REST API, you can use these subtypes to filter your recommendations.
|REMOVE_ROLE||A recommendation to remove the member's role.|
|REPLACE_ROLE||A recommendation to replace the member's role with a less permissive role.|
|SERVICE_AGENT_WITH_DEFAULT_ROLE||A recommendation to replace a Google-managed service account's Owner, Editor, or Viewer role with the role that was automatically granted to the service account when it was created. For more information, see Recommendations for Google-managed service accounts.|
|SERVICE_AGENT_WITHOUT_DEFAULT_ROLE||A recommendation to replace a Google-managed service account's Owner, Editor, or Viewer role with a less permissive role. For more information, see Recommendations for Google-managed service accounts.|
Recommendations for Google-managed service accounts
For Google-managed service accounts, the IAM recommender only provides recommendations for role bindings with basic roles (Owner, Editor, or Viewer). These recommendations are divided into two recommendation subtypes.
On creation, some Google-managed service accounts are automatically granted a
service agent role to ensure that your Google Cloud
services work properly. If you replace this role with a basic role (Owner,
Editor, or Viewer), the IAM recommender might suggest that you
restore the original service agent role to remove excess permissions, even if
the service agent role has permissions that are not in the basic role. These
recommendations have the subtype
SERVICE_AGENT_WITH_DEFAULT_ROLE. They help
you safely remove excess permissions while ensuring that all Google Cloud
services work properly.
SERVICE_AGENT_WITH_DEFAULT_ROLE recommendations are the only type of
recommendation that might suggest roles with permissions not in the current
If a Google-managed service account is not automatically granted a role on
creation, recommendations for the service account are based exclusively on the
permissions that the service account uses. These recommendations have the
Recommendations are created based on one or more IAM insights. IAM policy insights are ML-based findings about permission usage.
Unlike recommendations, IAM policy insights can be generated for role bindings that have existed for less than 90 days.
Some insights provide evidence for recommendations. However, you can use insights independently from recommendations. To learn how to use insights, see Using insights.
Insights are assigned severity levels based their perceived urgency. Severity
levels can be
IAM policy insights can have a severity level of
Insights for role bindings with basic roles (Owner, Editor, and Viewer) have a
severity level of
HIGH. These insights have a high severity because basic
roles are highly permissive, and addressing insights for these roles can greatly
reduce your over-granted permissions. All other insights have a severity level
Other types of access controls
Some Google Cloud services provide access controls that are separate from IAM. For example, Cloud Storage provides access control lists (ACLs), and Google Kubernetes Engine (GKE) supports Kubernetes role-based access control (RBAC).
The IAM recommender analyzes only IAM access controls. If you use other types of access controls, take extra care when you review your recommendations, and consider how those access controls relate to your IAM policies.
When you click on a recommendation in the Cloud Console, the Cloud Console shows 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 recommendations for Google-managed service accounts.: Permissions that are not in the member's current role, but are in the recommended roles. This type of permission appears only in
Blue with a Machine learning icon machine learning that they are likely to need those permissions in the future. This page shows an example of a scenario where you might see a permission that was suggested by ML.: 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 the recommender has determined through
Recommendations for custom roles
When the IAM recommender suggests replacements for a role, it always suggests an existing custom role, or one or more predefined roles, that appear to be a better fit for the member's needs.
For some project-level recommendations, it also provides the option to create a new custom role that includes only the recommended permissions. You can modify the custom role recommendation by adding or removing permissions.
If you want to enforce the principle of least privilege as strictly as possible, choose the new custom role. The IAM recommender creates the custom role at the project level. You are responsible for maintaining and updating the custom roles for your projects.
If you prefer to use a Google-managed role, choose the predefined role. Google Cloud updates these roles regularly by adding or removing permissions. To be notified about these updates, subscribe to the news feed for the permissions change log. When you choose the predefined role, the member will continue to have at least a few permissions, and potentially a large number of permissions, that they have not used.
The IAM recommender does not recommend new custom roles in the following cases:
- The recommendation is for a folder-level or organization-level role.
- Your organization already has 100 or more custom roles.
- Your project already has 25 or more custom roles.
Also, the IAM recommender recommends no more than 5 new custom roles per day in each project, and no more than 15 new custom roles across the entire organization.
Examples of role recommendations
The following examples show the types of recommendations that you can receive.
Revoke an existing role
email@example.com was granted the Browser role on a project.
The Browser role includes six permissions that allow the user to view resources
in the project. However, during the past 90 days,
firstname.lastname@example.org hasn't viewed any resources.
Therefore, the IAM recommender suggests that you revoke the Browser
Replace an existing role
A service account was granted the Editor role (
roles/editor) on a project.
This basic role includes more than 3,000 permissions and grants extensive access
to the project. However, during the past 90 days, the
service account has only used a few of those permissions.
Therefore, the IAM recommender suggests that you revoke the Editor role and replace it with a combination of two other roles, which removes thousands of excess permissions:
Create a custom role
email@example.com was granted the Cloud Trace Admin role
roles/cloudtrace.admin) on a project. The role includes more than 10
permissions, but during the past 90 days,
firstname.lastname@example.org used only 4 of those permissions.
Therefore, the IAM recommender suggests that you create a custom role
that includes only the permissions that
email@example.com actually used:
The IAM recommender also suggests another option, which is to replace
the existing role with the Cloud Trace User role
roles/cloudtrace.user). This predefined role includes slightly fewer
permissions than the Cloud Trace Admin role.
Role replacement with permissions suggested by machine learning
A service account was granted the Editor role (
roles/editor) on a project.
This basic role includes more than 3,000 permissions and grants extensive access
to a project. However, during the past 90 days, the service
account has used fewer than 10 permissions.
The IAM recommender suggests that you revoke the Editor role and
replace it with the Storage Object Admin role (
which grants full control of objects in a Cloud Storage bucket. This change
removes thousands of excess permissions.
This role includes several permissions from the Editor role that the service account did not use in the past 90 days. However, using machine learning, the IAM recommender predicts that the service account will need these permissions in the future.
The IAM recommender uses a Machine learning
identify these additional permissions. In this example, the
resourcemanager.projects.get permission was recommended based on machine
Availability of recommendations
In the Cloud Console, the IAM page shows all of the members of your project and lists the roles that each member has on the project. It also indicates whether a recommendation is available for each role.
When recommendations are available, the Cloud Console shows a Recommendation available icon in the Analyzed permissions column alongside the member's permission usage. This icon indicates that the member has permissions that they probably do not need. Click the icon to review and apply the recommendation.
It's normal for some roles to not have recommendations. In these cases, the Analyzed permissions column shows either aicon, or the member's permission usage with no Recommendation available icon:
The Analyzed permissions column shows aicon in the following cases:
There is not enough usage data for the member. If the IAM recommender does not have enough information about how the member uses Google Cloud, it cannot make recommendations for that member's roles.
You might see recommendations for the member in the future, after the IAM recommender collects more data.
The member is a Google-managed service account, and the role is not a basic role. For Google-managed service accounts, the IAM recommender provides recommendations only for basic roles (Owner, Editor, or Viewer). It does not analyze any other role bindings for Google-managed service accounts.
The role binding is conditional. If the role binding includes a condition, then the role is granted only if certain permissions are met. The IAM recommender does not make recommendations for these role bindings.
The current recommendation for the role binding was dismissed, or applied and then reverted. If you dismiss a recommendation to change a member's role, or if you apply a recommendation and then revert it, the Cloud Console does not display that recommendation again.
In the future, if the IAM recommender makes a new recommendation to change the member's role, the Cloud Console shows the new recommendation even if you dismissed or reverted the previous recommendation.
You can view dismissed and reverted recommendations in the recommendations history. Dismissed recommendations are available until the recommendation becomes obsolete. Reverted recommendations are available for 90 days.
The Analyzed permissions column shows the member's permission usage with no Recommendation available icon in the following cases:
There are no predefined IAM roles that are more appropriate than the current role. If a member already has a predefined role that minimizes their permissions, or that includes fewer permissions than other predefined roles, then the IAM recommender cannot recommend a different predefined role.
You might be able to reduce the member's permissions by creating a custom role for the member.
No other member has the Owner basic role for the project. At least one member must have the Owner role (
roles/owner) for each project. If only one member has this role, the IAM recommender will not recommend that you revoke or replace the role.
- Understand best practices for using the IAM recommender.
- Review and apply your IAM recommendations.
- Learn more about Recommender.
- Understand predefined roles and custom roles in IAM.
- Learn about IAM policies, which bind roles to members.