View recent usage for service accounts and keys

This page shows you how to use Activity Analyzer to see when your service accounts and keys were last used to call a Google API. These usages are called authentication activities.

Authentication activities include any time a service account or key is used to call any Google API, including APIs that are not part of Google Cloud. Authentication activities include both successful and failed API calls. For example, if an API call fails because the caller is not authorized to call that API, or because the request referred to a resource that does not exist, the action still counts as an authentication activity for the service account or key that was used for that API call.

Authentication activities for service account keys also include any time a system lists the keys while attempting to authenticate a request, even if the system doesn't use the key to authenticate the request. This behavior is most common when using signed URLs for Cloud Storage or when authenticating to third-party applications.

Activity Analyzer reports the date of the most recent authentication activity. The date is determined based on US and Canadian Pacific Standard Time (UTC-8), even when Pacific Daylight Time is in effect. If you need the specific time of the activity, or want to track usage patterns over time, use Monitoring to view usage metrics for all service accounts and keys.

Recent authentication activity can help you identify service accounts and service account keys that you no longer use. We recommend disabling or deleting these unused service accounts and keys because they create an unnecessary security risk.

Before you begin

  • Enable the Policy Analyzer API.

    Enable the API

Required permissions

To list the most recent authentication activities for your service accounts and service account keys, you need a role that includes the following permissions:

  • policyanalyzer.serviceAccountLastAuthenticationActivities.query
  • policyanalyzer.serviceAccountKeyLastAuthenticationActivities.query

To gain these permissions while following the principle of least privilege, ask your administrator to grant you the Activity Analysis Viewer role (roles/policyanalyzer.activityAnalysisViewer).

Alternatively, your administrator can grant you a different role with the required permissions, such as a custom role or a more permissive predefined role.

View recent usage for all service accounts or keys

To view recent usage for your service accounts or service account keys, use Activity Analyzer to list the dates of the most recent authentication activities.

gcloud

To list the most recent authentication activities for your service accounts or keys, use the gcloud policy-intelligence query-activity command:

gcloud policy-intelligence query-activity --activity-type=ACTIVITY_TYPE \
    --project=PROJECT_ID --limit=LIMIT

Replace the following values:

  • ACTIVITY_TYPE: The activity type that you want to list. To list the most recent usage times for your service accounts, use serviceAccountLastAuthentication. To list most recent usage times for your service account keys, use serviceAccountKeyLastAuthentication.
  • PROJECT_ID: Your Google Cloud project ID. Project IDs are alphanumeric strings, like my-project.
  • LIMIT: Optional. The maximum number of results to be returned. The default value is 1000.

The response is similar to the following, which lists recent usage times for a project's service accounts:

---
activity:
  lastAuthenticatedTime: '2021-04-27T07:00:00Z'
  serviceAccount:
    fullResourceName: //iam.googleapis.com/projects/my-project/serviceAccounts/service-account-1@my-project.iam.gserviceaccount.com
    projectNumber: '123456789012'
    serviceAccountId: '123456789012345678901'
activityType: serviceAccountLastAuthentication
fullResourceName: //iam.googleapis.com/projects/my-project/serviceAccounts/service-account-1@my-project.iam.gserviceaccount.com
observationPeriod:
  endTime: '2021-07-06T07:00:00Z'
  startTime: '2020-03-12T07:00:00Z'
---
activity:
  lastAuthenticatedTime: '2021-02-09T08:00:00Z'
  serviceAccount:
    fullResourceName: //iam.googleapis.com/projects/my-project/serviceAccounts/service-account-2@my-project.iam.gserviceaccount.com
    projectNumber: '123456789012'
    serviceAccountId: '234567890123456789012'
activityType: serviceAccountLastAuthentication
fullResourceName: //iam.googleapis.com/projects/my-project/serviceAccounts/service-account-2@my-project.iam.gserviceaccount.com
observationPeriod:
  endTime: '2021-07-06T07:00:00Z'
  startTime: '2020-09-01T07:00:00Z'

To learn how to understand these results, see Understand activities on this page.

REST

The Policy Analyzer API's activities.query method lists the most recent authentication activities for your service accounts or keys.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: Your Google Cloud project ID. Project IDs are alphanumeric strings, like my-project.
  • ACTIVITY_TYPE: The activity type that you want to list. To list the most recent usages for all of your service accounts, use serviceAccountLastAuthentication. To list most recent usages for all of your service account keys, use serviceAccountKeyLastAuthentication.
  • PAGE_SIZE: Optional. The maximum number of results to return from this request. If not specified, the server will determine the number of results to return. If the number of activities is greater than the page size, the response contains a pagination token that you can use to retrieve the next page of results.
  • PAGE_TOKEN: Optional. The pagination token returned in an earlier response from this method. If specified, the list of activities will start where the previous request ended.

HTTP method and URL:

GET https://policyanalyzer.googleapis.com/v1/projects/PROJECT_ID/locations/global/activityTypes/ACTIVITY_TYPE/activities:query?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN

To send your request, expand one of these options:

The response is similar to the following, which lists recent usage times for a project's service accounts:

{
  "activities": [
    {
      "fullResourceName": "//iam.googleapis.com/projects/my-project/serviceAccounts/service-account-1@my-project.iam.gserviceaccount.com",
      "activityType": "serviceAccountLastAuthentication",
      "observationPeriod": {
        "startTime": "2020-04-20T07:00:00Z",
        "endTime": "2021-05-17T07:00:00Z"
      },
      "activity": {
        "lastAuthenticatedTime": "2021-04-28T07:00:00Z",
        "serviceAccount": {
          "projectNumber": "123456789012",
          "fullResourceName": "//iam.googleapis.com/projects/my-project/serviceAccounts/service-account-1@my-project.iam.gserviceaccount.com",
          "serviceAccountId": "123456789012345678901"
        }
      }
    },
    {
      "fullResourceName": "//iam.googleapis.com/projects/my-project/serviceAccounts/service-account-2@my-project.iam.gserviceaccount.com",
      "activityType": "serviceAccountLastAuthentication",
      "observationPeriod": {
        "startTime": "2020-04-20T07:00:00Z",
        "endTime": "2021-05-17T07:00:00Z"
      },
      "activity": {
        "lastAuthenticatedTime": "2021-04-29T07:00:00Z",
        "serviceAccount": {
          "projectNumber": "123456789012",
          "fullResourceName": "//iam.googleapis.com/projects/my-project/serviceAccounts/service-account-2@my-project.iam.gserviceaccount.com",
          "serviceAccountId": "234567890123456789012"
        }
      }
    }
  ],
  "nextPageToken": "AVgRrQV4b5nISN6cGJvTPFJ2v_"
}

To learn how to understand these results, see Understand activities on this page.

View recent usage for specific service accounts

To find the last date that specific service accounts were used, filter Activity Analyzer results using the full resource names for the service accounts.

gcloud

To get the most recent authentication activity for specific service accounts, use the gcloud policy-intelligence query-activity command with a filter:

gcloud policy-intelligence query-activity --activity-type=serviceAccountLastAuthentication \
    --project=PROJECT_ID \
    --query-filter='FILTER'

Replace the following values:

  • PROJECT_ID: Your Google Cloud project ID. Project IDs are alphanumeric strings, like my-project.
  • FILTER: A filter specifying the full resource names of the service accounts whose usage you want to see. The full resource name of a service account includes the project ID and the email address of the service account.

    To filter for a single service account, use a filter with the following format:

    activities.full_resource_name="//iam.googleapis.com/projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL"
    

    To filter for multiple service accounts, use OR to specify multiple acceptable full resource names:

    activities.full_resource_name="//iam.googleapis.com/projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_1_EMAIL" OR activities.full_resource_name="//iam.googleapis.com/projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_2_EMAIL"
    

    You can filter for up to 10 service accounts.

The response describes the most recent usage for the service accounts:

---
activity:
  lastAuthenticatedTime: '2021-04-27T07:00:00Z'
  serviceAccount:
    fullResourceName: //iam.googleapis.com/projects/my-project/serviceAccounts/service-account-1@my-project.iam.gserviceaccount.com
    projectNumber: '123456789012'
    serviceAccountId: '123456789012345678901'
activityType: serviceAccountLastAuthentication
fullResourceName: //iam.googleapis.com/projects/my-project/serviceAccounts/service-account-1@my-project.iam.gserviceaccount.com
observationPeriod:
  endTime: '2021-07-06T07:00:00Z'
  startTime: '2020-03-12T07:00:00Z'

To learn how to understand these results, see Understand activities on this page.

REST

The Policy Analyzer API's activities.query method , when used with a filter, gets the most recent authentication activity for specific service accounts.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: Your Google Cloud project ID. Project IDs are alphanumeric strings, like my-project.
  • FILTER: A filter specifying the full resource names of the service accounts whose usage you want to see.

    To filter for a single service account, use a filter with the following format:

    activities.full_resource_name%3D%22%2F%2Fiam.googleapis.com%2Fprojects%2FPROJECT_ID%2FserviceAccounts%2FSERVICE_ACCOUNT_EMAIL%22

    To filter for multiple service accounts, use %20OR%20 to specify multiple acceptable full resource names:

    activities.full_resource_name%3D%22%2F%2Fiam.googleapis.com%2Fprojects%2FPROJECT_ID%2FserviceAccounts%2FSERVICE_ACCOUNT_1_EMAIL%22%20OR%20activities.full_resource_name%3D%22%2F%2Fiam.googleapis.com%2Fprojects%2FPROJECT_ID%2FserviceAccounts%2FSERVICE_ACCOUNT_2_EMAIL%22

HTTP method and URL:

GET https://policyanalyzer.googleapis.com/v1/projects/PROJECT_ID/locations/global/activityTypes/serviceAccountLastAuthentication/activities:query?filter=FILTER

To send your request, expand one of these options:

The response describes the most recent usage for the service accounts:

{
  "activities": [
    {
      "fullResourceName": "//iam.googleapis.com/projects/my-project/serviceAccounts/service-account-1@my-project.iam.gserviceaccount.com",
      "activityType": "serviceAccountLastAuthentication",
      "observationPeriod": {
        "startTime": "2020-04-20T07:00:00Z",
        "endTime": "2021-05-17T07:00:00Z"
      },
      "activity": {
        "lastAuthenticatedTime": "2021-04-28T07:00:00Z",
        "serviceAccount": {
          "projectNumber": "123456789012",
          "fullResourceName": "//iam.googleapis.com/projects/my-project/serviceAccounts/service-account-1@my-project.iam.gserviceaccount.com",
          "serviceAccountId": "123456789012345678901"
        }
      }
    }
  ]
}

View recent usage for specific service account keys

To find the last date that specific service account keys were used, find the unique IDs for the service account keys, then filter Activity Analyzer results using those IDs.

If you have a JSON key file, you can find a service account key's unique ID in the file's private_key_id field.

If you don't have a JSON key file, you can find a service account key's unique ID by following these steps:

Console

  1. In the Cloud Console, go to the Service Accounts page.

    Go to the Service Accounts page

  2. Select the project that contains the service account associated with your key.

  3. Click the email address of the service account associated with your key.

  4. Click the Keys tab.

  5. Find and copy your key ID from the list of key IDs.

gcloud

  1. Run the gcloud iam service-accounts keys list command, replacing SERVICE_ACCOUNT_EMAIL with the email address of the service account that the key is associated with:

    gcloud iam service-accounts keys list --iam-account=SERVICE_ACCOUNT_EMAIL
    

    The output shows a list of all of the user-created keys associated with the service account, including each key's unique ID, creation time, and expiration time.

  2. Use the data in the output to identify the key you want to track and copy its unique ID.

REST

  1. List the service account keys:

    The Policy Analyzer API's projects.serviceAccounts.keys.list method lists all of the service account keys for a service account.

    Before using any of the request data, make the following replacements:

    • PROJECT_ID: Your Google Cloud project ID. Project IDs are alphanumeric strings, like my-project.
    • SA_NAME: The name of the service account whose keys you want to list.
    • KEY_TYPES: Optional. A comma-separated list of key types that you want to include in the response. The key type indicates whether a key is user-managed (USER_MANAGED) or system-managed (SYSTEM_MANAGED). If left blank, all keys are returned.

    HTTP method and URL:

    GET https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_NAME@PROJECT_ID.iam.gserviceaccount.com/keys?keyTypes=KEY_TYPES

    To send your request, expand one of these options:

    You should receive a JSON response similar to the following:

    {
      "keys": [
        {
          "name": "projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com/keys/90c48f61c65cd56224a12ab18e6ee9ca9c3aee7c",
          "validAfterTime": "2020-03-04T17:39:47Z",
          "validBeforeTime": "9999-12-31T23:59:59Z",
          "keyAlgorithm": "KEY_ALG_RSA_2048",
          "keyOrigin": "GOOGLE_PROVIDED",
          "keyType": "USER_MANAGED"
        },
        {
          "name": "projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com/keys/e5e3800831ac1adc8a5849da7d827b4724b1fce8",
          "validAfterTime": "2020-03-31T23:50:09Z",
          "validBeforeTime": "9999-12-31T23:59:59Z",
          "keyAlgorithm": "KEY_ALG_RSA_2048",
          "keyOrigin": "GOOGLE_PROVIDED",
          "keyType": "USER_MANAGED"
        },
        {
          "name": "projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com/keys/b97699f042b8eee6a846f4f96259fbcd13e2682e",
          "validAfterTime": "2020-05-17T18:58:13Z",
          "validBeforeTime": "9999-12-31T23:59:59Z",
          "keyAlgorithm": "KEY_ALG_RSA_2048",
          "keyOrigin": "GOOGLE_PROVIDED",
          "keyType": "USER_MANAGED",
          "disabled": true
        }
      ]
    }
    

  2. Use the metadata in the response to identify the key you want to track. Then, copy the key's unique ID from the end of the name field.

    The name field has the following format:

    "name": "projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL/keys/KEY_ID"
    

    The key's unique ID is everything after keys/.

    For example, the unique ID in the following key name is 0f561cc41650ff521899de2fd653bd3de08e2da4:

    "name": "projects/my-project/serviceAccounts/my-account@my-project.iam.gserviceaccount.com/keys/0f561cc41650ff521899de2fd653bd3de08e2da4"
    

After you find the unique IDs for the service account keys, use the IDs to filter the results from Activity Analyzer:

gcloud

To get the most recent authentication activity for specific service account keys, use the gcloud policy-intelligence query-activity command with a filter:

gcloud policy-intelligence query-activity --activity-type=serviceAccountKeyLastAuthentication \
    --project=PROJECT_ID \
    --query-filter='FILTER'

Replace the following values:

  • PROJECT_ID: Your Google Cloud project ID. Project IDs are alphanumeric strings, like my-project.
  • FILTER: A filter specifying the full resource names of the service account keys whose usage you want to see. The full resource name of a service account key includes the project ID, the email address of the service account associated with the key, and the key ID.

    To filter for a single service account key, use a filter with the following format:

    activities.full_resource_name="//iam.googleapis.com/projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL/keys/KEY_ID"
    

    To filter for multiple service account keys, use OR to specify multiple acceptable full resource names:

    activities.full_resource_name="//iam.googleapis.com/projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_1_EMAIL/keys/KEY_ID_1" OR activities.full_resource_name="//iam.googleapis.com/projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_2_EMAIL/keys/KEY_ID_2"
    

    You can filter for up to 10 service account keys.

The response describes the most recent usage for the service account keys:

---
activity:
  lastAuthenticatedTime: '2021-06-11T07:00:00Z'
  serviceAccountKey:
    fullResourceName: //iam.googleapis.com/projects/my-project/serviceAccounts/service-account-1@my-project.iam.gserviceaccount.com/keys/1c65fca351d6925e629059743428b7af243a728c
    projectNumber: '232342569935'
    serviceAccountId: '103185812403937829397'
activityType: serviceAccountKeyLastAuthentication
fullResourceName: //iam.googleapis.com/projects/my-project/serviceAccounts/service-account-1@my-project.iam.gserviceaccount.com/keys/1c65fca351d6925e629059743428b7af243a728c
observationPeriod:
  endTime: '2021-07-06T07:00:00Z'
  startTime: '2020-09-10T07:00:00Z'

To learn how to understand these results, see Understand activities on this page.

REST

The Policy Analyzer API's activities.query method , when used with a filter, gets the most recent authentication activity for specific service account keys.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: Your Google Cloud project ID. Project IDs are alphanumeric strings, like my-project.
  • FILTER: A filter specifying the full resource names of the service account keys whose usage you want to see. The full resource name of a service account key includes the project ID, the email address of the service account associated with the key, and the key ID.

    To filter for a single service account key, use a filter with the following format:

    activities.full_resource_name%3D%22%2F%2Fiam.googleapis.com%2Fprojects%2FPROJECT_ID%2FserviceAccounts%2FSERVICE_ACCOUNT_EMAIL%2Fkeys%2FKEY_ID%22

    To filter for multiple service account keys, use %20OR%20 to specify multiple acceptable full resource names:

    activities.full_resource_name%3D%22%2F%2Fiam.googleapis.com%2Fprojects%2FPROJECT_ID%2FserviceAccounts%2FSERVICE_ACCOUNT_1_EMAIL%2Fkeys%2FKEY_ID_1%22%20OR%20activities.full_resource_name%3D%22%2F%2Fiam.googleapis.com%2Fprojects%2FPROJECT_ID%2FserviceAccounts%2FSERVICE_ACCOUNT_2_EMAIL%2Fkeys%2FKEY_ID_2%22

    You can filter for up to 10 service account keys.

HTTP method and URL:

GET https://policyanalyzer.googleapis.com/v1/projects/PROJECT_ID/locations/global/activityTypes/serviceAccountKeyLastAuthentication/activities:query?filter=FILTER

To send your request, expand one of these options:

The response describes the most recent usage for the service account keys:

{
  "activities": [
    {
      "activity": {
        "lastAuthenticatedTime": "2021-06-11T07:00:00Z",
        "serviceAccountKey": {
          "fullResourceName": "//iam.googleapis.com/projects/my-project/serviceAccounts/service-account-1@my-project.iam.gserviceaccount.com/keys/1c65fca351d6925e629059743428b7af243a728c",
          "projectNumber": "123456789012",
          "serviceAccountId": "123456789012345678901"
        }
      },
      "activityType": "serviceAccountKeyLastAuthentication",
      "fullResourceName": "//iam.googleapis.com/projects/my-project/serviceAccounts/service-account-1t@my-project.iam.gserviceaccount.com/keys/1c65fca351d6925e629059743428b7af243a728c",
      "observationPeriod": {
        "endTime": "2021-07-06T07:00:00Z",
        "startTime": "2020-04-20T07:00:00Z"
      }
    }
  ]
}

To learn how to understand these results, see Understand activities on this page.

Understand activities

Activity Analyzer reports results as a list of activities. Activities have the following fields:

  • fullResourceName: The full resource name of the service account or service account key whose activity is being reported. This format is described in the following sections, and in Full resource names.
  • activityType: The type of activity that is being reported. For recent service account authentication activity, the value is serviceAccountLastAuthentication. For recent service account key authentication activity, the value is serviceAccountKeyLastAuthentication.
  • observationPeriod: Start and end times indicating the span of time for which the service account or key was observed for activity. The time in these timestamps is always T07:00:00Z.
  • activity: The details of the activity. The contents of this field vary based on the activity type. See the following sections for details.

Details for service account activities

The activity field for serviceAccountLastAuthentication activities contains the following fields:

  • serviceAccount: Details about the service account whose activity is being reported, including the following:

    • fullResourceName: The full resource name of the service account, in the format //iam.googleapis.com/projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL.
    • projectNumber: The numeric ID of the project that owns the service account.
    • serviceAccountId: The numeric ID of the service account.
  • lastAuthenticatedTime: A timestamp representing the date at which the most recent authentication event occurred. The time in this timestamp is always T07:00:00Z, regardless of the exact time of the authentication event.

    This field is not included for service accounts that have never been used.

Details for service account key activities

The activity field for serviceAccountKeyLastAuthentication activities contains the following fields:

  • serviceAccountKey: Details about the service account key whose activity is being reported, including the following:

    • fullResourceName: The full resource name of the service account key, in the format //iam.googleapis.com/projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL/keys/KEY_ID.
    • projectNumber: The numeric ID of the project that owns the service account that the key is associated with.
    • serviceAccountId: The numeric ID of the service account that the key is associated with.
  • lastAuthenticatedTime: A timestamp representing the date at which the most recent authentication event occurred. The time in this timestamp is always T07:00:00Z, regardless of the exact time of the authentication event.

    This field is not included for service account keys that have never been used.

What's next