Third-party login plugin for hapi
bell is a third-party login plugin for hapi. bell ships with built-in support for Facebook, GitHub, Google, Instagram, LinkedIn, Twitter, Yahoo, Foursquare, VK, ArcGIS Online, Windows Live, Nest, and Phabricator. It also supports any compliant OAuth 1.0a and 2.0 based login services with a simple configuration object.
Lead Maintainer: Lois Desplat
bell works by adding a login endpoint and setting it to use a bell-based authentication strategy. bell will manage the third-party authentication flow and will only call the handler if the user successfully authenticated. The handler function is then used to examine the third-party credentials (e.g. lookup an existing account or offer a registration page), setup an active session, and redirect to the actual application.
bell does not maintain a session beyond a temporary state between the authorization flow. If a user authenticated once when accessing the endpoint, they will have to authenticate again. This means bell cannot be used alone as a login system except for single-page applications that require loading a single resource. Once the handler is called, the application must set its own session management. A common solution is to combine bell with the hapi-auth-cookie authentication scheme plugin.
var Hapi = require'hapi';var server = ;serverconnection port: 8000 ;// Register bell with the serverserverregisterrequire'bell'// Declare an authentication strategy using the bell scheme// with the name of the provider, cookie encryption password,// and the OAuth client credentials.serverauthstrategy'twitter' 'bell'provider: 'twitter'password: 'cookie_encryption_password'clientId: 'my_twitter_client_id'clientSecret: 'my_twitter_client_secret'isSecure: false // Terrible idea but required if not using HTTPS;// Use the 'twitter' authentication strategy to protect the// endpoint handling the incoming authentication credentials.// This endpoints usually looks up the third party account in// the database and sets some application state (cookie) with// the local application account information.serverroutemethod: 'GET' 'POST' // Must handle both GET and POSTpath: '/login' // The callback endpoint registered with the providerconfig:auth: 'twitter'// Perform any account lookup or registration, setup local session,// and redirect to the application. The third-party credentials are// stored in request.auth.credentials. Any query parameters from// the initial request are passed back via request.auth.credentials.query.return replyredirect'/home';;serverstart;;
server.auth.strategy() method requires the following strategy options:
provider- the name of the third-party provider (
'phabricator') or an object containing a custom provider with the following:
protocol- the authorization protocol used. Must be one of:
'oauth'- OAuth 1.0a
'oauth2'- OAuth 2.0
temporary- the temporary credentials (request token) endpoint (OAuth 1.0a only).
useParamsAuth- boolean that determines if OAuth client id and client secret will be sent as parameters as opposed to an Authorization header (OAuth 2.0 only). Defaults to
auth- the authorization endpoint URI.
token- the access token endpoint URI.
version- the OAuth version.
scope- an array of scope strings (OAuth 2.0 only).
scopeSeparator- the scope separator character (OAuth 2.0 only). Only required when a provider has a broken OAuth 2.0 implementation. Defaults to space (Facebook and GitHub default to comma).
headers- a headers object with additional headers required by the provider (e.g. GitHub required the 'User-Agent' header which is set by default).
profile- a function used to obtain user profile information and normalize it. The function signature is
function(credentials, params, get, callback)where:
credentials- the credentials object. Change the object directly within the function (profile information is typically stored under
params- the parsed information received from the provider (e.g. token, secret, and other custom fields).
get- an OAuth helper function to make authenticated requests using the credentials received. The
getfunction signature is
function(uri, params, callback)where:
uri- the requested resource URI (bell will add the token or authentication header as needed).
params- any URI query parameters (cannot include them in the URI due to signature requirements).
callback- request callback with signature
responseis the parsed payload (any errors are handled internally).
callback- the callback function which much be called once profile processing is complete.
password- the cookie encryption password. Used to encrypt the temporary state cookie used by the module in between the authorization protocol steps.
clientId- the OAuth client identifier (consumer key).
clientSecret- the OAuth client secret (consumer secret).
forceHttps- A boolean indicating whether or not you want the redirect_uri to be forced to https. Useful if your hapi application runs as http, but is accessed through https.
location- Set the base redirect_uri manually if it cannot be inferred properly from server settings. Useful to override port, protocol, and host if proxied or forwarded.
Each strategy accepts the following optional settings:
cookie- the name of the cookie used to manage the temporary state. Defaults to
'bell-provider'where 'provider' is the provider name (or
'custom'for custom providers). For example, the Twitter cookie name defaults to
isSecure- sets the cookie secure flag. Defaults to
isHttpOnly- sets the cookie HTTP only flag. Defaults to
ttl- cookie time-to-live in milliseconds. Defaults to
null(session time-life - cookies are deleted when the browser is closed).
domain- the domain scope. Defaults to
providerParams- provider-specific query parameters for the authentication endpoint. Each provider supports its own set of parameters which customize the user's login experience. For example:
display('page', 'popup', or 'touch'),
scope- Each built-in vendor comes with the required scope for basic profile information. Use
scopeto specify a different scope as required by your application. Consult the provider for their specific supported scopes.
config- a configuration object used to customize the provider settings. The built-in
'twitter'provider accepts the
extendedProfileoption which allows disabling the extra profile request when the provider returns the user information in the callback (defaults to
true). The built-in
'phabricator'providers accept the
urioption which allows pointing to a private enterprise installation (e.g.
profileParams- an object of key-value pairs that specify additional URL query parameters to send with the profile request to the provider. The built-in
fieldsspecified to determine the fields returned from the user's graph, which would then be available to you in the
server.auth.strategy() method supports string representations of its boolean and number typed options.
forceHttps can be set to 'true', 'false', 'yes', or 'no'. In effect, this allows you to configure any strategy option using environment variables.
By default, bell will reply back with an internal error (500) on most authentication errors due to the nature of the OAuth protocol. There is little that can be done to recover from errors as almost all of them are caused by implementation or deployment issues.
If you would like to display a useful error page instead of the default JSON response, use the hapi
onPreResponse extension point to transform the
error into a useful page or to redirect the user to another destination.
Another way to handle authentication errors is within the route handler. By default, an authentication error will cause the handler to be
skipped. However, if the authentication mode is set to
'try' instead of
'required', the handler will still be called. In this case,
request.auth.isAuthenticated must be checked to test if authentication failed. In that case,
request.auth.error will contain the error.
To keep track of the token expiry time,
request.auth.credentials.expiresIn provides you the duration (in seconds) after which you could send a refresh token request using the
request.auth.credentials.refreshToken to get a new token.
var Hapi = require'hapi';var server = ;serverconnection port: 8000 ;// Register bell with the serverserverregisterrequire'bell'serverauthstrategy'twitter' 'bell'provider: 'twitter'password: 'cookie_encryption_password'clientId: 'my_twitter_client_id'clientSecret: 'my_twitter_client_secret';serverroutemethod: 'GET' 'POST'path: '/login'config:auth:strategy: 'twitter'mode: 'try'if !requestauthisAuthenticatedreturn reply'Authentication failed due to: ' + requestauth.errormessage;return replyredirect'/home';;serverstart;;