Enforce least privilege with role recommendations

Role recommendations help you identify and remove excess permissions from your members, improving your resources' security configurations.

Overview of role recommendations

Role recommendations are one of the types of recommendations that Recommender generates.

Each role recommendation suggests that you remove or replace a role that gives your members excess permissions. At scale, these recommendations help you enforce the principle of least privilege by ensuring that members have only the permissions that they actually need.

Recommender identifies excess permissions using policy insights. Policy insights are machine learning-based findings about permission usage in your project, folder, or organization.

How policy insights are generated

Recommender generates policy insights by comparing the permissions that each member used during the past 90 days with the total permissions the member has. 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.

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. For more information, see Machine learning for policy insights on this page.

Policy insights are not generated for all IAM role bindings. For more information about why a role binding might not have a policy insight, see Availability on this page.

To learn how to manage policy insights, see Managing policy insights.

Machine learning for policy insights

In some cases, a member is likely to need certain permissions that are included in their current roles, but that they haven't used recently. To identify these permissions, Recommender uses a machine learning (ML) model when generating policy insights.

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

How role recommendations are generated

If a policy insight indicates that a member does not need all of the permissions in their role, Recommender assesses the role to determine if it could be revoked, or if there is another role that's a better fit. If the role can be revoked, Recommender generates a role recommendation to revoke the role. If there is another role that's a better fit, Recommender generates a role recommendation to replace the role with a suggested role. This suggested role 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, a role recommendation never suggests a change that increases a member's level of access.

Role recommendations are generated based on only IAM access controls. They do not take into account other kinds of access controls, like access control lists (ACLs) and Kubernetes role-based access control (RBAC). 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.

Additionally, role recommendations are not generated for all IAM role bindings. For more information about why a role binding might not have a role recommendation, see Availability on this page.

New custom roles in role recommendations

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

If Recommender identifies a common permission usage pattern in your organization that does not map to an existing predefined or custom role, it might also recommend that you create a new project-level custom role. This custom role 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. 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.

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

Availability

Policy insights and role recommendations are not generated for every role binding. Read the following sections to understand the role bindings that policy insights and recommendations are generated for.

Policy insight availability

For Recommender to generate a policy insight for a role binding, the following must be true:

  • The role binding must exist at the project, folder, or organization level. Recommender does not generate policy insights for roles that are granted on service-specific resources within a project.
  • The role binding must not have a condition. Recommender does not generate policy insights for conditional role bindings.

It can take up to 10 days for Recommender to generate policy insights for a new role binding.

Role recommendation availability

For Recommender to generate a role recommendation for a role binding, the following must be true:

  • The role binding must have a policy insight associated with it. This policy insight serves as the basis for the recommendation.
  • The role binding must be older than 90 days. This ensures that Recommender has enough usage data to make a recommendation.
  • If the member in the role binding is a Google-managed service account, the role binding must be Owner, Editor, or Viewer. Recommender does not generate role recommendations for Google-managed service accounts with other roles. For more details, see Role recommendations for Google-managed service accounts.

If a role binding does not have any insights or has not existed for 90 days, the Analyzed permissions column in the Cloud Console shows a icon.

There are some cases where Recommender does not generate role recommendations for a role binding that is older than 90 days and has an insight associated with it. This can happen for the following reasons:

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

  • The member is a Google-managed service account, and the role is not a basic role. Recommender only generates role recommendations for Google-managed service accounts if the service account has a basic role (Owner, Editor, or Viewer). For more details, see Role recommendations for Google-managed service accounts.

  • 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, Recommender will not recommend that you revoke or replace the role.

In these cases, the Analyzed permissions column in the Cloud Console shows the member's permission usage, but does not have a Recommendation available icon.

Priority and severity

Recommendation priority and insight severity help you understand the urgency of a recommendation or insight and prioritize accordingly.

Role recommendation priority

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 P2 or 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 P4.

You can see your recommendations' priority levels by listing your recommendations using the gcloud tool or REST API.

Policy insight severity

Insights are assigned severity levels based their perceived urgency. Severity levels can be LOW, MEDIUM, HIGH, or CRITICAL.

Policy insights can have a severity level of LOW or HIGH. 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 of LOW.

How role recommendations are applied

Recommender does not apply recommendations automatically. Instead, you must review your recommendations and decide whether to apply or dismiss them. To learn how to review, apply, and dismiss role recommendations, see Reviewing and applying recommendations.

Audit logging

When you apply or dismiss a recommendation, Recommender creates a log entry. You can view these entries in the project's recommendations history, or you can view them in your Google Cloud audit logs.

Role recommendation subtypes

Role recommendations are split into several different subtypes based on the action they recommend. If you use the gcloud tool or the REST API, you can use these subtypes to filter your recommendations.

Subtype Description
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. The recommended replacement could be a new custom role, an existing custom role, or one or more predefined roles.
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.

Role recommendations for Google-managed service accounts

For Google-managed service accounts, Recommender only provides recommendations for role bindings with basic roles (Owner, Editor, or Viewer).

Recommendations for Google-managed service accounts are divided into two recommendation subtypes.

SERVICE_AGENT_WITH_DEFAULT_ROLE

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), a role recommendation 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 role.

SERVICE_AGENT_WITHOUT_DEFAULT_ROLE

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 subtype SERVICE_AGENT_WITHOUT_DEFAULT_ROLE.

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, Recommender generates a role recommendation suggesting 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, Recommender generates a role recommendation suggesting 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 a policy insight indicates that, during the past 90 days, my-user@example.com used only 4 of those permissions.

Therefore, Recommender generates a role recommendation suggesting that you create a custom role that includes only the permissions that my-user@example.com actually used:

The role recommendation 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, a policy insight indicates that, during the past 90 days, the service account has used fewer than 10 permissions.

The policy insight also highlights several permissions that service account is likely to need in the future. Recommender identified these permissions using machine learning.

Recommender generates a role recommendation suggesting 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, while still including both the permissions the service account used and the permissions that the service account is likely to need in the future.

The Recommender uses a Machine learning icon to identify permissions that were added based on Recommender's machine learning rather than on permission usage. In this example, the resourcemanager.projects.get permission was recommended based on machine learning:

What's next