Introduction to service identity

This page describes the two Cloud Run identities and how theCloud Client Libraries use the service identity to call Google Cloud APIs. Examplesof Google Cloud products that have Cloud Client Libraries includeCloud Storage, Firestore, Cloud SQL, Pub/Sub, andCloud Tasks. This page is for admins, operators, or developers whomanage organization policies and user access, or anyone who would like to learnabout such topics.

Cloud Run identities

To use Cloud Run, Google Cloud requires theCloud Run user and the Cloud Run instance to eachhave an identity.

  • The identity of the Cloud Run user is referred to as theCloud Run deployer account. When managing arevision or job, you use this identity to make requests to theCloud Run Admin API.
  • The identity of the Cloud Run instance is referred to as theCloud Run service identity. When the Cloud Runcode you wrote interacts with Cloud Client Libraries, or calls anotherCloud Run service forservice-to-service communication,you use this identity to make requests from Cloud Run toGoogle Cloud APIs or other Cloud Run services.

To access and make requests to the Google Cloud APIs orcommunicate between services, each identity must have the appropriatepermissions granted to them in Identity and Access Management (IAM).

Call the Cloud Run Admin API with the deployer account

You call the Cloud Run Admin API from Cloud Run using theCloud Run deployer account. The deployer account can be either auser account or a service account, and represents the account that was signedinto the Google Cloud environment.

When the deployer account uses Cloud Run, IAMchecks if the deployer account has the necessary permissions to perform theCloud Run operation. The following diagram shows how a useraccount calls the Cloud Run Admin API to deploy a new revision from theGoogle Cloud console:

Call Cloud Run Admin API from the Google Cloud console.
Figure 1. A user uses the Google Cloud console to deploy a new revision by sending a request with an access token to the Cloud Run Admin API. IAM uses that access token to verify that the user account is authenticated to access the Cloud Run Admin API before performing the operation.

Call Google Cloud APIs with the service identity

When a Cloud Run instance interacts with other IAM-authenticatedCloud Run services, or calls Cloud Client Libraries eitherthrough application code or built-in features likeCloud Run integrations orCloud Storage volume mounts, the Google Cloud environment usesApplication Default Credentials (ADC)to automatically detect whether theCloud Run service identityis authenticated to perform the API operation. The Cloud Runservice identity is a service account that was assigned as theCloud Run instance's identity when you deploy a revision orexecute a job.

A service account that is used as the deployer account will only be used asthe service identity if you configure the same service account in yourCloud Run configuration.

The rest of this guide describes how a Cloud Run service or jobuses service identity to call and access Google services and APIs. For moreinformation on service identity configuration, see the service identityconfiguration pages forservicesandjobs.

Types of service accounts for service identity

When your Cloud Run instance makes calls to Google Cloud APIs toperform the operations it needs, Cloud Run automatically uses aservice account as the service identity. The two types of service accounts thatcan be used as the service identity are as follows:

  • User-managed service account (recommended): You manually create thisservice account and determine the most minimal set of permissions that theservice account needs to access specific Google Cloud resources. Theuser-managed service account follows the format ofSERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com.
  • Compute Engine default service account: Cloud Runautomatically provides the Compute Engine default service account as thedefault service identity. The Compute Engine default service account followsthe format ofPROJECT_NUMBER-compute@developer.gserviceaccount.com.

Avoid the default service account when configuring service identity

By default, the Compute Engine default service account is automaticallycreated. If you don't specify a service account when theCloud Run service or job is created, Cloud Runuses this service account.

Depending on your organization policy configuration, the default service account might automatically be granted theEditor role on your project. We strongly recommend that you disable the automatic role grant by enforcing theiam.automaticIamGrantsForDefaultServiceAccounts organization policy constraint. If you created your organization after May 3, 2024, this constraint is enforced by default.

If you disable the automatic role grant, you must decide which roles to grant to the default service accounts, and thengrant these roles yourself.

If the default service account already has the Editor role, we recommend that you replace the Editor role with less permissive roles.To safely modify the service account's roles, usePolicy Simulator to see the impact of the change, and thengrant and revoke the appropriate roles.

How service identity works

When your code uses Cloud Client Libraries that makes requests toGoogle Cloud API, the following happens:

  1. The client library requests an OAuth 2.0 access token for the serviceidentity from the instance metadata server.
  2. The instance metadata server provides an IAM access token forthe service account that is configured as the service identity.
  3. The request to the Google Cloud API is sentwith an OAuth 2.0 access token.
  4. IAM verifies the service identity referenced in the accesstoken for the necessary permissions, and checks policy bindings before itforwards the call to the API endpoint.
  5. The Google Cloud API performs the operation.
Call Google Cloud API from Cloud Run.
Figure 1. Cloud Run generates an access token from the metadata server, and IAM uses that access token to verify that the assigned Cloud Run service identity is authenticated to access the Google Cloud APIs.

Generate an access token for the Cloud Run request to call Google Cloud APIs

Warning: If your Cloud Run service, job, or worker pool usesservice identity to authenticate accessto Google Cloud APIs, never setGOOGLE_APPLICATION_CREDENTIALS as anenvironment variable on a Cloud Run service, job, or worker pool. Alwaysconfigure auser-managed service account instead.

If your Cloud Run code usesCloud Client Libraries, you configure serviceidentity in Cloud Run by assigning a service account atdeployment or execution. This lets the library automatically acquire an accesstoken to authenticate your code's request. If your Cloud Run code communicates with other authenticated Cloud Run services, youmust add theaccess token to yourrequests.

To assign a service account as the service identity, see the following guides:

However, if you use your own custom code or need to make requestsprogrammatically, you can use themetadata serverdirectly to manually fetch identity tokens and access token described in thenext section. Note that you cannot query this server directly from your localmachine as the metadata server is only available for workloads running onGoogle Cloud.

Fetch ID and access tokens using the metadata server

The two types of tokens you can fetch with the metadata server are as follows:

To fetch a token, follow the instructions in the appropriate tab for the type oftoken you are using:

Access tokens

For example, if you want to create a Pub/Sub topic, use theprojects.topics.createmethod.

  1. Use the Compute Metadata Server tofetch an access token:

    curl"http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token"\--header"Metadata-Flavor: Google"

    This endpoint returns a JSON response with anaccess_token attribute.

  2. In your HTTP protocol request, the request must be authenticated with anaccess token in theAuthorization header:

    PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_IDAuthorization: BearerACCESS_TOKEN

    Where:

    • PROJECT_ID is your project ID.
    • TOPIC_ID is your topic ID.
    • ACCESS_TOKEN is the access token you fetchedin the previous step.

    Response:

    {    "name": "projects/PROJECT_ID/topics/TOPIC_ID"}

ID tokens

Use the Compute Metadata Server tofetch an identity tokenwith a specific audience:

curl"http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=AUDIENCE"\--header"Metadata-Flavor: Google"

WhereAUDIENCE is the JWT Audience requested.

For Cloud Run services, the audience should be either theURL of the service you are invoking or acustom audience,such as a custom domain, configured for the service.

https://service.domain.com

For other resources, it is likely the OAuth Client ID of an IAP-protectedresource:

1234567890.apps.googleusercontent.com

Next steps

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.