oauth-cli

OAuth CLI

A Node utility that opens the authorizationURL (on the oauth server), starts an express server which listens for the redirect from the oauth server after the user logs in. Then the oauth2 library makes a request to the tokenURL and returns back the token in the response. It resolves the promise of the OAuthCLI with the accessToken and refreshToken.

You can either use oauth2 directly (passing in a authorizationURL and tokenURL) or pass in any passport strategy

Installation

yarn add @node-cli-toolkit/oauth-cli

Usage

CLI Usage

Note that this package has a CLI avaialable where you can just pass in the options as arguments. See generate-oauth-token-cli for details.

Using Default Oauth2 Strategy

import oauthCLI from "@node-cli-toolkit/oauth-cli";

await oauthCLI({
  authorizationURL: "http://oauthprovider.com/oauth",
  tokenUrl: "http://oauthprovider.com/token",
  appKey: "key",
  appSecret: "secret"
});

Returns: The accessToken, refreshToken, user

{
  accessToken: "I_AM_THE_TOKEN",
  refreshToken: "REFRESH_TOKEN",
  user: {}
}

Using Custom Passport Strategy

import { Strategy as DropboxOAuth2Strategy } from "passport-dropbox-oauth2";
import oauthCLI from "@node-cli-toolkit/oauth-cli";

await oauthCLI({
  oauthStrategy: DropboxOAuth2Strategy,
  oauthStrategyOptions: {
    apiVersion: "2"
  },
  mutateUser: profile => ({
    userId: profile.id,
    email: profile.emails[0].value,
    name: {
      givenName: profile.name.givenName,
      familyName: profile.name.familyName,
      displayName: profile.displayName
    },
    // any other user details
    profile
  }),
  appSecret: "SECRET",
  appKey: "KEY"
});

Returns: The accessToken, refreshToken, user

{
  accessToken: "I_AM_THE_TOKEN",
  refreshToken: "REFRESH_TOKEN",
  user: {}
}

Save token to a file using a Token Identifier

This is great for prototyping. It saves your token to the file system in the /tmp folder with a unique token identifier. You can later retrieve it using getToken utility.

See @node/api-toolkit/save-token for more info

import oauthCLI from "@node-cli-toolkit/oauth-cli";

await oauthCLI({
  authorizationURL: "http://oauthprovider.com/oauth",
  tokenUrl: "http://oauthprovider.com/token",
  appKey: "key",
  appSecret: "secret",
  saveTokenToFile: true,
  tokenIdentifier: "NODE_CLI_TOOLKIT_OAUTH_TOKEN_JEST"
});

Returns: The accessToken, refreshToken, user

{
  accessToken: "I_AM_THE_TOKEN",
  refreshToken: "REFRESH_TOKEN",
  user: {}
}

Saves token to /tmp/NODE_CLI_TOOLKIT_OAUTH_TOKEN_JEST

You can retrieve using

import { getToken } from "@node-cli-toolkit/save-token";

const token = await getToken({
  tokenIdentifier: "NODE_CLI_TOOLKIT_OAUTH_TOKEN_JEST"
});

Save token to a file using a Token Identifier

This is great for prototyping. It saves your token to the file system in whatever file you choose. You can later retrieve it using getToken utility.

See @node/api-toolkit/save-token for more info

import oauthCLI from "@node-cli-toolkit/oauth-cli";

await oauthCLI({
  authorizationURL: "http://oauthprovider.com/oauth",
  tokenUrl: "http://oauthprovider.com/token",
  appKey: "key",
  appSecret: "secret",
  saveTokenToFile: true,
  tokenPath: "/tmp/node-api-toolkit-save-token-test-custom-file"
});

Returns: The accessToken, refreshToken, user

{
  accessToken: "I_AM_THE_TOKEN",
  refreshToken: "REFRESH_TOKEN",
  user: {}
}

Saves token to /tmp/node-api-toolkit-save-token-test-custom-file

You can retrieve using:

import { getToken } from "@node-cli-toolkit/save-token";

const token = await getToken({
  filePath: "/tmp/node-api-toolkit-save-token-test-custom-file"
});

Options

Required For All

• appKey - Aka the clientID. This is the app key you get from creating your Oauth application

• (ex for Dropbox: https://docs.gravityforms.com/creating-a-custom-dropbox-app/) (ex: 3u23809sd90239)

• appSecret - Aka the clientSecret This is the app secret you get from creating your Oauth

• application (ex: 3u23809sd90239)

Using Default Strategy

• authorizationURL - Initial OAuth URL (example: https://www.dropbox.com/1/oauth2/authorize)
• tokenUrl - The URL to fetch the token (example: https://api.dropbox.com/1/oauth2/token)
• callbackURL - (optional) The URI of our local server (default: http://localhost:8888/redirect)

Passing IN a Custom Strategy

• oauthStrategy - The Strategy constructor or require-able package name (ex: DropboxOAuth2Strategy or passport-dropbox-oauth2),

• oauthStrategyOptions - The custom options you need pass to the strategy besides the appKey and appSecret. Example:

  {
     apiVersion: "2"
  }
  

• mutateUser - (optional) - A parser for the user object (profile) you get back. Otherwise it just passes in the result

Saving Token to A File

• saveTokenToFile - Should the token be saved to a file
• tokenIdentifier - If saving to a file, what should be the unique token identifier. See @node/api-toolkit/save-token for more info
• tokenPath - If saving to a file, what should be the filename (if not using a token identifier)

Tests and Todos

Everything in this package is tested thoroughly. You can also see planned features as part of the tests' todos. See tests directory.