Grant a workflow permission to access Google Cloud resources

Workflows uses service accounts to give workflows access to Google Cloud resources. Service accounts are special accounts that serve as the identity of a non-person, like a function, an application, or a VM. They give you a way to authenticate these non-persons. You can think of a service account as both an identity and a resource:

• When thinking of a service account as an identity, you can grant a role to a service account, allowing it to access a resource (such as a workflow).

• When thinking of a service account as a resource, you can grant roles to other users to access or manage that service account.

A service account is identified by its email address, which is unique to the account.

For more information about setting up authentication with a production application, see Authenticate as a service account.

Note: When managing access for users in external identity providers, replace instances of Google Account principal identifiers—like user:[e-mail], group:[e-mail], and domain:example.com—with appropriate Workforce Identity Federation principal identifiers.

Default service account

Every workflow is associated with an Identity and Access Management (IAM) service account when you create the workflow. If you don't specify a service account during the workflow's creation, the workflow uses the default Compute Engine service account for its identity. To verify which service account is associated with a workflow, in this document, see Verify the service account associated with a workflow.

• We recommend using the default service account for testing and development only. For production environments, we strongly recommend creating a new service account and granting it one or more IAM roles that contain the minimum permissions required to access the resources orchestrated by your workflows.

• The only roles required by your service account are those required to access the resources orchestrated by your workflows. For more information, in this document, see Service account permissions.

Note:

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.

Service account permissions

Because service accounts are identities, you can let a service account access resources in your project by granting it a role, just like you would for any other principal. For example, if you want to let your workflow send logs to Cloud Logging, make sure that the service account executing the workflow has a role that includes the logging.logEntries.create permission—for example, the Logs Writer (roles/logging.logWriter) IAM role. In general, the roles required by your service account depend on the resources that you're orchestrating with your workflows. To determine which roles are required, review the product documentation for the resource you're orchestrating, or choose predefined roles.

The workflow service account doesn't require the Workflows Invoker (roles/workflows.invoker) IAM role, unless the workflow invokes itself or other workflows (that is, creates new workflow executions). For more information, see Invoke Workflows.

Attach service accounts to resources

To create a workflow and attach a service account, you need permissions to create the workflow and to attach the service account to the workflow.

To get the permission that you need to attach a service account to a resource, ask your administrator to grant you the Service Account User (roles/iam.serviceAccountUser) IAM role on the service account or the project that contains the service account. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the iam.serviceAccounts.actAs permission, which is required to attach a service account to a resource.

You might also be able to get this permission with custom roles or other predefined roles.

When you update the source code or service account of an existing workflow, you also need the iam.serviceAccounts.actAs permission:

• Update only the workflow source code (without updating the service account): you need the iam.serviceAccounts.actAs permission on the existing service account associated with the workflow.
• Update the service account, or both the source code and the service account: you need the iam.serviceAccounts.actAs permission on the new service account that you're associating with the workflow.

For more information about service account authentication roles, see Roles for service account authentication.

Invoke Cloud Run functions

In Cloud Run functions, invocation permissions are available by managing the underlying Cloud Run service. If your workflow is invoking a Cloud Run functions service, you don't need to grant the caller's service account the Cloud Functions Invoker (roles/cloudfunctions.invoker) IAM role. Instead, you must grant the Cloud Run Invoker (roles/run.invoker) IAM role.

For more information, see Compare Cloud Run functions.

Deploy a workflow with a custom service account

You can create your own user-managed service account to give you greater flexibility in controlling access to your workflow.

1. Create your service account and note its name.

2. Grant the service account the appropriate roles, based on what resources the workflow must access to do its work.

3. Ensure that all principals who deploy or update workflows have permission to attach or act as the service account (roles/iam.serviceAccountUser). If you created the service account, you're automatically granted this permission.

   Grant the role on the project:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=PRINCIPAL \
       --role='roles/iam.serviceAccountUser'

   Or, grant the role on the service account:

   gcloud iam service-accounts add-iam-policy-binding \
       SERVICE_ACCOUNT_RESOURCE_NAME \
       --member=PRINCIPAL \
       --role='roles/iam.serviceAccountUser'

   Replace the following:

   • PROJECT_ID: the Google Cloud project ID that contains the workflow and service account.

   • PRINCIPAL: an identifier for the workflow deployer in the format user|group|serviceAccount:email or domain:domain. For example:

     • user:[e-mail]
     • group:[e-mail]
     • serviceAccount:[e-mail]
     • domain:example.com

   • SERVICE_ACCOUNT_RESOURCE_NAME: the full resource name of the service account, in the following format:

     projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

     Where SERVICE_ACCOUNT_NAME is the name of the service account.

4. Deploy your workflow using the custom service account.

Deploy a workflow with a cross-project service account

By default, you can't create a service account in one project and attach it to a resource in another project. The following instructions show you how to attach a service account in one project to a workflow in another project. You can then use the service account across different projects to deploy a workflow.

If the service account and the workflow resources are in different projects, do the following:

1. In the Google Cloud console, go to the Organization policies page for the project where the service account is located:

   Go to Organization policies

   Check the organization policy for the project and ensure that the iam.disableCrossProjectServiceAccountUsage boolean constraint isn't enforced for the project. For more information, see Enable service accounts to be attached across projects.

2. In the project where the service account is located, create your service account and note its name.

3. Grant the service account the appropriate roles, based on what resources the workflow must access to do its work.

4. Grant the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator) to the Workflows service agent in the workflow's project. This permits the service agent to manage cross-project access for the service account. A service agent is the identity of a given Google Cloud service for a particular project. For more information, see Service agents.

   Console

   1. In the Google Cloud console, go to the Workflows page:

      Go to Workflows

   2. To create a workflow, click Create, or to update an existing workflow, click the name of the workflow.

   3. In the Service account list, click Switch project.

   4. Select a service account from a different project.

   5. If prompted, grant the roles/iam.serviceAccountTokenCreator role to the Workflows service agent.

   gcloud

   1. Grant the roles/iam.serviceAccountTokenCreator role to the Workflows service agent:

      gcloud iam service-accounts add-iam-policy-binding \
          SERVICE_ACCOUNT_RESOURCE_NAME \
          --member='serviceAccount:[e-mail]' \
          --role='roles/iam.serviceAccountTokenCreator'

      Replace the following:

      • SERVICE_ACCOUNT_RESOURCE_NAME: the full resource name of the service account, in the following format:

        projects/SERVICE_ACCOUNT_PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@SERVICE_ACCOUNT_PROJECT_ID.iam.gserviceaccount.com

        Where:

        • SERVICE_ACCOUNT_PROJECT_ID is the Google Cloud project ID that contains the service account.
        • SERVICE_ACCOUNT_NAME is the name of the service account.

      • WORKFLOWS_PROJECT_NUMBER: the Google Cloud project number that contains the workflow resources.

5. Ensure that all principals who deploy or update workflows have permission to attach or act as the service account (roles/iam.serviceAccountUser). If you created the service account, you're automatically granted this permission.

   Console

   1. In the Google Cloud console, go to the Workflows page:

      Go to Workflows

   2. To create a workflow, click Create, or to update an existing workflow, click the name of the workflow.

   3. In the Service account list, click Switch project.

   4. Select a service account from a different project.

   5. If prompted, grant the roles/iam.serviceAccountUser role on the service account's project.

   gcloud

   Grant the role on the project that contains the service account:

   gcloud projects add-iam-policy-binding \
       SERVICE_ACCOUNT_PROJECT_ID \
       --member=PRINCIPAL \
       --role='roles/iam.serviceAccountUser'

   Or, grant the role on the service account:

   gcloud iam service-accounts add-iam-policy-binding \
       SERVICE_ACCOUNT_RESOURCE_NAME \
       --member=PRINCIPAL \
       --role='roles/iam.serviceAccountUser'

   Replace the following:

   • SERVICE_ACCOUNT_PROJECT_ID: the Google Cloud project ID that contains the service account.
   • PRINCIPAL: an identifier for the workflow deployer in the format user|group|serviceAccount:email or domain:domain. For example:
     • user:[e-mail]
     • group:[e-mail]
     • serviceAccount:[e-mail]
     • domain:example.com

   • SERVICE_ACCOUNT_RESOURCE_NAME: the full resource name of the service account, in the following format:

     projects/SERVICE_ACCOUNT_PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@SERVICE_ACCOUNT_PROJECT_ID.iam.gserviceaccount.com

     Where SERVICE_ACCOUNT_NAME is the name of the service account.

6. Deploy your workflow using the cross-project service account.

Verify the service account associated with a workflow

You can verify which service account is associated with a particular workflow.

Console

1. In the Google Cloud console, go to the Workflows page:

   Go to Workflows

2. On the Workflows page, click the workflow name.

3. On the Workflow details page, click the Details tab.

   The Details tab displays the workflow's associated service account.

gcloud

Retrieve the workflow description by running the gcloud workflows describe command:

gcloud workflows describe WORKFLOW_NAME \
    --location=LOCATION

Replace the following:

• WORKFLOW_NAME: the name of your workflow.
• LOCATION: the region where your workflow is deployed (for example, us-central1).

The output is similar to the following and includes the associated service account:

createTime: '2020-06-05T23:45:34.154213774Z'
name: projects/my-project/locations/us-central1/workflows/my-workflow
serviceAccount: projects/my-project/serviceAccounts/[e-mail]
sourceContents: [...]

What's next

• Manage access to projects, folders, and organizations

• Make authenticated requests from a workflow

• Workflows roles and permissions