Home

Awesome

ghauth

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

NPM

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

<b><code>ghauth(options, callback)</code></b>

The <b><code>options</code></b> argument can have the following properties:

The <b><code>callback</code></b> 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:
  1. 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.
  2. 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.

v4 to v5 Upgrade guide

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:

<table><tbody> <tr><th align="left">Rod Vagg</th><td><a href="https://github.com/rvagg">GitHub/rvagg</a></td><td><a href="http://twitter.com/rvagg">Twitter/@rvagg</a></td></tr> <tr><th align="left">Jeppe Nejsum Madsen</th><td><a href="https://github.com/jeppenejsum">GitHub/jeppenejsum</a></td><td><a href="http://twitter.com/nejsum">Twitter/@nejsum</a></td></tr> <tr><th align="left">Max Ogden</th><td><a href="https://github.com/maxogden">GitHub/maxogden</a></td><td><a href="http://twitter.com/maxogden">Twitter/@maxogden</a></td></tr> <tr><th align="left">Bret Comnes</th><td><a href="https://github.com/bcomnes">GitHub/bcomnes</a></td><td><a href="http://twitter.com/bcomnes">Twitter/@bcomnes</a></td></tr> </tbody></table>

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.