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.

  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

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