Function Identity

Note: This content applies only to Cloud Run functions—formerly Cloud Functions (2nd gen).

For the 1st gen version of this document, see Function Identity (1st gen).

For security most interactions between entities in Google Cloud require that each entity have a verifiable identity, secured by some kind of secret, like a password or a key. Just as other entities need an identity to access Cloud Run functions, functions themselves often need access to other resources in Google Cloud to do their work. Every function is associated with a service account that serves as its identity when the function accesses other resources. The service account a function uses as its identity is also known as its runtime service account.

For production use, Google recommends that you give each function a dedicated identity by assigning it a user-managed service account. User-managed service accounts allow you to control access by granting a minimal set of permissions using Identity and Access Management.

Runtime service account

Unless you specify a different runtime service account when deploying a function, Cloud Run functions uses a default service account as its identity for function execution:

• Cloud Run functions uses the default compute service account, [e-mail].

  Note that the project number is distinct from the project ID and project name. You can find your project number on the Google Cloud console Dashboard page.

Depending on your organization policy configuration, the default service account might automatically be granted the Editor role on your project. We strongly recommend that you disable the automatic role grant by enforcing the iam.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 then grant 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, use Policy Simulator to see the impact of the change, and then grant and revoke the appropriate roles.

To secure your functions in production:

• Change permissions on the default runtime service account, or
• Create individual service accounts for your functions

Changing permissions on the default runtime service account

Warning: Changing permissions on the App Engine default service account or default compute service account affects all resources linked to those service accounts, potentially including other Cloud Run functions, App Engine services, and Compute Engine resources.

Console

1. Go to the IAM page in the Google Cloud console:

   Go to Google Cloud console

2. Select the App Engine default service account or Default compute service account from the table.

3. Click the pencil icon on the right side of the row to show the Edit permissions tab.

4. Add or remove roles in the Role dropdown to provide least privilege access.

5. Click Save.

gcloud

Remove the Editor role, then use the gcloud projects add-iam-policy-binding command to add a new role:

# Remove the Editor role
gcloud projects remove-iam-policy-binding PROJECT_ID \
--member="SERVICE_ACCOUNT_EMAIL" \
--role="roles/editor"

# Add the desired role
gcloud projects add-iam-policy-binding PROJECT_ID \
--member="SERVICE_ACCOUNT_EMAIL" \
--role="ROLE"

Where PROJECT_ID is the project ID of the project you're using, SERVICE_ACCOUNT_EMAIL is the email address of the default runtime service account as shown earlier in Runtime service account, and ROLE is the new role to assign to the default runtime service account.

Using individual service accounts for your functions

To give you greater flexibility in controlling access for your functions, you can give them each their own user-managed service account.

1. Create your service account. Make a note of its name.
2. Grant it the appropriate roles, based on what resources the function needs to access to do its work.

3. If the service account and the function are in different projects, from the project where the service account is located:

   1. Configure the service account to work across projects.

   2. Grant the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator) to Cloud Run Service Agent ([e-mail]), where PROJECT refers to the project in which the function resides. Cloud Run Service Agent manages cross-project access for your service account.

   3. Grant the iam.serviceaccounts.actAs permission to the Cloud Run functions service agent ([e-mail]) on the service account from the different project.

4. Grant the service account access to the resource. The method for doing this depends on the resource type.

5. Connect the service account with your function. You can do this either at deployment time or by updating a previously deployed function.

Note: In order to deploy a function with a user-managed service account, the deployer must have the iam.serviceAccounts.actAs permission on the service account being deployed. If you created the service account, you are automatically granted this permission. If not, someone who has the correct permissions must grant you this permission on the service account.

Adding a user-managed service account at deployment

Console

1. Go to the Google Cloud console:

   Go to Google Cloud console

2. Specify and configure the function however you would like.

3. Click Runtime, build... to display additional settings.

4. Select the Runtime tab.

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

6. Click Next and Deploy.

gcloud

When deploying a function using gcloud functions deploy, add the --service-account flag. For example:

gcloud functions deploy FUNCTION_NAME --service-account SERVICE_ACCOUNT_EMAIL

where FUNCTION_NAME is your function name, and SERVICE_ACCOUNT_EMAIL is the service account email.

Updating the service account of an existing function

You can update the runtime service account of an existing function.

Console

1. Go to the Google Cloud console:

   Go to Google Cloud console

2. Click the name of the desired function to go to its detail page.

3. Click the Edit pencil at the top of the detail page to edit the function.

4. Click Runtime, build... to display additional settings.

5. Select the Runtime tab.

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

7. Click Next and Deploy.

gcloud

When deploying a function using gcloud functions deploy, add the --service-account flag:

gcloud functions deploy FUNCTION_NAME --service-account SERVICE_ACCOUNT_EMAIL

where FUNCTION_NAME is your function name, and SERVICE_ACCOUNT_EMAIL is the service account.

The redeployed function now uses the new runtime service account.

Using the Metadata Server to acquire tokens

While IAM-defined service accounts are the preferred method for managing access in Google Cloud, some services might require other modes, such as an API key, OAuth 2.0 client, or service account key. Access to an external resource might also require alternate methods.

If your target service requires that you present an OpenID Connect ID token or an Oauth 2.0 access token, you might be able to use the Compute Metadata Server to fetch these tokens rather than setting up a full OAuth client.

Note: You cannot query the metadata server directly from your local computer.

Identity tokens

You can use the Compute Metadata Server to fetch ID 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 requested target, 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

OAuth 2.0 access tokens use scopes to define access permissions. By default, within Google Cloud access tokens have the cloud-platform scope. In order to access other Google or Google Cloud APIs, you 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 and Cloud Functions.

Next steps

Learn how to authorize access to your functions or to authenticate developers and other functions so that they can invoke your functions.