GitHub Authentication Plugin for Hapi.js Apps with detailed documentation.
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:
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
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:
Install the plugin from npm and save it to your package.json
:
npm install hapi-auth-github --save
Follow the instructions in: GITHUB-APP-STEP-BY-STEP-GUIDE.md
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
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.
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
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 ...
});
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.
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
- 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)