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:

For service account keys created in Google Cloud console or by using the gcloud CLI, use a client library that provides JWT signing.
For system-managed service accounts, use the REST API or the gcloud CLI.

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:

Go: func JWTAccessTokenSourceFromJSON
Java: Class ServiceAccountCredentials
Node.js: Class JWTAccess
PHP: ServiceAccountJwtAccessCredentials
Python: google.auth.jwt module
Ruby: Class: Google::Auth::ServiceAccountJwtHeaderCredentials

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.

importcom.google.auth.oauth2.ServiceAccountCredentials ;
importcom.google.cloud.bigquery.BigQuery ;
importcom.google.cloud.bigquery.BigQueryOptions ;
importcom.google.common.collect.ImmutableList;
importjava.io.FileInputStream;
importjava.io.IOException;
importjava.net.URI;
publicclass Example{
publicstaticvoidmain(String...args)throwsIOException{
StringprojectId="myproject";
// Load JSON file that contains service account keys and create ServiceAccountCredentials object.
StringcredentialsPath="/path/to/key.json";
ServiceAccountCredentials credentials=null;
try(FileInputStreamis=newFileInputStream(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
gcloudbetaiamservice-accountssign-jwt--iam-account$SA_EMAIL_ADDRESS$JWT_FILE$SIGNED_JWT_FILE
echo"Datasets:"
curl-L-H"Authorization: Bearer $(cat$SIGNED_JWT_FILE)"\
-XGET\
"https://bigquery.googleapis.com/bigquery/v2/projects/myproject/datasets?alt=json"

What's next

Learn more about BigQuery authentication.
Learn how to authenticate with end-user credentials.