Workflows authentication

This topic describes authentication information for Workflows. There are two types of authentication discussed on this page:

Access control

For both types of authentication, it's important to understand access control and Workflows's available roles. Roles contain permissions that grant access to resources in Google Cloud. When building a production application, only grant an identity the roles it needs in order to interact with applicable Google Cloud APIs, features, or resources.

For more information about the available Workflows roles, see Workflows access control.

Authenticate to Workflows using service accounts

Workflows supports using services accounts to access Workflows resources. Service accounts are recommended for almost all use cases, whether you are developing locally or in a production application. For more information about setting up authentication with a production application, see Authenticate as a service account. You can grant a service account one or more roles that allow access to resources in Google Cloud, including Workflows resources.

Verify a workflow's associated service account

To verify which service account is associated with a particular workflow:

Console

  1. Go to the Workflows page in the Google Cloud Console:
    Go to Workflows

  2. On the Workflows page in the console, select the workflow to display a list of its executions.

  3. On the Workflow Details page, select the Details tab to display the workflow's details.

  4. The Details tab provides the workflow's associated service account.

gcloud

  1. Open a terminal.

  2. Enter the following command:

    gcloud workflows describe MY_WORKFLOW
    

    Replace MY_WORKFLOW with the name of your workflow.

  3. The command returns the associated service account with the full workflow description:

    createTime: '2020-06-05T23:45:34.154213774Z'
    name: projects/myProject/locations/us-central1/workflows/myWorkflow
    serviceAccount: projects/my-project/serviceAccounts/012345678901-compute@developer.gserviceaccount.com
    sourceContents: ...
    

Make authenticated requests from within a workflow

To send authenticated requests, your workflow must be associated with a service account that has been granted one or more Identity and Access Management roles containing the required permissions. You must also explicitly add authentication information to your workflow definition. By default, HTTP requests do not contain identity or access tokens for security reasons.

Each workflow created is associated with an IAM service account at the time the workflow is created. If you don't specify a service account during workflow creation, the workflow uses the default Compute Engine service account for its identity.

When making requests to other Google Cloud services, the workflow must be associated with a service account that has the correct permissions to access the requested resources.

To make an authenticated request within a workflow, you can use either OAuth 2.0 or OpenID Connect (OIDC) depending on the service you are calling.

  • Use OAuth 2.0 to connect with all Google Cloud APIs, such as the Compute Engine API or the Firestore API. Any API that ends with a host name of .googleapis.com accepts this authentication method.

  • Use OIDC to connect with Cloud Run or Cloud Functions.

  • Use an Authorization request header to authenticate with a third-party API.

Make authenticated requests to Google Cloud APIs

A workflow's service account can generate OAuth 2.0 tokens that the workflow can use to authenticate to any Google Cloud API. When you use this authentication method, the workflow authenticates as its associated service account. To make an HTTP request using the OAuth 2.0 protocol, add an auth section to the args section of your workflow's definition, after you specify the URL. In this example, a request is sent to the Compute Engine API to stop a VM:

YAML

  - step_A:
      call: http.post
      args:
          url: https://compute.googleapis.com/compute/v1/projects/myproject1234/zones/us-central1-b/instances/myvm001/stop
          auth:
              type: OAuth2
              [scope: OAUTH_SCOPE]
    

JSON

    [
      {
        "step_A": {
          "call": "http.post",
          "args": {
            "url": "https://compute.googleapis.com/compute/v1/projects/myproject1234/zones/us-central1-b/instances/myvm001/stop",
            "auth": {
              "type": "OAuth2",
              ["scope": "OAUTH_SCOPE"]
            }
          }
        }
      }
    ]
      
The scope parameter is optional, but can be used to specify the OAuth 2.0 scope for the token. By default, it's set to https://www.googleapis.com/auth/cloud-platform.

Make requests to Cloud Run or Cloud Functions

When making requests to Cloud Run or Cloud Functions, use OIDC to authenticate.

To make an HTTP request using OIDC, add an auth section to the args section of your workflow's definition, after you specify the URL. In this example, a request is sent to invoke a Cloud Functions:

YAML

  - step_A:
      call: http.get
      args:
          url: https://us-central1-project.cloudfunctions.net/functionA
          query:
              firstNumber: 4
              secondNumber: 6
              operation: sum
          auth:
              type: OIDC
              [audience: OIDC_AUDIENCE]
    

JSON

    [
      {
        "step_A": {
          "call": "http.get",
          "args": {
            "url": "https://us-central1-project.cloudfunctions.net/functionA",
            "query": {
              "firstNumber": 4,
              "secondNumber": 6,
              "operation": "sum"
            },
            "auth": {
              "type": "OIDC",
              ["audience": "OIDC_AUDIENCE"]
            }
          }
        }
      }
    ]
      
The audience parameter is optional, but can be used to specify the OIDC audience for the token. By default, it's set to the same value as url.

Make authenticated requests to external APIs

If you're integrating a third-party API, include an Authorization request header with the credentials necessary to carry out the authentication. For example, include an ID token in an Authorization: Bearer ID_TOKEN header in the request to the service. For more information, consult the API provider's documentation.

What's next