Workflows uses [service accounts](https://docs.cloud.google.com/iam/docs/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](https://docs.cloud.google.com/docs/authentication/production).

> [!NOTE]
> **Note:** When managing access for users in [external identity providers](https://docs.cloud.google.com/iam/docs/workforce-identity-federation.md.txt), replace instances of Google Account principal identifiers---like `user:kiran@example.com`, `group:support@example.com`, and `domain:example.com`---with appropriate [Workforce Identity Federation principal identifiers](https://docs.cloud.google.com/iam/docs/principal-identifiers.md.txt).

## 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](https://docs.cloud.google.com/workflows/docs/authentication.md.txt#verify-service-account).

- **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](https://docs.cloud.google.com/iam/docs/best-practices-service-accounts.md.txt#limit-service-account-privileges)
  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](https://docs.cloud.google.com/workflows/docs/authentication.md.txt#sa-permissions).

> [!NOTE]
> **Note:**
> Depending on your organization policy configuration, the default service account might
> automatically be granted the [Editor role](https://docs.cloud.google.com/iam/docs/roles-overview.md.txt#basic) on your
> project. We strongly recommend that you disable the automatic role grant by [enforcing the `iam.automaticIamGrantsForDefaultServiceAccounts` organization policy
> constraint](https://docs.cloud.google.com/resource-manager/docs/organization-policy/restricting-service-accounts#disable_service_account_default_grants). 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](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access) 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](https://docs.cloud.google.com/policy-intelligence/docs/simulate-iam-policies.md.txt) to see the impact of
> the change, and then [grant and revoke the
> appropriate roles](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access).

## 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](https://docs.cloud.google.com/iam/docs/roles-permissions/logging.md.txt#logging.logWriter)
(`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](https://docs.cloud.google.com/iam/docs/choose-predefined-roles.md.txt).

The workflow service account doesn't require the
[Workflows Invoker](https://docs.cloud.google.com/iam/docs/roles-permissions/workflows.md.txt#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](https://docs.cloud.google.com/workflows/docs/use-iam-for-access.md.txt#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](https://docs.cloud.google.com/iam/docs/roles-permissions/iam.md.txt#iam.serviceAccountUser) (`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](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


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](https://docs.cloud.google.com/iam/docs/creating-custom-roles.md.txt) or
other [predefined roles](https://docs.cloud.google.com/iam/docs/roles-overview.md.txt#predefined).

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](https://docs.cloud.google.com/iam/docs/service-account-permissions).

### 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](https://docs.cloud.google.com/iam/docs/roles-permissions/cloudfunctions.md.txt#cloudfunctions.invoker)
(`roles/cloudfunctions.invoker`) IAM role. Instead, you must
grant the
[Cloud Run Invoker](https://docs.cloud.google.com/iam/docs/roles-permissions/run.md.txt#run.invoker)
(`roles/run.invoker`) IAM role.

For more information, see
[Compare Cloud Run functions](https://docs.cloud.google.com/run/docs/functions/comparison.md.txt).


## 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](https://docs.cloud.google.com/iam/docs/creating-managing-service-accounts#creating)
   and note its name.

2. [Grant the service account](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt)
   the [appropriate roles](https://docs.cloud.google.com/iam/docs/roles-permissions.md.txt),
   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:

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

   Or, grant the role on the service account:

   ```bash
   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:dana@example.com`
     - `group:admins@example.com`
     - `serviceAccount:my-service-account@example.com`
     - `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](https://docs.cloud.google.com/workflows/docs/creating-updating-workflow.md.txt#create_a_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](https://console.cloud.google.com/iam-admin/orgpolicies)

   <br />

   Check the
   [organization policy](https://docs.cloud.google.com/resource-manager/docs/organization-policy/overview)
   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](https://docs.cloud.google.com/iam/docs/attach-service-accounts.md.txt#enabling-cross-project).
2. In the project where the service account is located,
   [create your service account](https://docs.cloud.google.com/iam/docs/creating-managing-service-accounts#creating)
   and note its name.

3. [Grant the service account](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt)
   the [appropriate roles](https://docs.cloud.google.com/iam/docs/roles-permissions.md.txt),
   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](https://docs.cloud.google.com/iam/docs/service-agents.md.txt).

   ### Console

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


      [Go to Workflows](https://console.cloud.google.com/workflows)

      <br />

   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:

      ```bash
      gcloud iam service-accounts add-iam-policy-binding \
          SERVICE_ACCOUNT_RESOURCE_NAME \
          --member='serviceAccount:service-WORKFLOWS_PROJECT_NUMBER@gcp-sa-workflows.iam.gserviceaccount.com' \
          --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](https://console.cloud.google.com/workflows)

      <br />

   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:

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

   Or, grant the role on the service account:

   ```bash
   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:dana@example.com`
     - `group:admins@example.com`
     - `serviceAccount:my-service-account@example.com`
     - `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](https://docs.cloud.google.com/workflows/docs/creating-updating-workflow.md.txt#create_a_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](https://console.cloud.google.com/workflows)

   <br />

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`](https://docs.cloud.google.com/sdk/gcloud/reference/workflows/describe)
command:

```bash
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/012345678901-compute@developer.gserviceaccount.com
sourceContents: [...]
```

## What's next

- [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt)

- [Make authenticated requests from a workflow](https://docs.cloud.google.com/workflows/docs/authenticate-from-workflow.md.txt)

- [Workflows roles and permissions](https://docs.cloud.google.com/workflows/docs/access-control.md.txt)