Role recommendations help you identify and remove excess permissions from your principals, improving your resources' security configurations.
Overview of role recommendations
Role recommendations are generated by the IAM recommender. The IAM recommender is one of the recommenders that Recommender offers.
Each role recommendation suggests that you remove or replace a role that gives your principals excess permissions. At scale, these recommendations help you enforce the principle of least privilege by ensuring that principals have only the permissions that they actually need.
The IAM recommender identifies excess permissions using policy insights. Policy insights are ML-based findings about a principal's permission usage.
Some recommendations are also associated with lateral movement insights. These insights identify roles that allow service accounts in one project to impersonate service accounts in another project. For more information, see How lateral movement insights are generated.
How policy insights are generated
Policy insights highlight the permissions in a principal's roles that the principal isn't using.
The IAM recommender generates policy insights by comparing a principal's total number of permissions with the permissions that the principal used in the last 90 days. If the role was granted fewer than 90 days ago, the IAM recommender looks at the principal's permission usage in the time since the principal was granted the role.
There are a few ways in which a principal 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 theiam.roles.list
permission. When you call theroles.list
method, you use theiam.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 Google Cloud console, you can edit a Compute Engine virtual machine (VM) instance, which requires different permissions based on which settings you change. However, the Google 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 Google Cloud console, you use the
compute.instances.get
permission.
The IAM recommender also uses machine learning to identify permissions in a principal's current role that the principal is likely to need in the future, even if the principal did not use those permissions recently. For more information, see Machine learning for policy insights on this page.
Policy insights aren't generated for all IAM roles that are granted to principals. For more information about why a role might not have a policy insight, see Availability on this page.
To learn how to manage policy insights, see Manage policy insights for projects, folders, and organizations or Manage policy insights for Cloud Storage buckets.
Machine learning for policy insights
In some cases, a principal is likely to need certain permissions that are included in their current roles, but that they haven't used recently. To identify these permissions, the IAM 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 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.
How role recommendations are generated
If a policy insight indicates that a principal does not need all of the permissions in their role, the IAM 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, the IAM recommender generates a role recommendation to revoke the role. If there is another role that's a better fit, the IAM 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 service agents, a role recommendation never suggests a change that increases a principal'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 allow policies.
Additionally, role recommendations aren't generated for all IAM roles that are granted to principals. For more information about why a role might not have a role recommendation, see Availability on this page.
Observation period
A role recommendation's observation period is the number of days of permission usage data that the recommendation is based on.
The maximum observation period for role recommendations is 90 days. This means that the IAM recommender uses, at most, the most recent 90 days of permission usage data to generate role recommendations.
The IAM recommender also doesn't start generating role recommendations until it has a certain number of days of permission usage data. This duration is called the minimum observation period. By default, the minimum observation period is 90 days, but, for project-level role recommendations, you can manually set it to 30 days or 60 days. For details, see Configure role recommendation generation. If you set the minimum observation period to fewer than 90 days, you'll get recommendations sooner, but the accuracy of the recommendations might be affected.
If it's been longer than the minimum observation period but less than 90 days since the role was granted, the observation period is the length of time since the role was granted.
New custom roles in role recommendations
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 principal's needs.
If the IAM 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. 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 role that is maintained for you, 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 principal continues to have at least a few permissions, and potentially a large number of permissions, that they have not used.
The IAM recommender recommends new custom roles only for roles granted on a project. It doesn't recommend new custom roles for roles granted on other resources, like folders or organizations.
Additionally, the IAM recommender doesn't 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.
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.
How lateral movement insights are generated
Lateral movement is when a service account in one project has permission to impersonate a service account in another project. For example, a service account might have been created in project A, but have permissions to impersonate a service account in project B.
These permissions can result in a chain of impersonations across projects that gives principals unintended access to resources. For example, if a principal impersonates the service account in project A, they can use that service account to impersonate the service account in project B. If the service account in project B has permission to impersonate other service accounts in other projects in your organization, the principal can continue to use service account impersonation to move from project to project, gaining permissions as they go.
The IAM recommender generates lateral movement insights by identifying roles that fit the following criteria:
- The principal that was granted the role is a service account that was not created in the project.
The role includes one of the following permissions, which allow a principal to impersonate a service account:
iam.serviceAccounts.actAs
iam.serviceAccounts.getAccessToken
iam.serviceAccounts.getOpenIdToken
iam.serviceAccounts.implicitDelegation
iam.serviceAccounts.signBlob
iam.serviceAccounts.signJwt
If a role fits these criteria, the IAM recommender generates a lateral movement insight for the role. This insight contains information about the service account's impersonation abilities, including which service accounts it can impersonate and whether it used any impersonation permissions in the last 90 days.
The IAM recommender doesn't use lateral movement insights on their own to generate new role recommendations. This is because, if a service account is using its impersonation permissions, the IAM recommender can't safely suggest removing them. However, if a role recommendation suggests removing these permissions because they aren't being used, the IAM recommender will link the lateral movement insight to that recommendation. This linkage helps you prioritize role recommendations for service accounts that have powerful, unused impersonation permissions across projects.
To learn how to manage lateral movement insights, see Manage lateral movement insights.
Availability
Policy insights, lateral movement insights, and role recommendations aren't generated for all roles that are granted to principals. Read the following sections to understand the roles that policy insights, lateral movement insights, and recommendations are generated for.
Policy insight availability
For the IAM recommender to generate a policy insight for a role, the following must be true:
The IAM allow policy that grants the role must be attached to one of the following resources:
- Cloud Storage bucket
- BigQuery dataset
- Project
- Folder
- Organization
The IAM recommender only generates policy insights for roles that are granted on these resources.
The role binding that grants the role must not have a condition. The IAM recommender does not generate policy insights for conditional role bindings.
The principal that's granted the role needs to be one of the following principal types:
- User
- Service account
- Group
allUsers
allAuthenticatedUsers
- Cloud Storage convenience values
- BigQuery special group membership
One of the following types of federated identities:
- All identities in a workload identity pool
- Single identity in a workload identity pool
- All identities in a workforce identity pool
- Single identity in a workforce identity pool
All Google Kubernetes Engine Pods that use a specific Kubernetes service account
For details about the identifier format for each principal type, see Principal identifiers.
It can take up to 10 days for the IAM recommender to generate policy insights for a newly granted role.
Existing policy insights are refreshed daily based on your recent permission usage. However, the data that the policy insights are based on typically lags up to two days behind your actual usage.
Lateral movement insight availability
Lateral movement insights are generated for roles that are granted on the following resources:
- Organizations
- Folders
- Projects
- Service accounts
Role recommendation availability
For the IAM recommender to generate a role recommendation for a role, the following must be true:
- The role must have a policy insight associated with it. This policy insight serves as the basis for the recommendation.
- It must have been longer than the minimum observation period since the role was granted. This ensures that the IAM recommender has enough usage data to make a recommendation. By default, the minimum observation period is 90 days, but you can manually set it to 30 days or 60 days. For details, see Configure role recommendation generation.
- If the principal that's granted the role is a service agent, the role must be Owner, Editor, or Viewer. The IAM recommender doesn't generate role recommendations for service agents with other roles. For more details, see Role recommendations for service agents.
If a role was granted too recently or doesn't have any insights, the Analyzed permissions column in the Google Cloud console shows a
icon.There are some cases where the IAM recommender doesn't generate role recommendations for a role, even though enough time has passed and the role 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 principal 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 principal's permissions by creating a custom role for the principal.
The principal is a service agent, and the role is not a basic role. The IAM recommender only generates role recommendations for service agents that have a basic role (Owner, Editor, or Viewer). For more details, see Role recommendations for service agents.
No other principal has the Owner basic role for the project. At least one principal must have the Owner role (
roles/owner
) for each project. If only one principal has this role, the IAM recommender will not recommend that you revoke or replace the role.
In these cases, the Analyzed permissions column in the Google Cloud console shows the principal's permission usage, but does not have a Recommendation available
icon.Existing role recommendations are refreshed daily based on your recent permission usage. However, the data that the role recommendations are based on typically lags up to two days behind your actual usage.
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).
A role recommendation's priority depends on the role that the recommendation is for:
Recommendation details | Priority | Explanation |
---|---|---|
Recommendations for roles that grant public access to Cloud Storage buckets | P1 |
Publicly accessible buckets can be accessed by anyone on the internet. Removing public access gives you more control over your data. |
Recommendations for roles that grant public access to BigQuery datasets | P1 |
Publicly accessible datasets can be accessed by anyone on the internet. Removing public access gives you more control over your data. |
Recommendations for basic roles (Owner, Editor, and Viewer) that are granted on a project, folder, or organization | P2 |
Basic roles are highly permissive, and applying recommendations for these roles can greatly reduce excess permissions. |
Recommendations that do not grant public access or basic roles | P4 |
Although these recommendations help you reduce excess permissions, they don't remove public access or highly permissive basic roles, which makes them a lower priority. |
Insight severity
Insights are assigned severity levels based their perceived urgency. Severity
levels can be LOW
, MEDIUM
, HIGH
, or CRITICAL
.
A policy insight's severity depends on the role that the insight is for:
Insight details | Severity | Explanation |
---|---|---|
Insights for roles that grant public access to Cloud Storage buckets | CRITICAL |
Publicly accessible buckets can be accessed by anyone on the internet. Removing public access gives you more control over your data. |
Insights for roles that grant public access to BigQuery datasets | CRITICAL |
Publicly accessible datasets can be accessed by anyone on the internet. Removing public access gives you more control over your data. |
Insights for basic roles (Owner, Editor, and Viewer) that are granted on a project, folder, or organization | HIGH |
Basic roles are highly permissive, and addressing insights for these roles can greatly reduce excess permissions. |
Insights that do not grant public access or basic roles | LOW |
Although these insights highlight excess permissions, they don't involve public access or highly permissive basic roles, which makes them a lower priority. |
All lateral movement insights have a severity of LOW
.
How role recommendations are applied
The IAM 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 one of the following guides:
- Review and apply role recommendations for projects, folders, and organizations
- Review and apply role recommendations for Cloud Storage buckets
- Review and apply role recommendations for BigQuery datasets
Audit logging
When you apply or dismiss a recommendation, the IAM recommender creates a log entry. You can view these entries in your 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 CLI or the REST API, you can use these subtypes to filter your recommendations.
Subtype | Description |
---|---|
REMOVE_ROLE |
A recommendation to remove the principal's project-level, folder-level, or organization-level role. |
REMOVE_ROLE_BIGQUERY_DATASET |
A recommendation to remove the principal's dataset-level role. |
REMOVE_ROLE_STORAGE_BUCKET |
A recommendation to remove the principal's bucket-level role. |
REPLACE_ROLE |
A recommendation to replace the principal's project-level, folder-level, or organization-level role with a less permissive role. The recommended replacement could be an existing custom role or one or more predefined roles. |
REPLACE_ROLE_CUSTOMIZABLE |
A recommendation to replace the principal's role with a new custom role that's less permissive than their current role. |
REPLACE_ROLE_BIGQUERY_DATASET |
A recommendation to replace the principal's dataset-level role with a less permissive role. The recommended replacement could be an existing custom role or one or more predefined roles. |
REPLACE_ROLE_STORAGE_BUCKET |
A recommendation to replace the principal's bucket-level role with a less permissive role. The recommended replacement could be an existing custom role or one or more predefined roles. |
SERVICE_AGENT_WITH_DEFAULT_ROLE |
A recommendation to replace a service agent'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 Role recommendations for service agents. |
SERVICE_AGENT_WITHOUT_DEFAULT_ROLE |
A recommendation to replace a service agent's Owner, Editor, or Viewer role with a less permissive role. For more information, see Role recommendations for service agents. |
Role recommendations for service agents
For service agents, the IAM recommender only provides recommendations for basic roles (Owner, Editor, or Viewer).
Recommendations for service agents are divided into two recommendation subtypes.
SERVICE_AGENT_WITH_DEFAULT_ROLE
On creation, some service agents 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 service agent is not automatically granted a role on creation,
recommendations for the service agent are based exclusively on the permissions
that the service agent uses. These recommendations have the subtype
SERVICE_AGENT_WITHOUT_DEFAULT_ROLE
.
Role recommendations in Security Command Center
If you have the Premium tier of Security Command Center, you can view some subtypes of role recommendations as findings in Security Command Center. Each subtype is associated with a detector:
Recommendation subtype | Finding category |
---|---|
REMOVE_ROLE |
Unused IAM role |
REPLACE_ROLE |
IAM role has excessive permissions |
SERVICE_AGENT_WITH_DEFAULT_ROLE |
Service agent role replaced with basic role |
SERVICE_AGENT_WITHOUT_DEFAULT_ROLE |
Service agent granted basic role |
For more information about viewing role recommendations in Security Command Center, see IAM recommender in the Security Command Center documentation.
Pricing
Project-level, folder-level, and organization-level role recommendations for basic roles are available at no charge.
The following advanced IAM recommender features require an organization-level activation of the premium tier of Security Command Center:
- Recommendations for non-basic roles
- Recommendations for roles granted on resources other than organizations, folders, and projects—for example, recommendations for roles granted on Cloud Storage buckets
- Recommendations that suggest custom roles
- Policy insights
- Lateral movement insights
For more information, see Billing questions.
Examples of role recommendations
The following examples show the types of recommendations that you can receive.
Revoke an existing role
The user [email protected]
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,
[email protected]
hasn't viewed any resources.
Therefore, the IAM recommender generates a role recommendation
suggesting that you revoke the Browser role from [email protected]
:
Console
gcloud
{
"associatedInsights": [
{
"insight": "projects/123456789012/locations/global/insightTypes/google.iam.policy.Insight/insights/86c14538-dcfd-4326-afe5-ee8ac921e06a"
}
],
"content": {
"operationGroups": [
{
"operations": [
{
"action": "remove",
"path": "/iamPolicy/bindings/*/members/*",
"pathFilters": {
"/iamPolicy/bindings/*/condition/expression": "",
"/iamPolicy/bindings/*/members/*": "user:[email protected]",
"/iamPolicy/bindings/*/role": "roles/browser"
},
"resource": "//cloudresourcemanager.googleapis.com/projects/123456789012",
"resourceType": "cloudresourcemanager.googleapis.com/Project"
}
]
}
],
"overview": {
"member": "user:[email protected]",
"removedRole": "roles/browser",
"resource": "//cloudresourcemanager.googleapis.com/projects/123456789012"
}
},
"description": "This role has not been used during the observation window.",
"etag": "\"9fc3241da8bfab51\"",
"lastRefreshTime": "2022-05-20T07:00:00Z",
"name": "projects/123456789012/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fe512038-5455-49g1-8f9c-752e31c8c154",
"primaryImpact": {
"category": "SECURITY",
"securityProjection": {
"details": {
"revokedIamPermissionsCount": 6
}
}
},
"priority": "P4",
"recommenderSubtype": "REMOVE_ROLE",
"stateInfo": {
"state": "ACTIVE"
}
}
REST
{
"name": "projects/123456789012/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fe512038-5455-49g1-8f9c-752e31c8c154",
"description": "This role has not been used during the observation window.",
"lastRefreshTime": "2022-05-20T07:00:00Z",
"primaryImpact": {
"category": "SECURITY",
"securityProjection": {
"details": {
"revokedIamPermissionsCount": 6
}
}
},
"content": {
"operationGroups": [
{
"operations": [
{
"action": "remove",
"resourceType": "cloudresourcemanager.googleapis.com/Project",
"resource": "//cloudresourcemanager.googleapis.com/projects/123456789012",
"path": "/iamPolicy/bindings/*/members/*",
"pathFilters": {
"/iamPolicy/bindings/*/condition/expression": "",
"/iamPolicy/bindings/*/members/*": "user:[email protected]",
"/iamPolicy/bindings/*/role": "roles/browser"
}
}
]
}
],
"overview": {
"resource": "//cloudresourcemanager.googleapis.com/projects/123456789012",
"member": "user:[email protected]",
"removedRole": "roles/browser"
}
},
"stateInfo": {
"state": "ACTIVE"
},
"etag": "\"9fc3241da8bfab51\"",
"recommenderSubtype": "REMOVE_ROLE",
"associatedInsights": [
{
"insight": "projects/123456789012/locations/global/insightTypes/google.iam.policy.Insight/insights/86c14538-dcfd-4326-afe5-ee8ac921e06a"
}
],
"priority": "P4"
}
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 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:
Console
gcloud
{
"associatedInsights": [
{
"insight": "projects/123456789012/locations/global/insightTypes/google.iam.policy.Insight/insights/3d4ef3d6-bdf0-4330-975d-c65cb929c44d"
}
],
"content": {
"operationGroups": [
{
"operations": [
{
"action": "add",
"path": "/iamPolicy/bindings/*/members/-",
"pathFilters": {
"/iamPolicy/bindings/*/condition/expression": "",
"/iamPolicy/bindings/*/role": "roles/iam.serviceAccountUser"
},
"resource": "//cloudresourcemanager.googleapis.com/projects/123456789012",
"resourceType": "cloudresourcemanager.googleapis.com/Project",
"value": "user:[email protected]"
},
{
"action": "add",
"path": "/iamPolicy/bindings/*/members/-",
"pathFilters": {
"/iamPolicy/bindings/*/condition/expression": "",
"/iamPolicy/bindings/*/role": "roles/storage.objectAdmin"
},
"resource": "//cloudresourcemanager.googleapis.com/projects/123456789012",
"resourceType": "cloudresourcemanager.googleapis.com/Project",
"value": "user:[email protected]"
},
{
"action": "remove",
"path": "/iamPolicy/bindings/*/members/*",
"pathFilters": {
"/iamPolicy/bindings/*/condition/expression": "",
"/iamPolicy/bindings/*/members/*": "user:[email protected]",
"/iamPolicy/bindings/*/role": "roles/editor"
},
"resource": "//cloudresourcemanager.googleapis.com/projects/123456789012",
"resourceType": "cloudresourcemanager.googleapis.com/Project"
}
]
}
],
"overview": {
"addedRoles": [
"roles/iam.serviceAccountUser",
"roles/storage.objectAdmin"
],
"member": "user:[email protected]",
"minimumObservationPeriodInDays": "0",
"removedRole": "roles/editor",
"resource": "//cloudresourcemanager.googleapis.com/projects/123456789012"
}
},
"description": "Replace the current role with smaller predefined roles to cover the permissions needed.",
"etag": "\"0da9a354c2a83d96\"",
"lastRefreshTime": "2022-06-22T07:00:00Z",
"name": "projects/123456789012/locations/global/recommenders/google.iam.policy.Recommender/recommendations/4637db3d-dba5-45eb-95ac-b4ee4b4cd14e",
"primaryImpact": {
"category": "SECURITY",
"securityProjection": {
"details": {
"revokedIamPermissionsCount": 2998
}
}
},
"priority": "P2",
"recommenderSubtype": "REPLACE_ROLE",
"stateInfo": {
"state": "ACTIVE"
}
}
REST
{
"name": "projects/123456789012/locations/global/recommenders/google.iam.policy.Recommender/recommendations/4637db3d-dba5-45eb-95ac-b4ee4b4cd14e",
"description": "Replace the current role with smaller predefined roles to cover the permissions needed.",
"lastRefreshTime": "2022-06-22T07:00:00Z",
"primaryImpact": {
"category": "SECURITY",
"securityProjection": {
"details": {
"revokedIamPermissionsCount": 2998
}
}
},
"content": {
"operationGroups": [
{
"operations": [
{
"action": "add",
"resourceType": "cloudresourcemanager.googleapis.com/Project",
"resource": "//cloudresourcemanager.googleapis.com/projects/123456789012",
"path": "/iamPolicy/bindings/*/members/-",
"value": "user:[email protected]",
"pathFilters": {
"/iamPolicy/bindings/*/condition/expression": "",
"/iamPolicy/bindings/*/role": "roles/iam.serviceAccountOwner"
}
},
{
"action": "add",
"resourceType": "cloudresourcemanager.googleapis.com/Project",
"resource": "//cloudresourcemanager.googleapis.com/projects/123456789012",
"path": "/iamPolicy/bindings/*/members/-",
"value": "user:[email protected]",
"pathFilters": {
"/iamPolicy/bindings/*/condition/expression": "",
"/iamPolicy/bindings/*/role": "roles/storage.objectAdmin"
}
},
{
"action": "remove",
"resourceType": "cloudresourcemanager.googleapis.com/Project",
"resource": "//cloudresourcemanager.googleapis.com/projects/123456789012",
"path": "/iamPolicy/bindings/*/members/*",
"pathFilters": {
"/iamPolicy/bindings/*/condition/expression": "",
"/iamPolicy/bindings/*/members/*": "user:[email protected]",
"/iamPolicy/bindings/*/role": "roles/editor"
}
}
]
}
],
"overview": {
"resource": "//cloudresourcemanager.googleapis.com/projects/123456789012",
"member": "user:[email protected]",
"removedRole": "roles/editor",
"addedRoles": [
"roles/iam.serviceAccountUser",
"roles/storage.objectAdmin"
],
"minimumObservationPeriodInDays": "0"
}
},
"stateInfo": {
"state": "ACTIVE"
},
"etag": "\"0da9a354c2a83d96\"",
"recommenderSubtype": "REPLACE_ROLE",
"associatedInsights": [
{
"insight": "projects/123456789012/locations/global/insightTypes/google.iam.policy.Insight/insights/3d4ef3d6-bdf0-4330-975d-c65cb929c44d"
}
],
"priority": "P2"
}
Create a custom role
The user [email protected]
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, [email protected]
used only 4 of those
permissions.
Therefore, the IAM recommender generates a role recommendation
suggesting that you create a custom role that includes only the permissions that
[email protected]
actually used:
Console
gcloud
The REPLACE_ROLE_CUSTOMIZABLE
subtype indicates that the
IAM recommender recommends creating a custom role with the used
permissions. To see the used permissions, get the associated policy
insight.
{
"associatedInsights": [
{
"insight": "projects/123456789012/locations/global/insightTypes/google.iam.policy.Insight/insights/2799dc04-b12e-4cf6-86aa-d81907d31f58"
}
],
"associatedResourceNames": [
"//cloudresourcemanager.googleapis.com/projects/123456789012"
],
"content": {
"operationGroups": [
{
"operations": [
{
"action": "add",
"path": "/iamPolicy/bindings/*/members/-",
"pathFilters": {
"/iamPolicy/bindings/*/condition/expression": "",
"/iamPolicy/bindings/*/role": "roles/cloudtrace.user"
},
"resource": "//cloudresourcemanager.googleapis.com/projects/123456789012",
"resourceType": "cloudresourcemanager.googleapis.com/Project",
"value": "user:[email protected]"
},
{
"action": "remove",
"path": "/iamPolicy/bindings/*/members/*",
"pathFilters": {
"/iamPolicy/bindings/*/condition/expression": "",
"/iamPolicy/bindings/*/members/*": "user:[email protected]",
"/iamPolicy/bindings/*/role": "roles/cloudtrace.admin"
},
"resource": "//cloudresourcemanager.googleapis.com/projects/123456789012",
"resourceType": "cloudresourcemanager.googleapis.com/Project"
}
]
}
],
"overview": {
"minimumObservationPeriodInDays": "0"
}
},
"description": "Replace the current role with a smaller role to cover the permissions needed.",
"etag": "\"c7f57a4725d32d66\"",
"lastRefreshTime": "2022-06-22T07:00:00Z",
"name": "projects/123456789012/locations/global/recommenders/google.iam.policy.Recommender/recommendations/ba1fc977-fddd-3856-a829-f69649ae8075",
"originalContent": {},
"primaryImpact": {
"category": "SECURITY",
"securityProjection": {
"details": {},
"revokedIamPermissionsCount": 1
}
},
"priority": "P4",
"recommenderSubtype": "REPLACE_ROLE_CUSTOMIZABLE",
"stateInfo": {
"state": "ACTIVE"
},
"targetResources": [
"//cloudresourcemanager.googleapis.com/projects/123456789012"
]
}
REST
The REPLACE_ROLE_CUSTOMIZABLE
subtype indicates that
the IAM recommender recommends creating a custom role with the used
permissions. To see the used permissions, get the associated policy
insight.
{
"name": "projects/123456789012/locations/global/recommenders/google.iam.policy.Recommender/recommendations/ba1fc977-fddd-3856-a829-f69649ae8075",
"description": "Replace the current role with a smaller role to cover the permissions needed.",
"lastRefreshTime": "2022-06-22T07:00:00Z",
"primaryImpact": {
"category": "SECURITY",
"securityProjection": {
"details": {
"revokedIamPermissionsCount": 1
}
}
},
"content": {
"operationGroups": [
{
"operations": [
{
"action": "add",
"resourceType": "cloudresourcemanager.googleapis.com/Project",
"resource": "//cloudresourcemanager.googleapis.com/projects/123456789012",
"path": "/iamPolicy/bindings/*/members/-",
"value": "user:[email protected]",
"pathFilters": {
"/iamPolicy/bindings/*/condition/expression": "",
"/iamPolicy/bindings/*/role": "roles/cloudtrace.user"
}
},
{
"action": "remove",
"resourceType": "cloudresourcemanager.googleapis.com/Project",
"resource": "//cloudresourcemanager.googleapis.com/projects/123456789012",
"path": "/iamPolicy/bindings/*/members/*",
"pathFilters": {
"/iamPolicy/bindings/*/condition/expression": "",
"/iamPolicy/bindings/*/members/*": "user:[email protected]",
"/iamPolicy/bindings/*/role": "roles/cloudtrace.admin"
}
}
]
}
],
"overview": {
"minimumObservationPeriodInDays": "0"
}
},
"stateInfo": {
"state": "ACTIVE"
},
"etag": "\"c7f57a4725d32d66\"",
"recommenderSubtype": "REPLACE_ROLE_CUSTOMIZABLE",
"associatedInsights": [
{
"insight": "projects/123456789012/locations/global/insightTypes/google.iam.policy.Insight/insights/2799dc04-b12e-4cf6-86aa-d81907d31f58"
}
],
"priority": "P4"
}
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. The IAM recommender identified these permissions using machine learning.
The IAM 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:
Console
The IAM recommender uses a Machine learning
resourcemanager.projects.get
permission was recommended
based on machine learning:
gcloud
Permissions that were added based on the IAM recommender's machine
learning rather than on permission usage aren't listed in the recommendation
itself. Instead, they're listed in the policy insights associated with the
recommendation. All ML-based permissions are listed in the inferredPermissions
field of the insight. In this example, the resourcemanager.projects.get
permission was recommended based on machine learning:
associatedRecommendations:
- recommendation: projects/123456789012/locations/global/recommenders/google.iam.policy.Recommender/recommendations/0573b702-96a5-4622-a916-c762e7b0731f
category: SECURITY
content:
condition:
description: ''
expression: ''
location: ''
title: ''
currentTotalPermissionsCount: '5069'
exercisedPermissions:
- permission: storage.objects.create
- permission: storage.objects.delete
- permission: storage.objects.get
- permission: storage.objects.list
inferredPermissions:
- permission: resourcemanager.projects.get
member: serviceAccount:[email protected]
role: roles/editor
description: 4 of the permissions in this role binding were used in the past 90 days.
etag: '"d3cdec23cc712bd0"'
insightSubtype: PERMISSIONS_USAGE
lastRefreshTime: '2020-07-11T07:00:00Z'
name: projects/123456789012/locations/global/insightTypes/google.iam.policy.Insight/insights/0d3ce433-f067-4e78-b6ae-03d7d1f6f040
observationPeriod: 7776000s
stateInfo:
state: ACTIVE
targetResources:
- //cloudresourcemanager.googleapis.com/projects/123456789012
severity: HIGH
To learn how to get a policy insight, see one of the following:
REST
Permissions that were added based on the IAM recommender's machine
learning rather than on permission usage aren't listed in the recommendation
itself. Instead, they're listed in the policy insights associated with the
recommendation. All ML-based permissions are listed in the inferredPermissions
field of the insight. In this example, the resourcemanager.projects.get
permission was recommended based on machine learning:
{
"name": "projects/123456789012/locations/global/insightTypes/google.iam.policy.Insight/insights/07841f74-02ce-4de8-bbe6-fc4eabb68568",
"description": "4 of the permissions in this role binding were used in the past 90 days.",
"content": {
"role": "roles/editor",
"member": "serviceAccount:[email protected]",
"condition": {
"expression": "",
"title": "",
"description": "",
"location": ""
},
"exercisedPermissions": [
{
"permission": "storage.objects.create"
},
{
"permission": "storage.objects.delete"
},
{
"permission": "storage.objects.get"
},
{
"permission": "storage.objects.list"
}
],
"inferredPermissions": [
{
"permission": "resourcemanager.projects.get"
}
],
"currentTotalPermissionsCount": "5069"
},
"lastRefreshTime": "2020-07-12T07:00:00Z",
"observationPeriod": "7776000s",
"stateInfo": {
"state": "ACTIVE"
},
"category": "SECURITY",
"associatedRecommendations": [
{
"recommendation": "projects/123456789012/locations/global/recommenders/google.iam.policy.Recommender/recommendations/b1932220-867d-43d1-bd74-fb95876ab656"
}
],
"targetResources": [
"//cloudresourcemanager.googleapis.com/projects/123456789012"
],
"insightSubtype": "PERMISSIONS_USAGE",
"etag": "\"d3cdec23cc712bd0\"",
"severity": "HIGH"
}
To learn how to get a policy insight, see one of the following:
What's next
- Understand best practices for using role recommendations.
- Review and apply role recommendations for projects, folders, and organizations.
- Review and apply your role recommendations for Cloud Storage buckets
- Review and apply your role recommendations for BigQuery datasets
- Learn more about Recommender.
- Understand predefined roles and custom roles in IAM.