This page shows how to manage service account insights, which are findings about which service accounts in your project have not been used in the past 90 days.
Before you begin
-
Enable the Recommender API.
- Optional: Read about Recommender insights.
Required roles
To get the permissions that you need to manage service account insights, ask your administrator to grant you the following IAM roles on the project that you want to manage insights for:
-
To view service account insights:
IAM Recommender Viewer (
roles/recommender.iamViewer
) -
To modify service account insights:
IAM Recommender Admin (
roles/recommender.iamAdmin
)
For more information about granting roles, see Manage access to projects, folders, and organizations.
These predefined roles contain the permissions required to manage service account insights. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to manage service account insights:
-
To view service account insights:
-
recommender.iamServiceAccountinsights.get
-
recommender.iamServiceAccountinsights.list
-
-
To modify service account insights:
recommender.iamServiceAccountinsights.update
You might also be able to get these permissions with custom roles or other predefined roles.
List service account insights
To list all service account insights for your project, use one of the following methods:gcloud
Use the gcloud recommender
insights list
command to view all service account insights for your
project.
Before you run the command, replace the following values:
PROJECT_ID
: The ID of the project that you want to list insights for.
gcloud recommender insights list --insight-type=google.iam.serviceAccount.Insight \ --project=PROJECT_ID \ --location=global
The output lists all of the service account insights for your project. For example:
INSIGHT_ID CATEGORY INSIGHT_STATE LAST_REFRESH_TIME SEVERITY INSIGHT_SUBTYPE DESCRIPTION 446303ba-2a14-49cc-b9fa-e2d2499d4f82 SECURITY ACTIVE 2022-05-24T07:00:00Z LOW SERVICE_ACCOUNT_USAGE Service account sa-1@my-project.iam.gserviceaccount.com was inactive. 4cfd82c3-7320-4dc6-9b67-ca0756bbd54c SECURITY ACTIVE 2022-05-24T07:00:00Z LOW SERVICE_ACCOUNT_USAGE Service account sa-2@my-project.iam.gserviceaccount.com was inactive. a627bed7-c8f4-4611-89c9-2a9a8618ca1b SECURITY ACTIVE 2022-05-24T07:00:00Z LOW SERVICE_ACCOUNT_USAGE Service account sa-3@my-project.iam.gserviceaccount.com was inactive. a922dd59-df0a-422d-a2a4-096195e1dae5 SECURITY ACTIVE 2022-05-24T07:00:00Z LOW SERVICE_ACCOUNT_USAGE Service account sa-4@my-project.iam.gserviceaccount.com was inactive.
REST
The Recommender API's
insights.list
method lists all service account insights for your
project.
Before using any of the request data, make the following replacements:
PROJECT_ID
: The ID of the project that you want to list insights for.
HTTP method and URL:
GET https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/global/insightTypes/google.iam.serviceAccount.Insight/insights
To send your request, expand one of these options:
The response lists all of the service account insights for your project. For example:
{ "insights": [ { "name": "projects/123456789012/locations/global/insightTypes/google.iam.serviceAccount.Insight/insights/446303ba-2a14-49cc-b9fa-e2d2499d4f82", "description": "Service account sa-1@my-project.iam.gserviceaccount.com was inactive.", "content": { "serviceAccountId": "103185812403937829397", "email": "sa-1@my-project.iam.gserviceaccount.com", "lastAuthenticatedTime": "2020-09-11T07:00:00Z" }, "lastRefreshTime": "2022-05-24T07:00:00Z", "observationPeriod": "19008000s", "stateInfo": { "state": "ACTIVE" }, "category": "SECURITY", "targetResources": [ "//cloudresourcemanager.googleapis.com/projects/123456789012" ], "insightSubtype": "SERVICE_ACCOUNT_USAGE", "etag": "\"9d797dd04263c855\"", "severity": "LOW" }, { "name": "projects/123456789012/locations/global/insightTypes/google.iam.serviceAccount.Insight/insights/4cfd82c3-7320-4dc6-9b67-ca0756bbd54c", "description": "Service account sa-2@my-project.iam.gserviceaccount.com was inactive.", "content": { "serviceAccountId": "105496400997178042131", "email": "sa-2@my-project.iam.gserviceaccount.com" }, "lastRefreshTime": "2022-05-24T07:00:00Z", "observationPeriod": "16070400s", "stateInfo": { "state": "ACTIVE" }, "category": "SECURITY", "targetResources": [ "//cloudresourcemanager.googleapis.com/projects/123456789012" ], "insightSubtype": "SERVICE_ACCOUNT_USAGE", "etag": "\"783a32b635d79a4e\"", "severity": "LOW" } ] }
To learn more about the components of an insight, see Review service account insights on this page.
Get a single service account insight
To get more information about a single insight, including the insight's description, status, and any recommendations it's associated with, use one of the following methods:
gcloud
Use the gcloud recommender
insights describe
command with your insight ID to view information about a single
insight.
-
INSIGHT_ID
: The ID of the insight that you want to view. To find the ID, list the insights for your project. PROJECT_ID
: The ID of the project that you want to manage insights for.
gcloud recommender insights describe INSIGHT_ID \ --insight-type=google.iam.serviceAccount.Insight \ --project=PROJECT_ID \ --location=global
The output shows the insight in detail. For example,the following insight indicates that the service account
sa-1@my-project.iam.gserviceaccount.com
has not authenticated since
October 11, 2020.
category: SECURITY content: email: sa-1@my-project.iam.gserviceaccount.com lastAuthenticatedTime: '2020-10-11T07:00:00Z' serviceAccountId: '103185812403937829397' description: Service account sa-1@my-project.iam.gserviceaccount.com was inactive. etag: '"9d797dd04263c855"' insightSubtype: SERVICE_ACCOUNT_USAGE lastRefreshTime: '2022-05-24T07:00:00Z' name: projects/123456789012/locations/global/insightTypes/google.iam.serviceAccount.Insight/insights/446303ba-2a14-49cc-b9fa-e2d2499d4f82 observationPeriod: 19008000s severity: LOW stateInfo: state: ACTIVE targetResources: - //cloudresourcemanager.googleapis.com/projects/123456789012
To learn more about the components of an insight, see Review service account insights on this page.
REST
The Recommender API's
insights.get
method gets a single insight.
Before using any of the request data, make the following replacements:
-
PROJECT_ID
: The ID of the project that you want to manage insights for. -
INSIGHT_ID
: The ID of the insight that you want to view. If you don't know the insight ID, you can find it by listing the insights in your project. The ID of an insight is everything afterinsights/
in thename
field for the insight.
HTTP method and URL:
GET https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/global/insightTypes/google.iam.serviceAccount.Insight/insights/INSIGHT_ID
To send your request, expand one of these options:
The response contains the insight. For example,the following insight indicates that the service account
sa-1@my-project.iam.gserviceaccount.com
has not authenticated since
October 11, 2020.
{ "name": "projects/123456789012/locations/global/insightTypes/google.iam.serviceAccount.Insight/insights/446303ba-2a14-49cc-b9fa-e2d2499d4f82", "description": "Service account sa-1@my-project.iam.gserviceaccount.com was inactive.", "content": { "serviceAccountId": "103185812403937829397", "email": "sa-1@my-project.iam.gserviceaccount.com", "lastAuthenticatedTime": "2020-09-11T07:00:00Z" }, "lastRefreshTime": "2022-05-24T07:00:00Z", "observationPeriod": "19008000s", "stateInfo": { "state": "ACTIVE" }, "category": "SECURITY", "targetResources": [ "//cloudresourcemanager.googleapis.com/projects/123456789012" ], "insightSubtype": "SERVICE_ACCOUNT_USAGE", "etag": "\"9d797dd04263c855\"", "severity": "LOW" }
To learn more about the components of an insight, see Review service account insights on this page.
Review service account insights
After you get a single insight, you can review its contents to understand the pattern of resource usage that it highlights.
An insight's content is determined by its subtypes.
Service account insights (google.iam.serviceAccount.Insight
) insights
have the SERVICE_ACCOUNT_USAGE
subtype.
SERVICE_ACCOUNT_USAGE
insights have the following components, not necessarily
in this order:
-
associatedRecommendations
: The identifiers for any recommendations associated with the insight. If there are no recommendations associated with the insight, this field is empty. -
category
: The category for IAM insights is alwaysSECURITY
. -
content
: Reports the last time the service account was authenticated. This field contains the following components:email
: The email address of the service account.lastAuthenticatedTime
: The most recent time that the service account was authenticated. If the service account does not have any recorded authentications, this field is not included.serviceAccountId
: The unique numeric ID of the service account.
-
description
: A human-readable summary of the insight. -
etag
: A unique identifier for the current state of an insight. Each time the insight changes, a newetag
value is assigned.To change the state of an insight, you must provide the
etag
of the existing insight. Using theetag
helps ensure that any operations are performed only if the insight has not changed since you last retrieved it. -
insightSubtype
: The insight subtype. -
lastRefreshTime
: The date when the insight was last refreshed, which indicates the freshness of the data used to generate the insight. -
name
: The name of the insight, in the following format:projects/PROJECT_ID/locations/global/insightTypes/google.iam.serviceAccount.Insight/insights/INSIGHT_ID
The placeholders have the following values:
-
PROJECT_ID
: The ID of the project where the insight was generated. INSIGHT_ID
: A unique ID for the insight.
-
-
observationPeriod
: The time period leading up to the insight. The source data used to generate the insight ends atlastRefreshTime
and begins atlastRefreshTime
minusobservationPeriod
. -
stateInfo
: Insights go through multiple state transitions after they are proposed:-
ACTIVE
: The insight has been generated, but either no actions have been taken, or an action was taken without updating the insight's state. Active insights are updated when the underlying data changes. -
ACCEPTED
: Some action has been taken based on the insight. Insights become accepted when an associated recommendation was markedCLAIMED
,SUCCEEDED
, orFAILED
, or the insight was accepted directly. When an insight is in theACCEPTED
state, the content of the insight cannot change. Accepted insights are retained for 90 days after they are accepted.
-
-
targetResources
: The full resource name of the project that the insight is for. For example,//cloudresourcemanager.googleapis.com/projects/123456789012
.
Mark a service account insight as ACCEPTED
If you take action based on an active insight, you can mark that insight as
ACCEPTED
. The ACCEPTED
state tells the
Recommender API that you have taken action based on this
insight, which helps refine your recommendations.
Accepted insights are retained for 90 days after
they are marked as ACCEPTED
.
gcloud
Use the
gcloud recommender insights mark-accepted
command with your insight ID to mark
an insight as ACCEPTED
.
-
INSIGHT_ID
: The ID of the insight that you want to view. To find the ID, list the insights for your project. PROJECT_ID
: The ID of the project that you want to manage insights for.-
ETAG
: An identifier for a version of the insight. To get theetag
, do the following:-
Get the insight using the
gcloud recommender insights describe
command. -
Find and copy the
etag
value from the output, including the enclosing quotes. For example,"d3cdec23cc712bd0"
.
-
Get the insight using the
gcloud recommender insights mark-accepted INSIGHT_ID \ --insight-type=google.iam.serviceAccount.Insight \ --project=PROJECT_ID \ --location=global \ --etag=ETAG
The output shows the insight, now with the state of ACCEPTED
:
category: SECURITY content: email: sa-1@my-project.iam.gserviceaccount.com lastAuthenticatedTime: '2020-10-11T07:00:00Z' serviceAccountId: '103185812403937829397' description: Service account sa-1@my-project.iam.gserviceaccount.com was inactive. etag: '"39c4199dcec92848"' insightSubtype: SERVICE_ACCOUNT_USAGE lastRefreshTime: '2022-05-24T07:00:00Z' name: projects/123456789012/locations/global/insightTypes/google.iam.serviceAccount.Insight/insights/446303ba-2a14-49cc-b9fa-e2d2499d4f82 observationPeriod: 19008000s severity: LOW stateInfo: state: ACCEPTED targetResources: - //cloudresourcemanager.googleapis.com/projects/123456789012
To learn more about the state info of an insight, see Review service account insights on this page.
REST
The Recommender API's
insights.markAccepted
method marks an insight as ACCEPTED
.
Before using any of the request data, make the following replacements:
-
PROJECT_ID
: The ID of the project that you want to manage insights for. -
INSIGHT_ID
: The ID of the insight that you want to view. If you don't know the insight ID, you can find it by listing the insights in your project. The ID of an insight is everything afterinsights/
in thename
field for the insight. -
ETAG
: An identifier for a version of the insight. To get theetag
, do the following:- Get the insight using the
insights.get
method. - Find and copy the
etag
value from the response.
- Get the insight using the
HTTP method and URL:
POST https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/global/insightTypes/google.iam.serviceAccount.Insight/insights/INSIGHT_ID:markAccepted
Request JSON body:
{ "etag": "ETAG" }
To send your request, expand one of these options:
The response contains the insight, now with the state of ACCEPTED
:
{ "name": "projects/123456789012/locations/global/insightTypes/google.iam.serviceAccount.Insight/insights/446303ba-2a14-49cc-b9fa-e2d2499d4f82", "description": "Service account sa-1@my-project.iam.gserviceaccount.com was inactive.", "content": { "serviceAccountId": "103185812403937829397", "email": "sa-1@my-project.iam.gserviceaccount.com", "lastAuthenticatedTime": "2020-10-11T07:00:00Z" }, "lastRefreshTime": "2022-05-24T07:00:00Z", "observationPeriod": "19008000s", "stateInfo": { "state": "ACCEPTED" }, "category": "SECURITY", "targetResources": [ "//cloudresourcemanager.googleapis.com/projects/123456789012" ], "insightSubtype": "SERVICE_ACCOUNT_USAGE", "etag": "\"39c4199dcec92848\"", "severity": "LOW" }
To learn more about the state info of an insight, see Review service account insights on this page.
What's next
- Review the other available tools to understand service account usage.
- Use the Recommendation Hub to view and manage all recommendations for your project, including IAM recommendations.