Service identity

About the default service account

By default, Cloud Run revisions execute as the Compute Engine default service account. The Compute Engine default service account has the Project Editor IAM role which grants read and write permissions on all resources in your Google Cloud project.

While this may be convenient, rather than use the default service account, Google recommends creating your own user-managed service account with the most granular permissions and assigning that service account as your Cloud Run service's identity. This document describes how to configure per-service identities with Cloud Run.

Using per-service identity

Google recommends giving every Cloud Run service a dedicated identity by assigning it a user-managed service account instead of using the default service account. User-managed service accounts allow you to control access by granting a minimal set of permissions using Identity and Access Management.

The gcloud command-line tool and Google Cloud client libraries automatically detect when they are running on Google Cloud and use the runtime service account of the current Cloud Run revision. That means that if your code uses the gcloud tool or an official Google Cloud client library, it will automatically detect and authenticate as the Cloud Run service's runtime service account. This strategy is called Application Default Credentials, and enables code portability across multiple environments.

Permissions required on user-managed service accounts

To deploy a Cloud Run service using a user-managed service account, you must have permission to impersonate (iam.serviceAccounts.actAs) that service account. This permission can be granted via the roles/iam.serviceAccountUser IAM role. All principals (e.g. users, service accounts) must have this permission on the user-managed service account in order to deploy a Cloud Run service as the user-managed service account.

You can grant this permission using the Cloud Console, via the API (YAML), or using the gcloud tool as follows:

gcloud iam service-accounts add-iam-policy-binding "SERVICE_ACCOUNT_EMAIL" \
    --member "user@example.com" \
    --role "roles/iam.serviceAccountUser"

To learn how to grant permissions, refer to 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, first create a service account.

You can set the Cloud Run service's service account using the Cloud Console, the gcloud tool, or the API (YAML) when you create a new service or deploy a new revision:

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. If you are configuring a new service, fill out the initial service settings page as desired, then click Next > Advanced settings to reach the service configuration page.

  4. Click the Security tab.

    image

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

  6. 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, example@myproject.iam.gserviceaccount.com.

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, us-docker.pkg.dev/cloudrun/container/hello:latest.
  • SERVICE_ACCOUNT with the service account associated with the new identity: this value is the email address for the service account, for example, example@myservice.iam.gserviceaccount.com.

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 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, example@myproject.iam.gserviceaccount.com.
  3. Replace the service with its new configuration using the following command:

    gcloud run services replace service.yaml

Using service accounts in other projects

You can also use a user-managed service account that resides in a different Google Cloud project than the Cloud Run service. If the service account and Cloud Run service are in different projects:

  • The project containing this service account requires the org-policy iam.disableCrossProjectServiceAccountUsage to be set to false/unenforced at the folder level or inherited from project-level settings. By default, this is set to true.

  • The service account requires a role membership for roles/iam.serviceAccountTokenCreator for the deploying-project's service agent:

    service-PROJECT_NUMBER@serverless-robot-prod.iam.gserviceaccount.com
    

    where PROJECT_NUMBER is the project number for the project.

  • The service account requires a role membership for roles/iam.serviceAccountUser for the identity (user or automation) that is performing the deploy operation.

You can apply role memberships directly to the service account resource or inherit from higher levels in the resource hierarchy.

Fetching identity and access tokens

You do not need to fetch identity or access tokens if your Cloud Run service's code uses a Google Cloud client library. These client libraries will automatically detect and authenticate using the Cloud Run service's runtime service account.

Your custom code running on a Cloud Run service can use the metadata server to fetch identity tokens and access tokens. You cannot query this metadata server directly from your local machine as the metadata server is only available for workloads running on Google Cloud.

Access tokens

You use OAuth 2.0 access tokens when calling most Google APIs. To generate an access token:

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

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. To specify different scopes:

curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token?scopes=SCOPES" \
    --header "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. You can also learn more about fetching access tokens.

Identity tokens

You use identity tokens when calling other Cloud Run services or when invoking any service that can validate an identity token.

Use the Compute Metadata Server to fetch an identity token with a specific audience:

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

Where AUDIENCE is the JWT Audience requested.

For Cloud Run services, the audience should be the URL of the service you are invoking:

https://service.domain.com

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

1234567890.apps.googleusercontent.com

Getting recommendations to create dedicated service accounts

The Recommender service automatically supplies recommendations to create a dedicated service accounts with the minimal required set of permissions.

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.