hapi-auth-github

hapi-auth-github makes it easy to

GitHub Authentication Plugin for Hapi.js Apps with detailed documentation.

Why?

We use GitHub for all our coding projects and are building a tool to keep track of all them: https://github.com/dwyl/tudo

Given that other people will have projects that need GitHub Authentication,
we have de-coupled our OAuth code into this re-useable Hapi Plugin.

If you have any questions or would like to contribute to this module, please get in touch:

What?

An easy-to-use Hapi.js plugin that gives you GitHub OAuth Authentication
in a few simple steps and has human-readable, maintained code.

Note: if you are new to Hapi check out: https://github.com/dwyl/learn-hapi

How?

If you're new to GitHub Authentication, and want to understand how it works, read the GitHub OAuth Web Application flow:
https://developer.github.com/v3/oauth/#web-application-flow

Or, if you just need to get up and running fast, follow these simple steps:

1. Install hapi-auth-github from NPM

Install the plugin from npm and save it to your package.json:

npm install hapi-auth-github --save

2. Create an App on GitHub

Follow the instructions in: GITHUB-APP-STEP-BY-STEP-GUIDE.md

3. Export the Required Environment Variables

Once you've created your app following the GitHub App Step-by-Step Guide

Export the Environment Variables:

BASE_URL=http://localhost:8000 # same as Authorized JavaScript Origin 
GITHUB_CLIENT_ID=YourGitHubClientID
GITHUB_CLIENT_SECRET=SuperSecret
GITHUB_AUTH_REDIRECT_URL=/githubauth
PORT=8000
 
# Optionals 
# (If you are using hapi-auth-jwt2) 
JWT_SECRET=ItsNoSecretBecauseYouToldEverybody
# If you are using custom instance of GitHub 
GITHUB_HOSTNAME=github.mycompany.com
GITHUB_API_HOSTNAME=api.github.mycompany.com

Notes on Environment Variables:

Tip: If you (or anyone on your team) are new to Environment Variables or need a refresher,
see: https://github.com/dwyl/learn-environment-variables

We named/exported the 5 variables prefixed with GITHUB_ to distinguish them from other services you may be using which may also have an environment variable named CLIENT_ID...

The BASE_URL is required to know which url your app is using. it needs to be identical to the Authorized JavaScript Origin that you set in step 2 above.

The GITHUB_AUTH_REDIRECT_URL is the url (endpoint) where GitHub will send the initial OAuth2 code to confirm your application is real. Make sure that the url is identical to the one you defined when setting up your app on GitHub. e.g: http://localhost:8000/githubauth

The GITHUB_HOSTNAME and GITHUB_API_HOSTNAME let's you define other instance of GitHub e.g. enterprise. Defaults are github.com and api.github.com accordingly.

4. Create Your (Custom) Handler Function

This is where you decide what to do with the person's profile details
once they have authorized your App to use their GitHub details.

Your custom handler should have the following signature:

function custom_handler(request, reply, tokens, profile) {
  // save the profile as a session so you can personalize their experience of your app
  // use the reply() to send a response/view to the visitor
}

The handler function parameters are:

• request is the hapi request object with all the properties.
• reply is the standard hapi reply object used to send your response to the client or send a rendered view.
• tokens are the OAuth2 tokens returned by GitHub for the session see: sample_auth_token.json
• profile is the person's GitHub profile see: sample_profile.json

For an example custom_handler, see: example/github_oauth_handler.js

5. Register the Plugin into your Hapi.js Server

The final step is to register the plugin into your Hapi.js Server declaring your desired options:

// declare your desired options for the plugin
var opts = {
  handler: require('./github_oauth_handler.js'), // your handler
  SCOPE: 'user' // ask for their public email address
};
 
server.register([{ register: require('hapi-auth-github'), options:opts }],
 function (err) {
  if(err){
    // handle the error if the plugin failed to load:  
  }
  // the rest of your app ...
});

options explained

• handler - the handler you defined above in step 4 which is your custom logic for GitHub auth enabled app.
• SCOPE - these are the permissions your app is requesting.

Implementation Notes:

To run the example you will need an extra environment variable:

BASE_URL=http://localhost:8000 # same as Authorized JavaScript Origin 
GITHUB_CLIENT_ID=YourGitHubClientID
GITHUB_CLIENT_SECRET=SuperSecret
GITHUB_AUTH_REDIRECT_URL=/githubauth
PORT=8000
# Optionally (If you are using hapi-auth-jwt2) 
JWT_SECRET=ItsNoSecretBecauseYouToldEverybody

Also, if you're wondering what that JWT_SECRET Environment Variables is for,
see: https://github.com/dwyl/learn-json-web-tokens

Background Reading

• Basics: https://developer.github.com/guides/basics-of-authentication
• Intro to OAuth2: https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2
• GitHub OAuth Scopes: https://developer.github.com/v3/oauth/#scopes (what you should ask to access on a person' GitHub account)