This is Google's officially supported node.js client library for using OAuth 2.0 authorization and authentication with Google APIs.
A comprehensive list of changes in each version may be found in the CHANGELOG.
Read more about the client libraries for Cloud APIs, including the older Google APIs Client Libraries, in Client Libraries Explained.
Table of contents:
This library provides a variety of ways to authenticate to your Google services.
This library provides an implementation of Application Default Credentialsfor Node.js. The Application Default Credentials provide a simple way to get authorization credentials for use in calling Google APIs.
They are best suited for cases when the call needs to have the same identity and authorization level for the application independent of the user. This is the recommended approach to authorize calls to Cloud APIs, particularly when you're building an application that uses Google Cloud Platform.
To use Application Default Credentials, You first need to download a set of JSON credentials for your project. Go to APIs & Auth > Credentials in the Google Developers Console and select Service account from the Add credentials dropdown.
This file is your only copy of these credentials. It should never be committed with your source code, and should be stored securely.
Once downloaded, store the path to this file in the GOOGLE_APPLICATION_CREDENTIALS
environment variable.
Before making your API call, you must be sure the API you're calling has been enabled. Go to APIs & Auth > APIs in the Google Developers Console and enable the APIs you'd like to call. For the example below, you must enable the DNS API
.
Rather than manually creating an OAuth2 client, JWT client, or Compute client, the auth library can create the correct credential type for you, depending upon the environment your code is running under.
For example, a JWT auth client will be created when your code is running on your local developer machine, and a Compute client will be created when the same code is running on Google Cloud Platform. If you need a specific set of scopes, you can pass those in the form of a string or an array to the GoogleAuth
constructor.
The code below shows how to retrieve a default credential type, depending upon the runtime environment.
This library comes with an OAuth2 client that allows you to retrieve an access token and refreshes the token and retry the request seamlessly if you also provide an expiry_date
and the token is expired. The basics of Google's OAuth2 implementation is explained on Google Authorization and Authentication documentation.
In the following examples, you may need a CLIENT_ID
, CLIENT_SECRET
and REDIRECT_URL
. You can find these pieces of information by going to the Developer Console, clicking your project > APIs & auth > credentials.
For more information about OAuth2 and how it works, see here.
Let's take a look at a complete example.
This library will automatically obtain an access_token
, and automatically refresh the access_token
if a refresh_token
is present. The refresh_token
is only returned on the first authorization, so if you want to make sure you store it safely. An easy way to make sure you always store the most recent tokens is to use the tokens
event:
With the code returned, you can ask for an access token as shown below:
If you need to obtain a new refresh_token
, ensure the call to generateAuthUrl
sets the access_type
to offline
. The refresh token will only be returned for the first authorization by the user. To force consent, set the prompt
property to consent
:
access_token
informationAfter obtaining and storing an access_token
, at a later time you may want to go check the expiration date,
original scopes, or audience for the token. To get the token info, you can use the getTokenInfo
method:
This method will throw if the token is invalid.
If you're authenticating with OAuth2 from an installed application (like Electron), you may not want to embed your client_secret
inside of the application sources. To work around this restriction, you can choose the iOS
application type when creating your OAuth2 credentials in the Google Developers console:
If using the iOS
type, when creating the OAuth2 client you won't need to pass a client_secret
into the constructor:
The Google Developers Console provides a .json
file that you can use to configure a JWT auth client and authenticate your requests, for example when using a service account.
The parameters for the JWT auth client including how to use it with a .pem
file are explained in samples/jwt.js.
Instead of loading credentials from a key file, you can also provide them using an environment variable and the GoogleAuth.fromJSON()
method. This is particularly convenient for systems that deploy directly from source control (Heroku, App Engine, etc).
Start by exporting your credentials:
Now you can create a new client from the credentials:
You can set the HTTPS_PROXY
or https_proxy
environment variables to proxy HTTPS requests. When HTTPS_PROXY
or https_proxy
are set, they will be used to proxy SSL requests that do not have an explicit proxy configuration option present.
If your application is running on Google Cloud Platform, you can authenticate using the default service account or by specifying a specific service account.
Note: In most cases, you will want to use Application Default Credentials. Direct use of the Compute
class is for very specific scenarios.
If your application is running on Cloud Run or Cloud Functions, or using Cloud Identity-Aware
Proxy (IAP), you will need to fetch an ID token to access your application. For
this, use the method getIdTokenClient
on the GoogleAuth
client.
For invoking Cloud Run services, your service account will need the
Cloud Run Invoker
IAM permission.
For invoking Cloud Functions, your service account will need the
Function Invoker
IAM permission.
A complete example can be found in samples/idtokens-serverless.js
.
For invoking Cloud Identity-Aware Proxy, you will need to pass the Client ID used when you set up your protected resource as the target audience.
A complete example can be found in samples/idtokens-iap.js
.
If you've secured your IAP app with signed headers, you can use this library to verify the IAP header:
A complete example can be found in samples/verifyIdToken-iap.js
.
Samples are in the samples/
directory. Each sample's README.md
has instructions for running its sample.
Sample | Source Code | Try it |
---|---|---|
Adc | source code | ![]() |
Compute | source code | ![]() |
Credentials | source code | ![]() |
Headers | source code | ![]() |
ID Tokens for Identity-Aware Proxy (IAP) | source code | ![]() |
ID Tokens for Serverless | source code | ![]() |
Jwt | source code | ![]() |
Keepalive | source code | ![]() |
Keyfile | source code | ![]() |
Oauth2-code Verifier | source code | ![]() |
Oauth2 | source code | ![]() |
Sign Blob | source code | ![]() |
Verifying ID Tokens from Identity-Aware Proxy (IAP) | source code | ![]() |
Verify Id Token | source code | ![]() |
The Google Auth Library Node.js Client API Reference documentation also contains samples.
Our client libraries follow the Node.js release schedule. Libraries are compatible with all current active and maintenance versions of Node.js.
Client libraries targeting some end-of-life versions of Node.js are available, and
can be installed via npm dist-tags.
The dist-tags follow the naming convention legacy-(version)
.
Legacy Node.js versions are supported as a best effort:
legacy-8
: install client libraries from this dist-tag for versions
compatible with Node.js 8.This library follows Semantic Versioning.
This library is considered to be General Availability (GA). This means it is stable; the code surface will not change in backwards-incompatible ways unless absolutely necessary (e.g. because of critical security issues) or with an extensive deprecation period. Issues and requests against GA libraries are addressed with the highest priority.
More Information: Google Cloud Platform Launch Stages
Contributions welcome! See the Contributing Guide.
Please note that this README.md
, the samples/README.md
,
and a variety of configuration files in this repository (including .nycrc
and tsconfig.json
)
are generated from a central template. To edit one of these files, make an edit
to its template in this
directory.
Apache Version 2.0
See LICENSE