OAuth1 Authentication

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

  1. $ npm install @feathersjs/authentication-oauth1 --save

@feathersjs/authentication-oauth1 is a server side module that allows you to use any Passport OAuth1 authentication strategy within your Feathers application, most notably Twitter.

This module contains 2 core pieces:

  1. The main initialization function
  2. The Verifier class

Configuration

In most cases initializing the module is as simple as doing this:

  1. const feathers = require('@feathersjs/feathers');
  2. const authentication = require('@feathersjs/authentication');
  3. const jwt = require('@feathersjs/authentication-jwt');
  4. const oauth1 = require('@feathersjs/authentication-oauth1');
  6. const session = require('express-session');
  7. const TwitterStrategy = require('passport-twitter').Strategy;
  8. const app = feathers();
  10. // Setup in memory session
  11. app.use(session({
  12.   secret: 'super secret',
  13.   resave: true,
  14.   saveUninitialized: true
  15. }));
  17. // Setup authentication
  18. app.configure(authentication(settings));
  19. app.configure(jwt());
  20. app.configure(oauth1({
  21.   name: 'twitter',
  22.   Strategy: TwitterStrategy,
  23.   consumerKey: '<your consumer key>',
  24.   consumerSecret: '<your consumer secret>'
  25. }));
  27. // Setup a hook to only allow valid JWTs to authenticate
  28. // and get new JWT access tokens
  29. app.service('authentication').hooks({
  30.   before: {
  31.     create: [
  32.       authentication.hooks.authenticate(['jwt'])
  33.     ]
  34.   }
  35. });

This will pull from your global authentication object in your config file. It will also mix in the following defaults, which can be customized.

Registering the OAuth1 plugin will automatically set up routes to handle the OAuth redirects and authorization.

Options

  1. {
  2.     idField: '<provider>Id', // The field to look up the entity by when logging in with the provider. Defaults to '<provider>Id' (ie. 'twitterId').
  3.     path: '/auth/<provider>', // The route to register the middleware
  4.     callbackURL: 'http(s)://hostame[:port]/auth/<provider>/callback', // The callback url. Will automatically take into account your host and port and whether you are in production based on your app environment to construct the url. (ie. in development http://localhost:3030/auth/twitter/callback)
  5.     entity: 'user', // the entity that you are looking up
  6.     service: 'users', // the service to look up the entity
  7.     passReqToCallback: true, // whether the request object should be passed to `verify`
  8.     session: true, // whether to use sessions,
  9.     handler: function, // Express middleware for handling the oauth callback. Defaults to the built in middleware.
  10.     formatter: function, // The response formatter. Defaults the the built in feathers-rest formatter, which returns JSON.
  11.     Verifier: Verifier // A Verifier class. Defaults to the built-in one but can be a custom one. See below for details.
  12. }

Additional passport strategy options can be provided based on the OAuth1 strategy you are configuring.

Verifier

This is the verification class that handles the OAuth1 verification by looking up the entity (normally a user) on a given service and either creates or updates the entity and returns them. It has the following methods that can all be overridden. All methods return a promise except verify, which has the exact same signature as passport-oauth1.

  1. {
  2.     constructor(app, options) // the class constructor
  3.     _updateEntity(entity) // updates an existing entity
  4.     _createEntity(entity) // creates an entity if they didn't exist already
  5.     _normalizeResult(result) // normalizes result from service to account for pagination
  6.     verify(req, accessToken, refreshToken, profile, done) // queries the service and calls the other internal functions.
  7. }

The Verifier class can be extended so that you customize it’s behavior without having to rewrite and test a totally custom local Passport implementation. Although that is always an option if you don’t want use this plugin.

An example of customizing the Verifier:

  1. import oauth1, { Verifier } from '@feathersjs/authentication-oauth1';
  3. class CustomVerifier extends Verifier {
  4.   // The verify function has the exact same inputs and 
  5.   // return values as a vanilla passport strategy
  6.   verify(req, accessToken, refreshToken, profile, done) {
  7.     // do your custom stuff. You can call internal Verifier methods
  8.     // and reference this.app and this.options. This method must be implemented.
  10.     // the 'user' variable can be any truthy value
  11.     // the 'payload' is the payload for the JWT access token that is generated after successful authentication
  12.     done(null, user, payload);
  13.   }
  14. }
  16. app.configure(oauth1({
  17.   name: 'twitter'
  18.   Strategy: TwitterStrategy,
  19.   consumerKey: '<your consumer key>',
  20.   consumerSecret: '<your consumer secret>',
  21.   Verifier: CustomVerifier
  22. }));

Customizing The OAuth Response

Whenever you authenticate with an OAuth1 provider such as Twitter, the provider sends back an accessToken, refreshToken, and a profile that contains the authenticated entity’s information based on the OAuth1 scopes you have requested and been granted.

By default the Verifier takes everything returned by the provider and attaches it to the entity (ie. the user object) under the provider name. You will likely want to customize the data that is returned. This can be done by adding a before hook to both the update and create service methods on your entity‘s service.

  1. app.configure(oauth1({
  2.   name: 'twitter',
  3.   entity: 'user',
  4.   service: 'users',
  5.   Strategy,
  6.   consumerKey: '<your consumer key>',
  7.   consumerSecret: '<your consumer secret>'
  8. }));
  10. function customizeTwitterProfile() {
  11.   return function(context) {
  12.     console.log('Customizing Twitter Profile');
  13.     // If there is a twitter field they signed up or
  14.     // signed in with twitter so let's pull the email. If
  15.     if (context.data.twitter) {
  16.       context.data.email = context.data.twitter.email; 
  17.     }
  19.     // If you want to do something whenever any OAuth
  20.     // provider authentication occurs you can do this.
  21.     if (context.params.oauth) {
  22.       // do something for all OAuth providers
  23.     }
  25.     if (context.params.oauth.provider === 'twitter') {
  26.       // do something specific to the twitter provider
  27.     }
  29.     return Promise.resolve(context);
  30.   };
  31. }
  34. app.service('users').hooks({
  35.   before: {
  36.     create: [customizeTwitterProfile()],
  37.     update: [customizeTwitterProfile()]
  38.   }
  39. });

Client Usage

When this module is registered server side, whether you are using feathers-authentication-client or not the user has to navigate to the authentication strategy url. This could be by setting window.location or through a link in your app.

For example you might have a login button for Twitter:

  1. <a href="/auth/twitter" class="button">Login With Twitter</a>