Enforce least privilege with recommendations

This page provides an overview of 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.

How the Cloud IAM recommender works

Cloud 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 Cloud IAM recommender is likely to recommend that you revoke the role. If necessary, the Cloud IAM recommender also recommends less permissive roles as a replacement. The Cloud IAM recommender never suggests a change that increases a member's level of access.

The Cloud 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 Cloud IAM recommender does not apply recommendations automatically. Instead, you must review each recommendation, then either apply or dismiss the recommendation.

The Cloud 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 Cloud IAM

Permissions used by each member

To create recommendations, the Cloud 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 Cloud 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 Cloud IAM recommender uses a machine learning (ML) model.

The Cloud 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: Cloud 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 Cloud 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.

Audit logging

When you apply or dismiss a recommendation, Cloud IAM recommender creates a log entry. You can view these entries in the Cloud 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 Cloud IAM. For example, Cloud Storage provides access control lists (ACLs), and Google Kubernetes Engine (GKE) supports Kubernetes role-based access control (RBAC).

The Cloud IAM recommender analyzes only Cloud 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 Cloud 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.

  • Green with a plus sign: Permissions that are implicitly included in the member's current role, but must be explicitly included in the recommended roles to maintain the current level of access.

    This type of permission will appear only when replacing a primitive role. Some Google Cloud services, including Cloud Storage and BigQuery, implicitly provide additional permissions to any member that has a primitive role. If a member has used these implicit permissions in the past 90 days, the recommended roles will include the equivalent explicit permissions so that the member retains their existing access. The Cloud IAM recommender never adds permissions that the member does not already have.

  • 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 Cloud IAM recommender suggests replacements for an existing role, it always suggests 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 Cloud 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 Cloud 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 Cloud 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 fuyo@example.com was granted a custom role on a project. The custom role includes one permission, iam.serviceAccounts.actAs, which gives fuyo@example.com the ability to act as a service account. However, during the past 90 days, fuyo@example.com hasn't acted as a service account in that project.

Therefore, the Cloud IAM recommender suggests that you revoke the custom role from fuyo@example.com:

Replace an existing role

A service account was granted the Owner role (roles/owner) on a project. This primitive role includes more than 2,500 permissions and grants almost unlimited access to a project. However, during the past 90 days, the service account has used only a few hundred permissions.

Therefore, the Cloud IAM recommender suggests that you revoke the Owner role and replace it with a combination of four other roles, which removes thousands of overgranted permissions:

Create a custom role

The user nelson@example.com was granted the BigQuery Data Viewer role (roles/bigquery.dataViewer) on a project. The role includes more than 10 permissions, but during the past 90 days, nelson@example.com used only 3 of those permissions.

Therefore, the Cloud IAM recommender suggests that you create a custom role that includes only the permissions that nelson@example.com actually used:

The Cloud IAM recommender also suggests another option, which is to replace the existing role with the BigQuery Metadata Viewer role (roles/bigquery.metadataViewer). This predefined role includes slightly fewer permissions than the BigQuery Data Viewer role.

Role replacement with permissions suggested by machine learning

A service account was granted the Editor role (roles/editor) on a project. This primitive role includes more than 2,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 Cloud 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 overgranted 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 Cloud IAM recommender predicts that the service account will need these permissions in the future.

The Cloud 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.

When recommendations are not available, the Cloud Console shows a Recommendation not available icon. To find out why, hold the pointer over the icon.

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 Cloud 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 Cloud 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 Cloud 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 Cloud 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 Cloud 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 Cloud IAM recommender does not make recommendations for these role bindings.

  • No other member has the Owner primitive 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 Cloud 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 Cloud 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 log. Dismissed recommendations are available until the recommendation becomes obsolete. Reverted recommendations are available for 90 days.

Required Cloud IAM permissions

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

View recommendations

To view recommendations from the Cloud 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 Cloud 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