ghauth

Create and load persistent GitHub authentication tokens for command-line apps

Important

Github deprecated their basic username/password auth api and have scheduled to sunset it November 13, 2020. ghauth v5.0.0+ supports the new device auth flow but requires some implementation changes and application registration with Github. Review the new API docs and see Setup for a simple upgrade guide between v4 and v5.

Example usage

const ghauth = require('ghauth')
const authOptions = {
  // provide a clientId from a Github oAuth application registration
  clientId: '123456',

  // awesome.json within the user's config directory will store the token
  configName: 'awesome',

  // (optional) whatever GitHub auth scopes you require
  scopes: [ 'user' ],

  // (optional)
  userAgent: 'My Awesome App'
}

const authData = await ghauth(authOptions)
console.log(authData)

// can also be run with a callback as:
//
// ghauth(authOptions, function (err, authData) {
//  console.log(authData)
// })

Will run something like this:

$ node awesome.js
  Authorize with GitHub by opening this URL in a browser:

    https://github.com/login/device

  and enter the following User Code:
  (or press ⏎ to enter a personal access token)

✔ Device flow complete.  Manage at https://github.com/settings/connections/applications/123456
✔ Authorized for rvagg
Wrote access token to "~/.config/awesome/config.json"
{
  token: '24d5dee258c64aef38a66c0c5eca459c379901c2',
  user: 'rvagg'
}

Because the token is persisted, the next time you run it there will be no prompts:

$ node awesome.js

{ user: 'rvagg',
  token: '24d5dee258c64aef38a66c0c5eca459c379901c2' }

When authUrl is configured for a Github enterprise endpoint, it will look more like this:

$ node awesome.js

GitHub username: rvagg
GitHub password: ✔✔✔✔✔✔✔✔✔✔✔✔
GitHub OTP (optional): 669684

{ user: 'rvagg',
  token: '24d5dee258c64aef38a66c0c5eca459c379901c2' }

API

ghauth(options, callback)

The options argument can have the following properties:

• clientId (String, required unless noDeviceFlow is true): the clientId of your oAuth application on Github. See setup below for more info on creating a Github oAuth application.
• configName (String, required unless noSave is true): the name of the config you are creating, this is required for saving a <configName>.json file into the users config directory with the token created. Note that the config directory is determined by application-config and is OS-specific.
• noSave (Boolean, optional): if you don't want to persist the token to disk, set this to true but be aware that you will still be creating a saved token on GitHub that will need cleaning up if you are not persisting the token.
• authUrl (String, optional): defaults to null since public Github no longer supports basic auth. Setting authUrl will allow you to perform basic authentication with a Github Enterprise instance. This setting is ignored if the host of the url is api.github.com or github.com.
• promptName (String, optional): defaults to 'GitHub Enterprise', change this if you are prompting for GHE credentials. Not used for public GH authentication.
• scopes (Array, optional): defaults to [], consult the GitHub scopes documentation to see what you may need for your application.
• note (String, optional): defaults to 'Node.js command-line app with ghauth', override if you want to save a custom note with the GitHub token (user-visible). Only used with GHE basic authentication.
• userAgent (String, optional): defaults to 'Magic Node.js application that does magic things with ghauth', only used for requests to GitHub, override if you have a good reason to do so.
• passwordReplaceChar (String, optional): defaults to '✔', the character echoed when the user inputs their password. Can be set to '' to silence the output.
• noDeviceFlow (Boolean, optional): disable the Device Flow authentication method. This will prompt users for a personal access token immediately if no existing configuration is found. Only applies when authUrl is not used.

The callback will be called with either an Error object describing what went wrong, or a data object as the second argument if the auth creation (or cache read) was successful. The shape of the second argument is { user:String, token:String }.

Setup

Github requires a clientId from a Github oAuth Application in order to complete oAuth device flow authentication.

1. Register an "oAuth Application" with Github:

• Personal Account oAuth apps page
• https://github.com/organizations/${org_name}/settings/applications: Organization oAuth settings page.

2. Provide an application name, homepage URL and callback URL. You can make these two URLs the same, since your app will not be using a callback URL with the device flow.
3. Go to your oAuth application's settings page and take note of the "Client ID" (this will get passed as clientId to ghauth). You can ignore the "Client Secret" value. It is not used.

The clientId is registered by the developer of the tool or CLI, and is baked into the code of your program. Users do not need to set this up, onyl the publisher of the app.

• Device flow docs

v4 to v5 Upgrade guide

• A options.clientId is required to use device flow. Set up an oAuth application to get a clientId.
• the options.authUrl now only applies to GitHub enterprise authentication which still only supports basic auth. Only pass this if you intend for GitHub Enterpise authentication.
• options.note is only used for GHE basic auth now. Your oAuth application details serve the purpose of token note.
• options.noDeviceFlow is available to skip the device flow if you are unable to create a clientId for some reason, and wish to skip to the personal access token input prompt immediately.

Contributing

ghauth is an OPEN Open Source Project. This means that:

Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.

See the CONTRIBUTING.md file for more details.

A note about tests

... there are no proper tests yet unfortunately. If you would like to contribute some that would be very helpful! We need to mock the GitHub API to properly test the functionality. Otherwise, testing of this library is done by its use downstream.

Contributors

ghauth is made possible by the excellent work of the following contributors:

License & copyright

Copyright (c) 2014 ghauth contributors (listed above).

ghauth is licensed under the MIT license. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE.md file for more details.