- Policy Intelligence
Contact Us Start free
- Home
- Policy Intelligence
- Documentation
- Guides
This page shows how to manage service account insights, which arefindings about which service accounts in your project have not been used in the past90 days.
Before you begin
-
Enable the Recommender API.
Enable the 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 DESCRIPTION446303ba-2a14-49cc-b9fa-e2d2499d4f82 SECURITY ACTIVE 2022-05-24T07:00:00Z LOW SERVICE_ACCOUNT_USAGE Service account [email protected] was inactive.4cfd82c3-7320-4dc6-9b67-ca0756bbd54c SECURITY ACTIVE 2022-05-24T07:00:00Z LOW SERVICE_ACCOUNT_USAGE Service account [email protected] was inactive.a627bed7-c8f4-4611-89c9-2a9a8618ca1b SECURITY ACTIVE 2022-05-24T07:00:00Z LOW SERVICE_ACCOUNT_USAGE Service account [email protected] was inactive.a922dd59-df0a-422d-a2a4-096195e1dae5 SECURITY ACTIVE 2022-05-24T07:00:00Z LOW SERVICE_ACCOUNT_USAGE Service account [email protected] 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:
curl (Linux, macOS, or Cloud Shell)
Execute the following command:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
"https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/global/insightTypes/google.iam.serviceAccount.Insight/insights"
PowerShell (Windows)
Execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/global/insightTypes/google.iam.serviceAccount.Insight/insights" | Select-Object -Expand Content
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 [email protected] was inactive.", "content": { "serviceAccountId": "103185812403937829397", "email": "[email protected]", "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 [email protected] was inactive.", "content": { "serviceAccountId": "105496400997178042131", "email": "[email protected]" }, "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[email protected] has not authenticated sinceOctober 11, 2020.
category: SECURITYcontent: 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_USAGElastRefreshTime: '2022-05-24T07:00:00Z'name: projects/123456789012/locations/global/insightTypes/google.iam.serviceAccount.Insight/insights/446303ba-2a14-49cc-b9fa-e2d2499d4f82observationPeriod: 19008000sseverity: LOWstateInfo: state: ACTIVEtargetResources:- //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 thenamefield 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:
curl (Linux, macOS, or Cloud Shell)
Execute the following command:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
"https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/global/insightTypes/google.iam.serviceAccount.Insight/insights/INSIGHT_ID"
PowerShell (Windows)
Execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/global/insightTypes/google.iam.serviceAccount.Insight/insights/INSIGHT_ID" | Select-Object -Expand Content
The response contains the insight. For example,the following insight indicates that the service account[email protected] has not authenticated sinceOctober 11, 2020.
{ "name": "projects/123456789012/locations/global/insightTypes/google.iam.serviceAccount.Insight/insights/446303ba-2a14-49cc-b9fa-e2d2499d4f82", "description": "Service account [email protected] was inactive.", "content": { "serviceAccountId": "103185812403937829397", "email": "[email protected]", "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 newetagvalue is assigned.To change the state of an insight, you must provide the
etagof the existing insight. Using theetaghelps 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 atlastRefreshTimeand begins atlastRefreshTimeminusobservationPeriod. -
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 theACCEPTEDstate, 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 describecommand. - Find and copy the
etagvalue 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: SECURITYcontent: 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_USAGElastRefreshTime: '2022-05-24T07:00:00Z'name: projects/123456789012/locations/global/insightTypes/google.iam.serviceAccount.Insight/insights/446303ba-2a14-49cc-b9fa-e2d2499d4f82observationPeriod: 19008000sseverity: LOWstateInfo: state: ACCEPTEDtargetResources:- //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 thenamefield for the insight. -
ETAG: An identifier for a version of the insight. To get theetag, do the following:- Get the insight using the
insights.getmethod. - Find and copy the
etagvalue 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:
curl (Linux, macOS, or Cloud Shell)
Save the request body in a file named request.json, and execute the following command:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/global/insightTypes/google.iam.serviceAccount.Insight/insights/INSIGHT_ID:markAccepted"
PowerShell (Windows)
Save the request body in a file named request.json, and execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/global/insightTypes/google.iam.serviceAccount.Insight/insights/INSIGHT_ID:markAccepted" | Select-Object -Expand Content
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 [email protected] was inactive.", "content": { "serviceAccountId": "103185812403937829397", "email": "[email protected]", "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.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-09-10 UTC.
[{ "type": "thumb-down", "id": "hardToUnderstand", "label":"Hard to understand" },{ "type": "thumb-down", "id": "incorrectInformationOrSampleCode", "label":"Incorrect information or sample code" },{ "type": "thumb-down", "id": "missingTheInformationSamplesINeed", "label":"Missing the information/samples I need" },{ "type": "thumb-down", "id": "otherDown", "label":"Other" }] [{ "type": "thumb-up", "id": "easyToUnderstand", "label":"Easy to understand" },{ "type": "thumb-up", "id": "solvedMyProblem", "label":"Solved my problem" },{ "type": "thumb-up", "id": "otherUp", "label":"Other" }]
