Authenticate with JWTs

The BigQuery API accepts JSON Web Tokens (JWTs) to authenticate requests.

As a best practice, you should use Application Default Credentials (ADC) to authenticate to BigQuery. If you can't use ADC and you're using a service account for authentication, then you can use a signed JWT instead. JWTs let you make an API call without a network request to Google's authorization server.

You can use JWTs to authenticate in the following ways:

Scope and Audience

Use scopes with service account when possible. If not possible, you can use an audience claim. For the BigQuery APIs, set the audience value to https://bigquery.googleapis.com/.

Create JWTs with client libraries

For service account keys created in Google Cloud console or by using the gcloud CLI, use a client library that provides JWT signing. The following list provides some appropriate options for popular programming languages:

Java example

The following example uses the BigQuery client library for Java to create and sign a JWT. The default scope for BigQuery API is set to https://www.googleapis.com/auth/bigquery in the client library.

import com.google.auth.oauth2.ServiceAccountCredentials; import com.google.cloud.bigquery.BigQuery; import com.google.cloud.bigquery.BigQueryOptions; import com.google.common.collect.ImmutableList; import java.io.FileInputStream; import java.io.IOException; import java.net.URI; public class Example {  public static void main(String... args) throws IOException {  String projectId = "myproject";  // Load JSON file that contains service account keys and create ServiceAccountCredentials object.  String credentialsPath = "/path/to/key.json";  ServiceAccountCredentials credentials = null;  try (FileInputStream is = new FileInputStream(credentialsPath)) {  credentials = ServiceAccountCredentials.fromStream(is);  // The default scope for BigQuery is used.   // Alternatively, use `.setScopes()` to set custom scopes.  credentials = credentials.toBuilder()  .setUseJwtAccessWithScope(true)  .build();  }  // Instantiate BigQuery client with the credentials object.  BigQuery bigquery =  BigQueryOptions.newBuilder().setCredentials(credentials).build().getService();  // Use the client to list BigQuery datasets.  System.out.println("Datasets:");  bigquery  .listDatasets(projectId)  .iterateAll()  .forEach(dataset -> System.out.printf("%s%n", dataset.getDatasetId().getDataset()));  } }

Create JWTs with REST or the gcloud CLI

For system-managed service accounts, you must manually assemble the JWT, then use the REST method projects.serviceAccounts.signJwt or the Google Cloud CLI command gcloud beta iam service-accounts sign-jwt to sign the JWT. To use either of these approaches, you must be a member of the Service Account Token Creator Identity and Access Management role.

gcloud CLI example

The following example shows a bash script that assembles a JWT and then uses the gcloud beta iam service-accounts sign-jwt command to sign it.

#!/bin/bash SA_EMAIL_ADDRESS="myserviceaccount@myproject.iam.gserviceaccount.com" TMP_DIR=$(mktemp -d /tmp/sa_signed_jwt.XXXXX) trap "rm -rf ${TMP_DIR}" EXIT JWT_FILE="${TMP_DIR}/jwt-claim-set.json" SIGNED_JWT_FILE="${TMP_DIR}/output.jwt" IAT=$(date '+%s') EXP=$((IAT+3600)) cat <<EOF > $JWT_FILE {  "aud": "https://bigquery.googleapis.com/",  "iat": $IAT,  "exp": $EXP,  "iss": "$SA_EMAIL_ADDRESS",  "sub": "$SA_EMAIL_ADDRESS" } EOF gcloud beta iam service-accounts sign-jwt --iam-account $SA_EMAIL_ADDRESS $JWT_FILE $SIGNED_JWT_FILE echo "Datasets:" curl -L -H "Authorization: Bearer $(cat $SIGNED_JWT_FILE)" \ -X GET \ "https://bigquery.googleapis.com/bigquery/v2/projects/myproject/datasets?alt=json"

What's next