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.
Audience
For JWTs, an
audience claim is
used instead of a
scope.
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 ServiceAccountJwtAccessCredentials
- 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.
import com.google.auth.Credentials;
import com.google.auth.oauth2.ServiceAccountJwtAccessCredentials;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import java.io.FileInputStream;
import java.net.URI;
public class Example {
public static void main(String... args) throws Exception {
String projectId = "myproject";
// Load JSON file that contains service account keys and create ServiceAccountJwtAccessCredentials object.
String credentialsPath = "/path/to/key.json";
URI audience = URI.create("https://bigquery.googleapis.com/");
Credentials credentials = null;
try (FileInputStream is = new FileInputStream(credentialsPath)) {
credentials = ServiceAccountJwtAccessCredentials.fromStream(is, audience);
}
// 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="[email protected]"
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.