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 theclientID
. 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 theclientSecret
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 orrequire
-able package name (ex:DropboxOAuth2Strategy
orpassport-dropbox-oauth2
), -
oauthStrategyOptions
- The custom options you need pass to the strategy besides theappKey
andappSecret
. 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.