Enforce least privilege with recommendations

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 project-level role grants with the permissions that each member used during the past 90 days. If you grant a project-level 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. 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 level, and that have existed for at least 90 days. It does not evaluate any of the following items:

  • Role grants made at the folder or organization level
  • 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
  • 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.list method in the IAM REST API requires the iam.roles.list permission. When you call the roles.list method, you use the iam.roles.list permission.

    Similarly, when you call the testIamPermissions method 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 compute.instances.get permission.

    As a result, when you edit a VM instance in the Cloud Console, you use the compute.instances.get permission.

Machine learning

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.

Insights

Recommendations are created based on one or more IAM insights. IAM policy insights are ML-based findings about permission usage within your project.

Some insights provide evidence for recommendations. However, you can use insights independently from recommendations. To learn how to use insights, see Using insights.

Audit logging

When you apply or dismiss a recommendation, IAM recommender creates a log entry. You can view these entries in the IAM recommender, or you can view them in your Google Cloud audit logs.

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.

Reviewing recommendations

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.

  • 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 the recommender has determined through 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.

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.

In some cases, 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:

  • 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

The user my-user@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, my-user@example.com hasn't viewed any resources.

Therefore, the IAM recommender suggests that you revoke the Browser role from my-user@example.com:

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

The user my-user@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, my-user@example.com used only 4 of those permissions.

Therefore, the IAM recommender suggests that you create a custom role that includes only the permissions that my-user@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 (roles/storage.objectAdmin), 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 icon to identify these additional permissions. In this example, the resourcemanager.projects.get permission was recommended based on machine learning:

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. 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 members of your project to have few or no recommendations. There are several reasons why a member might not have a recommendation for a specific role:

  • 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.

  • 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. To ensure that Google-managed service accounts can access your resources when necessary, the IAM recommender does not analyze any roles that are granted to a Google-managed service account.

  • 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.

  • 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.

  • 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.

Required IAM permissions

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

View recommendations

To view recommendations from the IAM recommender, you must have the following permissions for the project you are viewing:

  • iam.roles.get
  • iam.roles.list
  • recommender.iamPolicyRecommendations.get
  • recommender.iamPolicyRecommendations.list
  • resourcemanager.projects.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 from the IAM recommender, you must have the following permissions for the project you are managing:

  • iam.roles.get
  • iam.roles.list
  • recommender.iamPolicyRecommendations.get
  • recommender.iamPolicyRecommendations.list
  • recommender.iamPolicyRecommendations.update
  • resourcemanager.projects.getIamPolicy
  • resourcemanager.projects.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)
  • Project IAM Admin (roles/resourcemanager.projectIamAdmin)

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.

What's next