Function Identity

Just as other entities need access to Cloud Functions to interact with it, 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 Functions uses the App Engine default service account, [e-mail], as its identity for function execution.

The App Engine service account has the Editor role, which allows it broad access to many Google Cloud services. While this is the fastest way to develop functions, Google recommends using this default service account for testing and development only. For production, you should grant the service account only the minimum set of permissions required to achieve its goal.

To secure your functions in production:

• Change permissions on the App Engine default service account
• Create individual service accounts for your functions

Changing permissions on the App Engine default service account

Warning: Because this is the App Engine service account, changes to it change the permissions for all functions in a project, as well as all App Engine instances. Therefore, the minimum set of permissions must contain the permissions required for Cloud Functions and App Engine in a project.

Console

1. Go to the Google Cloud Console:

   Go to Google Cloud Console

2. Select the App Engine default Service Account ([e-mail]) from the table.

3. Click the pencil 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="[e-mail]"
  --role="roles/editor"

# Add the desired role
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="[e-mail]"
  --role="ROLE"

Where PROJECT_ID is the project ID of the project you're using and ROLE is the new role to assign to the 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 both of these Google-managed service accounts:

      • App Engine default service account ([e-mail])
      • Cloud Functions Service Agent ([e-mail])

      These Google accounts manage cross-project access for your service account.

4. Add the service account you created to the resource it needs to access as a member. 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 and connections settings 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 Create.

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 and connections settings 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 identification and authorization 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 identity 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 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 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.