Monitoring usage for service accounts and keys

This page explains how to use Cloud Monitoring to check when your service accounts and service account keys were used. Tracking this information can help you identify service accounts and keys that you no longer use.

Service accounts and service account keys appear in these metrics if they are used to call any Google API, including APIs that are not part of Google Cloud. The metrics 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 service account or key that was used for that API call appears in the metrics.

Monitoring retains service account metrics for a limited time. If you need to access data for a longer time period, you can periodically export the results to BigQuery. For more information, see Monitoring metric export in the Solutions documentation.

Before you begin

To use Monitoring for your project, you must add your project to a Monitoring workspace. To add your project to a workspace, you can either create a new workspace or add your project to an existing workspace.

Viewing usage metrics

After you use a service account or service account key, usage metrics are usually available within a few minutes.

To view the usage metrics for your service accounts and service account keys, follow these steps:

Console

  1. In the Cloud Console, go to the Metrics explorer page.

    Go to the metrics explorer page

  2. In the Find resource type and metric field, set the resource type to IAM Service accounts and set the metric to one of the following values:
    • For service account usage metrics, select Authentication events.
    • For service account key usage metrics, select Key Authentication Events.
  3. Adjust the settings of the graph:
    • Select the time interval you want to view from the list of intervals above the graph. You can select one of the predefined intervals, or you can set a custom interval by clicking Custom and selecting a start and end time.
    • Choose Line or Stacked bar as the plot type.

These metrics show each service account or service account key use within the selected interval.

REST

The Cloud Monitoring API API's timeSeries.list method allows you to access usage metrics programmatically.

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

  • project-id: Your Google Cloud project ID.
  • metric-type: The type of metric you want to check. Use one of the following values:
    • For service account usage metrics, use iam.googleapis.com%2Fservice_account%2Fauthn_events_count.
    • For service account key usage metrics, use iam.googleapis.com%2Fservice_account%2Fkey%2Fauthn_events_count.
  • end-time: The end of the time interval that you want to check, in percent-encoded RFC 3339 format. For example, 2020-06-12T00%3A00%3A00.00Z.
  • start-time: The start of the time interval that you want to check, in percent-encoded RFC 3339 format. For example, 2020-04-12T00%3A00%3A00.00Z.

HTTP method and URL:

GET https://monitoring.googleapis.com/v3/projects/project-id/timeSeries?filter=metric.type%3D%22metric-type%22&interval.endTime=end-time&interval.startTime=start-time

To send your request, expand one of these options:

For more information about programmatically reading usage metrics, see Reading metric data in the Monitoring documentation.

Identifying unused service accounts and keys

Service account and service account key usage metrics 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.

Finding recent usage for a single service account

To find the last time that a service account was used, follow these steps:

Console

  1. Find and copy the unique numeric ID of the service account:

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

      Go to the Service Accounts page

    2. Select the project that contains your service account.

    3. Click the email address of your service account.

    4. Copy the service account's unique numeric ID from the Unique ID field.

  2. In the Cloud Console, go to the Metrics explorer page.

    Go to the metrics explorer page

  3. In the Find resource type and metric field, set the resource type to IAM Service accounts and set the metric to Authentication events.

  4. In the Filter field, select unique_id and paste the unique numeric ID for the service account.

  5. To make the graph easier to read, choose Line or Stacked bar as the plot type.

The most recent authentication event on the graph shows when the service account was last used.

REST

The Cloud Monitoring API's timeSeries.list method , when used with specific filters, allows you to get usage metrics for a single service account. You can then use those metrics to determine when the account was last used.

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

  • project-id: Your Google Cloud project ID.
  • service-account-id: The unique numeric ID of your service account. To find your service account's unique numeric ID, follow these steps:
    1. In the Cloud Console, go to the Service Accounts page.

      Go to the Service Accounts page
    2. Click the email address of your service account. Your service account's unique numeric ID is the value in the Unique ID field.
  • end-time: The end of the time interval that you want to check, in percent-encoded RFC 3339 format. For example, 2020-06-12T00%3A00%3A00.00Z.
  • start-time: The start of the time interval that you want to check, in percent-encoded RFC 3339 format. For example, 2020-04-12T00%3A00%3A00.00Z.

HTTP method and URL:

GET https://monitoring.googleapis.com/v3/projects/project-id/timeSeries?filter=metric.type%3D%22iam.googleapis.com%2Fservice_account%2Fauthn_events_count%22%20AND%20resource.labels.unique_id%3D%22service-account-id%22&interval.endTime=end-time&interval.startTime=start-time

To send your request, expand one of these options:

The response contains a timeSeries object with all of the recent authentication events for the specified service account. You can use this timeSeries object to determine when the service account was last used.

Finding recent usage for a single service account key

To find the last time that a service account key was used, find and copy the key's unique ID, then use that ID to find the usage metrics for the key.

If you have a JSON key file, you can find the 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 the 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

    1. Select the project that contains the service account associated with your key.
    2. Click the email address of the service account associated with your key.
    3. Find the Keys section of the page, then 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 projects.serviceAccounts.keys.list method lists all of the service account keys for a service account.

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

    • project-id: Your Google Cloud project ID.
    • 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"
        }
      ]
    }
    

  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"
    

To find the usage metrics for the service account key, follow these steps:

Console

  1. In the Cloud Console, go to the Metrics explorer page.

    Go to the metrics explorer page

  2. In the Find resource type and metric field, set the resource type to IAM Service accounts and set the metric to Key authentication events.

  3. In the Filter field, select keyid and enter the unique ID for the service account key.

  4. To make the graph easier to read, choose Line or Stacked bar as the plot type.

The most recent authentication event on the graph shows when the service account key was last used.

REST

The Cloud Monitoring API's timeSeries.list method , when used with specific filters, allows you to get usage metrics for a single service account key. You can then use those metrics to determine when the key was last used.

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

  • project-id: Your Google Cloud project ID.
  • key-id: The unique ID of your service account key.
  • end-time: The end of the time interval that you want to check, in percent-encoded RFC 3339 format. For example, 2020-06-12T00%3A00%3A00.00Z.
  • start-time: The start of the time interval that you want to check, in percent-encoded RFC 3339 format. For example, 2020-04-12T00%3A00%3A00.00Z.

HTTP method and URL:

GET https://monitoring.googleapis.com/v3/projects/project-id/timeSeries?filter=metric.type%3D%22iam.googleapis.com%2Fservice_account%2Fkey%2Fauthn_events_count%22%20AND%20metric.labels.key_id%3D%22key-id%22&interval.endTime=end-time&interval.startTime=start-time

To send your request, expand one of these options:

The response contains a timeSeries object with all of the recent authentication events for the specified service account key. You can use this timeSeries object to determine when the service account key was last used.

Exporting metrics

You can use Monitoring to export your metrics to BigQuery. Exporting metrics is useful for performing long-term analysis because Monitoring only retains metrics for a limited time.

For instructions, see Monitoring metric export in the Solutions documentation.

What's next