Service identity

Runtime service account

During its execution, a Cloud Run revision uses a service account as its identity. This means that when your code uses Google Cloud client libraries, it automatically obtains and uses credentials from the runtime service account of the current Cloud Run revision. This strategy is called "Application Default Credentials".

By default, Cloud Run revisions are using the Compute Engine default service account ([e-mail]), which has the Project > Editor IAM role. This means that by default, your Cloud Run revisions have read and write access to all resources in your Google Cloud project. While this is very convenient, we recommend granting more granular permissions to each of your Cloud Run services by assigning dedicated service accounts with more restricted IAM roles.

Using per-service identity

Google recommends that you give each of your services a dedicated identity by assigning it a user-managed service account instead of using a default service account. User-managed service accounts allow you to control access by granting a minimal set of permissions using Identity and Access Management.

You can use a user-managed service account in the same project as the Cloud Run (fully managed) service. You can also use a user-managed service account in a different project, which requires additional configuration. If the service account and Cloud Run (fully managed) service are in different projects, you must grant the Service Account Token Creator role to the following Google-managed service accounts on your user-managed service account:

• Compute Engine default service account ([e-mail])
• Cloud Run Service Agent ([e-mail])

Permissions required for user-managed service accounts

In order to deploy a service with a user-managed service account, the user deploying the service must have the iam.serviceAccounts.actAs permission on that service account.

When a user creates a service account, that user is automatically granted this permission. Otherwise, a user with the correct permissions must grant the user deploying the service the iam.serviceAccounts.actAs permission. To learn how to grant permissions, see Granting, changing, and revoking access to resources.

Deploying a new service with a user-managed service account

If you don't already have a user-managed service account you want to use, learn how to create and manage service accounts.

You can set environment variables using the Cloud Console or the gcloud command line when you create a new service or deploy a new revision. Update the service account with your service account email associated with the new identity:

Console

1. Go to Cloud Run

2. Click Create Service if you are configuring a new service you are deploying to. If you are configuring an existing service, click on the service, then click Edit and Deploy New Revision.

3. Under Advanced Settings, click Container.

   

4. Click the Service account dropdown and select the desired service account.

5. Click Create or Deploy.

gcloud

You can update an existing service to have a new runtime service account by using the following command:

gcloud run services update SERVICE --service-account SERVICE_ACCOUNT

Replace:

• SERVICE with the name of your service.
• SERVICE_ACCOUNT with the service account associated with the new identity: this value is the email address for the service account, for example, [e-mail].

You can also set a service account during deployment using the command:

gcloud run deploy --image IMAGE_URL --service-account SERVICE_ACCOUNT

Replace:

• IMAGE_URL with a reference to the container image, for example, gcr.io/myproject/my-image:latest.
• SERVICE_ACCOUNT with the service account associated with the new identity: this value is the email address for the service account, for example, [e-mail].

YAML

You can download and view existing service configuration using the gcloud run services describe --format export command, which yields cleaned results in YAML format. You can then modify the fields described below and upload the modified YAML using the gcloud beta run services replace command. Make sure you only modify fields as documented.

1. To view and download the configuration:

   gcloud run services describe SERVICE --format export > service.yaml

2. Update the serviceAccountName: attribute:

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     name: SERVICE
   spec:
     template:
       spec:
         serviceAccountName: SERVICE_ACCOUNT

   Replace

   • SERVICE with the name of your Cloud Run service.
   • SERVICE_ACCOUNT with the service account associated with the new identity: this value is the email address for the service account, for example, [e-mail].

3. Replace the service with its new configuration using the following command:

   gcloud beta run services replace service.yaml

Fetching identity and access tokens

When your code runs on Cloud Run (fully managed) it can use the Compute Metadata Server to fetch identity tokens and access tokens. You cannot query the metadata server directly from your local computer.

Identity tokens

You use identity tokens when calling other Cloud Run (fully managed) services or any other service that can validate an identity token.

You can use the Compute Metadata Server to fetch identity tokens with a specific audience as follows:

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

Where AUDIENCE is the JWT Audience requested, for example: the URL of a service you're invoking, such as https://service.domain.com, or the OAuth Client ID of an IAP protected resource, such as 1234567890.apps.googleusercontent.com.

Access tokens

You use access tokens when calling Google APIs.

By default, access tokens have the cloud-platform scope, which allows access to all Google Cloud Platform APIs, assuming IAM also allows access. In order to access other Google or Google Cloud APIs, you will need to fetch an access token with the appropriate scope.

You can use the Compute Metadata Server to fetch access tokens.

If you need an access token with a specific scope, you can generate one as follows:

curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token?scopes=[SCOPES]" \
  -H "Metadata-Flavor: Google"

Where SCOPES is a comma separated list of OAuth scopes requested, for example: https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/spreadsheets.

Consult the full list of Google OAuth scopes to find which scopes you need.

Note: the ?scopes= query parameter is only available on App Engine, Cloud Functions, and Cloud Run.

Next steps

Learn how to manage access to or securely authenticate developers, services, and end-users to your services.

For an end-to-end walkthrough of an application using service identity to minimize security risk, follow the securing Cloud Run services tutorial.