Authorize service-to-service access

If your architecture is using multiple services, you likely require credentials to enable communication between services. Cloud Build provides built-in support for the OpenID Connect (OIDC) standard for secure authentication and authorization between services.

You can use Cloud Build to generate ID tokens. With these tokens, you can call secure endpoints from within Cloud Build.

For example, if you are running a serverless platform application like Cloud Functions, Cloud Run, or App Engine, you can securely interact with your application from within Cloud Build workloads.

Before you begin

  • Enable the Cloud Build and IAM APIs.

    Enable the APIs

  • If you plan to use this account to create short-lived credentials, then you also need to enable the IAM Service Account Credentials API.

    Enable the API

  • To use the command-line examples in this guide, install and configure the Google Cloud CLI.

  • Make sure you've created the service account you want to use. You must create the account in the same Google Cloud project where you're running builds.

Required IAM permissions

Your user-specified service account must have the iam.serviceAccounts.getOpenIdToken permission.

For instructions on granting IAM roles to a service account, see Manage access to service accounts.

Methods for obtaining an ID token

There are two ways to configure your build steps to obtain ID tokens:

  • use the gcloud CLI
  • send a direct request to the metadata server

Get an ID token via gcloud

In this section, the following code snippet demonstrates how to use the gcloud CLI to obtain ID tokens:

YAML 

steps:

- name: 'gcr.io/cloud-builders/gcloud'
  script: 'gcloud auth print-identity-token --audiences ${_TOKEN_AUDIENCE} > /workspace/identity_token.txt'
  env:
  - _TOKEN_AUDIENCE=${_TOKEN_AUDIENCE}
service_account: '$_SERVICE_ACCOUNT'
substitutions:
  _TOKEN_AUDIENCE: 'TOKEN_AUDIENCE'
  _SERVICE_ACCOUNT_ID: 'SERVICE_ACCOUNT_ID'
  _SERVICE_ACCOUNT: 'projects/${PROJECT_ID}/serviceAccounts/${_SERVICE_ACCOUNT_ID}'
logsBucket: 'LOGS_BUCKET_LOCATION'
options:
  logging: GCS_ONLY
  dynamic_substitutions: true

JSON 

{
  "steps": [
      {
          "name": "gcr.io/cloud-builders/gcloud",
          "script": "gcloud auth print-identity-token --audiences ${_TOKEN_AUDIENCE} > /workspace/identity_token.txt"
          "env": [
              "_TOKEN_AUDIENCE=${_TOKEN_AUDIENCE}"
          ]
      }
  ],
  "service_account": "$_SERVICE_ACCOUNT",
  "substitutions": {
      "_TOKEN_AUDIENCE": "TOKEN_AUDIENCE",
      "_SERVICE_ACCOUNT_ID": "SERVICE_ACCOUNT_ID",
      "_SERVICE_ACCOUNT": "projects/${PROJECT_ID}/serviceAccounts/${_SERVICE_ACCOUNT_ID}"
  },
  "logsBucket": "LOGS_BUCKET_LOCATION",
  "options": {
      "logging": "GCS_ONLY",
      "dynamic_substitutions": true
  }
}

Replace the following:

  • TOKEN_AUDIENCE is the URL or target audience to obtain the ID token for, such as http://www.example.com.
  • SERVICE_ACCOUNT_ID is the email address or unique ID for the user-specified service account. For example, service-account-name@project-id.iam.gserviceaccount.com.
  • LOGS_BUCKET_LOCATION is the Cloud Storage bucket to store build logs. For example, gs://mylogsbucket.

Send a direct request to the metadata server

In this section, the following code snippet demonstrates how to make a direct request to the metadata server to obtain ID tokens:

YAML 

steps:
- name: 'gcr.io/cloud-builders/curl'
  id: 'printTokenFromCurl'
  script: |
    curl -H 'Metadata-Flavor: Google' http://metadata/computeMetadata/v1/instance/service-accounts/default/identity?audience=${_TOKEN_AUDIENCE} -o /workspace/identity_token.txt
  env:
  - _TOKEN_AUDIENCE=${_TOKEN_AUDIENCE}
service_account: '$_SERVICE_ACCOUNT'
substitutions:
  _TOKEN_AUDIENCE: 'TOKEN_AUDIENCE'
  _SERVICE_ACCOUNT_ID: 'SERVICE_ACCOUNT_ID'
  _SERVICE_ACCOUNT: 'projects/${PROJECT_ID}/serviceAccounts/${_SERVICE_ACCOUNT_ID}'
logsBucket: 'LOGS_BUCKET_LOCATION'
options:
  logging: GCS_ONLY
  dynamic_substitutions: true

JSON 

{
  "steps": [
      {
          "name": "gcr.io/cloud-builders/curl",
          "id": "printTokenFromCurl"
          "script": "curl -H 'Metadata-Flavor: Google' http://metadata/computeMetadata/v1/instance/service-accounts/default/identity?audience=${_TOKEN_AUDIENCE} -o /workspace/identity_token.txt"
          "env":
              "_TOKEN_AUDIENCE=${_TOKEN_AUDIENCE}"
      }
  ],
  "service_account": "$_SERVICE_ACCOUNT",
  "substitutions": {
      "_TOKEN_AUDIENCE": "TOKEN_AUDIENCE",
      "_SERVICE_ACCOUNT_ID": "SERVICE_ACCOUNT_ID",
      "_SERVICE_ACCOUNT": "projects/${PROJECT_ID}/serviceAccounts/${_SERVICE_ACCOUNT_ID}"
  },
  "logsBucket": "LOGS_BUCKET_LOCATION",
  "options": {
      "logging": "GCS_ONLY",
      "dynamic_substitutions": true
  }
}

Replace the following:

  • TOKEN_AUDIENCE is the URL or target audience to obtain the ID token for, such as http://www.example.com.
  • SERVICE_ACCOUNT_ID is the email address or unique ID for the user-specified service account. For example, service-account-name@project-id.iam.gserviceaccount.com.
  • LOGS_BUCKET_LOCATION is the Cloud Storage bucket to store build logs. For example, gs://mylogsbucket.

For additional instructions on generating and using ID tokens in your workloads, see Methods for getting an ID token.

What's next