tra-analysis/website/functions/node_modules/google-auto-auth/readme.md
2019-01-06 13:14:45 -06:00

6.6 KiB

google-auto-auth

Making it as easy as possible to authenticate a Google API request

$ npm install --save google-auto-auth
var googleAuth = require('google-auto-auth');

// Create a client
var auth = googleAuth();

auth.authorizeRequest({
  method: 'get',
  uri: 'https://www.googleapis.com/something'
}, function (err, authorizedReqOpts) {
/*
  authorizedReqOpts = {
    method: 'get',
    uri: 'https://www.googleapis.com/something',
    headers: {
      Authorization: 'Bearer {{token}}'
    }
  }
*/
});

Or, just get an access token.

auth.getToken(function (err, token) {
/*
  token = 'access token'
*/
});

This works automatically if:

  • your app runs on Google Cloud Platform
  • you are authenticated with the gcloud sdk
  • you have the path to a JSON key file as an environment variable named GOOGLE_APPLICATION_CREDENTIALS

If you do not meet those, you must provide a keyFilename or credentials object.

var googleAuth = require('google-auto-auth');

var authConfig = {};

// path to a key:
authConfig.keyFilename = '/path/to/keyfile.json';

// or a credentials object:
authConfig.credentials = {
  client_email: '...',
  private_key: '...'
};

// Create a client
var auth = googleAuth(authConfig);

auth.authorizeRequest({/*...*/}, function (err, authorizedReqOpts) {});
auth.getToken(function (err, token) {});

API

googleAuth = require('google-auto-auth')

auth = googleAuth([authConfig])

authConfig
  • Type: Object

See the above section on Authentication. This object is necessary if automatic authentication is not available in your environment.

At a glance, the supported properties for this method are:

  • credentials - Object containing client_email and private_key properties
  • keyFilename - Path to a .json, .pem, or .p12 key file
  • projectId - Your project ID
  • scopes - Required scopes for the desired API request
  • token - An access token. If provided, we'll use this instead of fetching a new one

auth.authorizeRequest(reqOpts, callback)

Extend an HTTP request object with an authorized header.

callback(err, authorizedReqOpts)
callback.err
  • Type: Error

An API error or an error if scopes are required for the request you're trying to make (check for err.code = MISSING_SCOPE). If you receive the missing scope error, provide the authConfig.scopes array with the necessary scope URLs for your request. There are examples of scopes that are required for some of the Google Cloud Platform services in the gcloud-node Authentication Guide.

callback.authorizedReqOpts
  • Type: Object

The reqOpts object provided has been extended with a valid access token attached to the headers.Authorization value. E.g.: headers.Authorization = 'Bearer y.2343...'.

auth.getAuthClient(callback)

Get the auth client instance from google-auth-library.

callback(err, authClient)
callback.err
  • Type: Error

An error that occurred while trying to get an authorization client.

callback.authClient

The client instance from google-auth-library. This is the underlying object this library uses.

auth.getCredentials(callback)

Get the client_email and private_key properties from an authorized client.

callback(err, credentials)
callback.err
  • Type: Error

An error that occurred while trying to get an authorization client.

callback.credentials
  • Type: Object

An object containing client_email and private_key.

auth.getEnvironment(callback)

Determine if the environment the app is running in is a Google Compute Engine instance.

callback(err, environmentObject)
callback.err
  • Type: Null

We won't return an error, but it's here for convention-sake.

callback.environmentObject
  • Type: Object
{
  IS_APP_ENGINE: Boolean,
  IS_CLOUD_FUNCTION: Boolean,
  IS_COMPUTE_ENGINE: Boolean,
  IS_CONTAINER_ENGINE: Boolean
}

If you've already run this function, the object will persist as auth.environment.

auth.getProjectId(callback)

Get the project ID if it was auto-detected or parsed from the provided keyfile.

callback(err, projectId)
callback.err
  • Type: Error

An error that occurred while trying to get an authorization client.

callback.projectId
  • Type: string

The project ID that was parsed from the provided key file or auto-detected from the environment.

auth.getToken(callback)

Get an access token. The token will always be current. If necessary, background refreshes are handled automatically.

callback(err, token)
callback.err
  • Type: Error

An API error or an error if scopes are required for the request you're trying to make (check for err.code = MISSING_SCOPE). If you receive the missing scope error, provide the authConfig.scopes array with the necessary scope URLs for your request.

callback.token
  • Type: String

A current access token to be used during an API request. If you provided authConfig.token, this method simply returns the value you passed.

auth.isAppEngine(callback)

Determine if the environment the app is running in is a Google App Engine instance.

callback(err, isAppEngine)
callback.err
  • Type: Null

We won't return an error, but it's here for convention-sake.

callback.isAppEngine
  • Type: Boolean

Whether the app is in App Engine or not.

auth.isCloudFunction(callback)

Determine if the environment the app is running in is a Google Cloud Function.

callback(err, isCloudFunction)
callback.err
  • Type: Null

We won't return an error, but it's here for convention-sake.

callback.isCloudFunction
  • Type: Boolean

Whether the app is in a Cloud Function or not.

auth.isComputeEngine(callback)

Determine if the environment the app is running in is a Google Compute Engine instance.

callback(err, isComputeEngine)
callback.err
  • Type: Null

We won't return an error, but it's here for convention-sake.

callback.isComputeEngine
  • Type: Boolean

Whether the app is in a Compute Engine instance or not.

auth.isContainerEngine(callback)

Determine if the environment the app is running in is a Google Container Engine instance.

callback(err, isContainerEngine)
callback.err
  • Type: Null

We won't return an error, but it's here for convention-sake.

callback.isContainerEngine
  • Type: Boolean

Whether the app is in a Container Engine instance or not.