hapi auth google

Let people authenticate with your application/website using their Google Account.

Why?

As of May 2017, Google has over 2 Billion Android users alone. In addition, there are over a billion who use gmail (thus, have a Google account) as of 2016, and THEN there are all the Google For Education users, which was 45 million in 2015 and was growing at a rate of 40+%/year. To put it conservatively, there are more than 2 Billion users out there who could authenticate with your app using that Google account so offering people the option of logging into your App(s) using their Google Account makes a lot of sense.

What?

This plugin lets you easily integrate Google Authentication into a Hapi-based Web Application / API.

Key Advantages of This Plugin:

• Much simpler than "Passport" or "Bell"; you can read the code in a few minutes: /lib/index.js
• Only One Dependency: Google's Official Node.js module (nothing else)
• Complete step-by-step instructions, example && tests to get you up and running in 5 mins.
• Always up-to-date - we use this plugin in our/client projects so we are quick to update it when required.
• We're here to help if you get stuck!

How? (Usage)

1. Install hapi-auth-google from NPM

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

npm install hapi-auth-google --save

2. Create an App on the Google Developer Console

To get access to the Google Account (Plus) API you will first need to create an app
by visiting the google developer console: https://console.developers.google.com

If you are totally new to using the Google API, we created GOOGLE-APP-STEP-BY-STEP-GUIDE just for you!
( Note: if you still have any questions, ask! )

3. Export the Required Environment Variables

Once you've created your app following the GOOGLE-APP-STEP-BY-STEP-GUIDE

Export the Environment Variables:

GOOGLE_CLIENT_ID=YourAppsClientId.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=SuperSecret
PORT=8000
BASE_URL=http://localhost:8000 # Must be identical to "Authorized JavaScript Origin" 
JWT_SECRET=SomethingSuperHardToGuess-->grc.com/passwords.htm # Optionally use JWTs 

We export the two variables prefixed with GOOGLE_ to distinguish them from other services you may be using.

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.8 above.

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

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 Google 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 Google for the session see: sample-auth-token.json
• profile is the person's Google Plus profile see: sample-profile.json

If you get stuck check out: /example/google_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 = {
  REDIRECT_URL: '/googleauth', // must match google app redirect URI from step 2.8
  handler: require('./google_oauth_handler.js'), // your handler
  config: {  // optional route config (as for any route in hapi)
    description: 'Google auth callback',
    notes: 'Handled by hapi-auth-google plugin',
    tags: ['api', 'auth', 'plugin']
  },
  access_type: 'online', // options: offline, online
  approval_prompt: 'auto', // options: always, auto
  scope: 'https://www.googleapis.com/auth/plus.profile.emails.read', // ask for their email address
  // can use process.env or if you prefer, define here in options:
  BASE_URL: process.env.BASE_URL,
  GOOGLE_CLIENT_ID: process.env.GOOGLE_CLIENT_ID,
  GOOGLE_CLIENT_SECRET: process.env.GOOGLE_CLIENT_SECRET
};
 
server.register([{ register: require('hapi-auth-google'), options:opts }],
 function (err) {
  if(err){
    // handle the error if the plugin failed to load:  
  }
  // the rest of your app ...
});

options explained

• REDIRECT_URL - is the url (endpoint) where google will send the initial OAuth2 code to check your application is real. Make sure that the url is identical to the one you defined when setting up your app in the google developer console (section 2.8 in the step-by-step guide)
• handler - the handler you defined above in step 4 which is your custom logic for google-auth enabled app.
• scope - these are the permissions your app is requesting.

Need an Example ?

See: /example directory in this repo for a quick example.

Dependencies

This plugin depends on the Official google-api-nodejs-client - to do the authentication with Google and access to other Google Services.

Background Reading

If you are new to OAuth2, see:

• Intro to OAuth 2.0: https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2
• Google OAuth2 in detail: https://developers.google.com/identity/protocols/OAuth2