gtoken

What is gtoken?

The gtoken npm package is designed to handle the acquisition and management of Google OAuth2 tokens. It simplifies the process of authenticating with Google APIs by managing the token generation, refresh, and validation processes.

What are gtoken's main functionalities?

Generate Access Token

This feature allows users to generate an access token by providing a key file and the required scopes. The token can then be used to authenticate requests to Google APIs.

const { GoogleToken } = require('gtoken');
const gtoken = new GoogleToken({
  keyFile: 'path/to/keyfile.json',
  scope: ['https://www.googleapis.com/auth/drive']
});
gtoken.getToken().then(token => {
  console.log(token);
}).catch(err => {
  console.error(err);
});

Refresh Token

This feature allows users to refresh their existing token when it expires. The refreshed token ensures continued access without needing to re-authenticate.

const { GoogleToken } = require('gtoken');
const gtoken = new GoogleToken({
  keyFile: 'path/to/keyfile.json',
  scope: ['https://www.googleapis.com/auth/drive'],
  token: existingToken
});
gtoken.refreshToken().then(newToken => {
  console.log(newToken);
}).catch(err => {
  console.error(err);
});

Other packages similar to gtoken

google-auth-library

Similar to gtoken, google-auth-library is a comprehensive library for Google authentication, supporting OAuth2, service accounts, and other authentication methods. It offers more extensive features compared to gtoken, including support for various environments and additional Google authentication flows.

oauth2-client-js

This package provides mechanisms for implementing OAuth2 clients. While it is not specific to Google, it can be used for Google OAuth2 authentication. It is more generic compared to gtoken, which is specifically tailored for Google token management.

README

node-gtoken

Node.js Google Authentication Service Account Tokens

This is a low level utility library used to interact with Google Authentication services. In most cases, you probably want to use the google-auth-library instead.

• gtoken API Reference
• github.com/googleapis/node-gtoken

Installation

npm install gtoken

Usage

Use with a .pem or .p12 key file:

const { GoogleToken } = require('gtoken');
const gtoken = new GoogleToken({
  keyFile: 'path/to/key.pem', // or path to .p12 key file
  email: '[e-mail]',
  scope: ['https://scope1', 'https://scope2'], // or space-delimited string of scopes
  eagerRefreshThresholdMillis: 5 * 60 * 1000
});

gtoken.getToken((err, tokens) => {
  if (err) {
    console.log(err);
    return;
  }
  console.log(tokens);
  // {
  //   access_token: 'very-secret-token',
  //   expires_in: 3600,
  //   token_type: 'Bearer'
  // }
});

You can also use the async/await style API:

const tokens = await gtoken.getToken()
console.log(tokens);

Or use promises:

gtoken.getToken()
  .then(tokens => {
    console.log(tokens)
  })
  .catch(console.error);

Use with a service account .json key file:

const { GoogleToken } = require('gtoken');
const gtoken = new GoogleToken({
  keyFile: 'path/to/key.json',
  scope: ['https://scope1', 'https://scope2'], // or space-delimited string of scopes
  eagerRefreshThresholdMillis: 5 * 60 * 1000
});

gtoken.getToken((err, tokens) => {
  if (err) {
    console.log(err);
    return;
  }
  console.log(tokens);
});

Pass the private key as a string directly:

const key = '-----BEGIN RSA PRIVATE KEY-----\nXXXXXXXXXXX...';
const { GoogleToken } = require('gtoken');
const gtoken = new GoogleToken({
  email: '[e-mail]',
  scope: ['https://scope1', 'https://scope2'], // or space-delimited string of scopes
  key: key,
  eagerRefreshThresholdMillis: 5 * 60 * 1000
});

Options

Various options that can be set when creating initializing the gtoken object.

• options.email or options.iss: The service account email address.
• options.scope: An array of scope strings or space-delimited string of scopes.
• options.sub: The email address of the user requesting delegated access.
• options.keyFile: The filename of .json key, .pem key or .p12 key.
• options.key: The raw RSA private key value, in place of using options.keyFile.
• options.additionalClaims: Additional claims to include in the JWT when requesting a token.
• options.eagerRefreshThresholdMillis: How long must a token be valid for in order to return it from the cache. Defaults to 0.

.getToken(callback)

Returns the cached tokens or requests a new one and returns it.

gtoken.getToken((err, token) => {
  console.log(err || token);
  // gtoken.rawToken value is also set
});

.getCredentials('path/to/key.json')

Given a keyfile, returns the key and (if available) the client email.

const creds = await gtoken.getCredentials('path/to/key.json');

Properties

Various properties set on the gtoken object after call to .getToken().

• gtoken.idToken: The OIDC token returned (if any).
• gtoken.accessToken: The access token.
• gtoken.expiresAt: The expiry date as milliseconds since 1970/01/01
• gtoken.key: The raw key value.
• gtoken.rawToken: Most recent raw token data received from Google.

.hasExpired()

Returns true if the token has expired, or token does not exist.

const tokens = await gtoken.getToken();
gtoken.hasExpired(); // false

.revokeToken()

Revoke the token if set.

await gtoken.revokeToken();
console.log('Token revoked!');

Downloading your private .p12 key from Google

1. Open the Google Developer Console.
2. Open your project and under "APIs & auth", click Credentials.
3. Generate a new .p12 key and download it into your project.

Converting your .p12 key to a .pem key

You can just specify your .p12 file (with .p12 extension) as the keyFile and it will automatically be converted to a .pem on the fly, however this results in a slight performance hit. If you'd like to convert to a .pem for use later, use OpenSSL if you have it installed.

$ openssl pkcs12 -in key.p12 -nodes -nocerts > key.pem

Don't forget, the passphrase when converting these files is the string 'notasecret'

License

MIT

Changelog

6.1.0 (2022-06-28)

Features

• allow customizing the http client (#426) (408ad04)