hapi-auth-token
This Hapi plugin provides a token based authentication scheme.
The authentication scheme secures endpoints with token authentication, and exposes hooks to validate
the received tokens & set custom credentials object onto authenticated Hapi requests (which will be
accessible as request.auth.credentials
in the route handlers post-authentication).
User authentication and token generation should be handled by the application.
The scheme will automatically extract auth token from Cookie, Header or Query parameter,
making it convenient to use any of those modes for token authentication.
Installation
npm install --save hapi-auth-token
OR
yarn add hapi-auth-token
Example Applications
- hapi-auth-token-db-example: Using
hapi-auth-token
to authenticate users against a SQL DB. - hapi-auth-token-jwt-example: Using
hapi-auth-token
with JWT tokens.
Usage
Follow these steps to use this plugin in your Hapi application.
- Register the plugin
; await server
- Configure an auth strategy from the
token-auth
scheme
const strategyOptions = cookie: name: '__AUTH' // Auth cookie name isSecure: false header: false // Disable extracting token from the "Authorization" header query: name: 'authToken' // Name of the query parameter to read the auth token from async { // Verify whether the token is valid, for example, against a list of existing tokens like below return modelsUserToken; } async { // Identify user based on the token information // Return a credentials object based on the identified user information // The object returned from this method will be accessible as `request.auth.credentials` in authenticated handlers const user = await modelsUser; return id: userid profile: userprofileId ; }; this_serverauth;
The key parameters in configuration of the strategy are the validateToken
and buildAuthCredentials
functions.
validateToken
will be called with the extracted authentication token, and is expected to respond back with a boolean indicating whether the token is valid.buildAuthCredentials
will be called ifvalidateToken
returns true, and is expected to return a JSON object, which will be set as the auth credentials for the current request. The object returned by this function will be accessible asrequest.auth.credentials
in the authenticated route handlers.
Here's a more elaborate snippet:
;; const server = ; { // Register the HapiAuthToken plugin await server; // Initialize plugin/strategy options const strategyOptions = cookie: name: '__AUTH' // Auth cookie name isSecure: false header: false // Disable extracting token from the "Authorization" header query: name: 'authToken' // Name of the query parameter to read the auth token from async { // Verify whether the token is valid, for example, against a list of existing tokens like below return modelsUserToken; } async { // Identify user based on the token information // Return a credentials object based on the identified user information // The object returned from this method will be accessible as `request.auth.credentials` in authenticated handlers const user = await modelsUser; return id: userid profile: userprofileId ; } ; // Register an authentication strategy based on the HapiAuthToken scheme this_serverauth; this_serverauth;} ;
API
The plugin can be configured during plugin registration, and/or during auth strategy registration. Options can be passed during plugin registration like this:
await server;
Or during strategy registration like this:
serverauth;
Note that the final set of options would be a combination of these two option sets, and the options provided to the strategy will override plugin level options when there's a conflict.
Plugin/Strategy Options
cookie
false
or anobject
false
will disable reading auth tokens from cookies- Hapi cookie options object (https://github.com/hapijs/hapi/blob/master/API.md#-serverstatename-options) to configure the auth cookie.
name
is the name of the auth cookie. Defaults to__TOKEN_AUTH
header
- Boolean indicating whether token authentication via the
Authorization
header should be enabled- If
true
, the plugin will read auth-token from theAuthorization: Token <auth-token>
header - If
false
,Authorization
headers are ignored by the plugin - Defaults to
true
- If
- Boolean indicating whether token authentication via the
query
false
or anobject
false
will disable reading auth tokens from query parameters- An options object with the following attributes can be provided to enable reading auth tokens from query parameters
name
is the name of the query parameter to read the auth token from. Defaults to thetoken
parameter.
- Defaults to:
{name: 'token'}
validateToken
- A function that accepts an auth token (string) and returns a boolean indicating whether the supplied token is valid.
- This is where you can customize the token validation logic, and this is a required parameter.
buildAuthCredentials
- A function that accepts an auth token (string) and returns a JSON object that would be set as the credentials object on authenticated requests.
- This will be invoked only if
validateToken
returns true. - The object returned by this function will be accessible as
request.auth.credentials
in authenticated route handlers.