Authentication Client

GitHub stars
@feathersjs/authentication-client"">npm version
Changelog

  1. npm install @feathersjs/authentication-client --save

The @feathersjs/authentication-client module allows you to easily authenticate against a Feathers server. It is not required, but makes it easier to implement authentication in your client by automatically storing and sending the JWT access token and handling re-authenticating when a websocket disconnects.

This module contains:

app.configure(auth(options))

Setup is done the same as all Feathers plugins, using the configure method:

  1. const feathers = require('@feathersjs/feathers');
  2. const socketio = require('@feathersjs/socketio-client');
  3. const io = require('socket.io-client');
  4. const auth = require('@feathersjs/authentication-client');
  6. const socket = io('http://api.feathersjs.com');
  7. const app = feathers();
  9. // Setup the transport (Rest, Socket, etc.) here
  10. app.configure(socketio(socket));
  12. // Available options are listed in the "Options" section
  13. app.configure(auth(options))

> The transports plugins (Rest, Socket, Primus…) must have been initialized previously to the authentication plugin.

Options

The following default options will be mixed in with the settings you pass in when configuring authentication. It will set the mixed options back to to the app so that they are available at any time by app.get('auth'). They can all be overridden.

  1. {
  2.   header: 'Authorization', // the default authorization header for REST
  3.   prefix: '', // if set will add a prefix to the header value. for example if prefix was 'JWT' then the header would be 'Authorization: JWT eyJ0eXAiOiJKV1QiLCJhbGciOi...'
  4.   path: '/authentication', // the server-side authentication service path
  5.   jwtStrategy: 'jwt', // the name of the JWT authentication strategy 
  6.   entity: 'user', // the entity you are authenticating (ie. a users)
  7.   service: 'users', // the service to look up the entity
  8.   cookie: 'feathers-jwt', // the name of the cookie to parse the JWT from when cookies are enabled server side
  9.   storageKey: 'feathers-jwt', // the key to store the accessToken in localstorage or AsyncStorage on React Native
  10.   storage: undefined // Passing a WebStorage-compatible object to enable automatic storage on the client.
  11. }

To enable storing the JWT make sure to provide a storage when configuring the plugin. The following storage options are available:

  • window.localStorage in the browser to use the browsers localStorage
  • AsyncStorage for React Native
  • localForage which helps deal with older browsers and browsers in Incognito / Private Browsing mode.
  • cookie-storage uses cookies. It can be useful on devices that don’t support localStorage.

app.authenticate()

app.authenticate() -> Promise with no arguments will try to authenticate using the JWT from the storage. This is normally called to either show your application (when successful) or showing a login page or redirecting to the appropriate oAuth link.

  1. app.authenticate().then(() => {
  2.   // show application page
  3. }).catch(() => {
  4.   // show login page
  5. })

Important: app.authenticate() has to be called when you want to use the token from storage and only once when the application initializes. Once successful, all subsequent requests will send their authentication information automatically.

app.authenticate(options)

app.authenticate(options) -> Promise will try to authenticate with a Feathers server by passing a strategy and other properties as credentials. It will use whichever transport has been setup on the client (@feathersjs/rest-client, @feathersjs/socketio-client, or @feathersjs/primus-client).

  1. // Authenticate with the local email/password strategy 
  2. app.authenticate({
  3.   strategy: 'local',
  4.   email: 'my@email.com',
  5.   password: 'my-password'
  6. }).then(() => {
  7.   // Logged in
  8. }).catch(e => {
  9.   // Show login page (potentially with `e.message`)
  10.   console.error('Authentication error', e);
  11. });
  13. app.authenticate({
  14.   strategy: 'jwt', 
  15.   accessToken: '<the.jwt.token.string>'
  16. }).then(() => {
  17.   // JWT authentication successful
  18. }).catch(e => {
  19.   console.error('Authentication error', e);
  20.   // Show login page
  21. });
  • data {Object} - of the format {strategy [, ...otherProps]}
    • strategy {String} - the name of the strategy to be used to authenticate. Required.
    • ...otherProps {Properties} vary depending on the chosen strategy. Above is an example of using the jwt strategy. Below is one for the local strategy.

app.logout()

Removes the JWT accessToken from storage on the client. It also calls the remove method of the /authentication service on the Feathers server.

app.passport

app.passport contains helper functions to work with the JWT.

app.passport.getJWT()

Pull the JWT from storage or the cookie. Returns a Promise.

app.passport.verifyJWT(token)

Verify that a JWT is not expired and decode it to get the payload. Returns a Promise.

app.passport.payloadIsValid(token)

Synchronously verify that a token has not expired. Returns a Boolean.

Authentication Events

On the client authentication events are emitted on the app object whenever a client successfully authenticates or “logs out”.
These events are emitted on the client.

app.on(‘authenticated’, callback)

app.on(‘logout’, callback)

app.on(‘reauthentication-error’, errorHandler)

In the event that your server goes down or the client loses connectivity, it will automatically handle attempting to re-authenticate the socket when the client regains connectivity with the server. In order to handle an authentication failure during automatic re-authentication you need to implement the following event listener:

  1. const errorHandler = error => {
  2.   app.authenticate({
  3.     strategy: 'local',
  4.     email: 'admin@feathersjs.com',
  5.     password: 'admin'
  6.   }).then(response => {
  7.     // You are now authenticated again
  8.   });
  9. };
  11. // Handle when auth fails during a reconnect or a transport upgrade
  12. app.on('reauthentication-error', errorHandler)

Hooks

There are 3 hooks. They are really meant for internal use and you shouldn’t need to worry about them very often.

  • populateAccessToken - Takes the token and puts in on hooks.params.accessToken in case you need it in one of your client side services or hooks
  • populateHeader - Add the accessToken to the authorization header
  • populateEntity - Experimental. Populate an entity based on the JWT payload.

Complete Example

Here’s an example of a Feathers server that uses @feathersjs/authentication-client. 

  1. const feathers = require('@feathersjs/feathers');
  2. const rest = require('@feathersjs/rest-client');
  3. const auth = require('@feathersjs/authentication-client');
  5. const superagent = require('superagent');
  6. const localStorage = require('localstorage-memory');
  8. const feathersClient = feathers();
  10. feathersClient.configure(rest('http://localhost:3030').superagent(superagent))
  11.   .configure(auth({ storage: localStorage }));
  13. feathersClient.authenticate({
  14.   strategy: 'local',
  15.   email: 'admin@feathersjs.com',
  16.   password: 'admin'
  17. })
  18. .then(response => {
  19.   console.log('Authenticated!', response);
  20.   return feathersClient.passport.verifyJWT(response.accessToken);
  21. })
  22. .then(payload => {
  23.   console.log('JWT Payload', payload);
  24.   return feathersClient.service('users').get(payload.userId);
  25. })
  26. .then(user => {
  27.   feathersClient.set('user', user);
  28.   console.log('User', feathersClient.get('user'));
  29. })
  30. .catch(function(error){
  31.   console.error('Error authenticating!', error);
  32. });