node package manager


User authentication plugin for the seneca module.

A Seneca.js Auth Plugin


A user authentication plugin, using PassportJS for Express and Bell for Hapi.

Table of Contents

Lead Maintainers: Mircea Alexandru and Mihai Dima

For a gentle introduction to Seneca itself, see the site.

If you're using this plugin module, feel free to contact me on twitter if you have any questions! :) @rjrodger


npm install seneca-auth

Migration guide

Please see bellow the migration guide from older version to 0.4.x or above version.

A large part of the internal functionality of seneca-auth is now implemented as external plugins. Some of them are loaded by default in order to offer the basic functionality, some must be loaded explicitly.

Plugins and modules

Functionality Loaded by default plugin
Local strategy auth No seneca-local-auth
Facebook strategy auth No seneca-facebook-auth
Github strategy auth No seneca-github-auth
Google strategy auth No seneca-google-auth
LinkedIn strategy auth No seneca-linkedin-auth
Twitter strategy auth No seneca-twitter-auth
Redirect Yes auth-redirect
Cookie token Yes auth-token-cookie
Header token No seneca-auth-token-header
Url matcher Yes auth-urlmatcher
Restrict Login No seneca-auth-restrict-login

Check the documentation of each plugin for details.

Note about node version support

Hapi is supported only if using node 4 or greater. When using node 0.1x only Express is supported.

Options deprecated or no longer supported

Some options are no longer supported:

  • service - the service array that defines the auth strategies is no longer supported. Instead of this the auth strategies plugins must be loaded explicitly, each with its own options.
  • sendemail - the send email option (and send email functionality) is no longer supported.
  • email - see above

When one of these parameters are provided to seneca-auth it will be considered a fatal error. Please remove them from seneca-auth options and check the documentation.

Some options are deprecated:

Restrict Login

Different conditions for login can be added by simply overriding the default behavior of seneca action with pattern:

role: 'auth', restrict: 'login'

This function must return:

  • an object with at least { ok: true } in case that login is allowed based on the implemented rules
  • an object with at least { ok: false, why: 'reason' } in case that login is not allowed based on the implemented rules.

An example of this implementation is provided by the plugin seneca-auth-restrict-login. The restrict condition implemented by this plugin is based on the existence of a cookie value in the request.

If more conditions are required these can be implemented in separated seneca actions. All actions can then be added to seneca but make sure to call seneca.prior from each action to make sure that all conditions in the chain are verified.

JSON API and Redirects

NOTE: Take a look at the user accounts example or seneca-mvp example.

The redirect functionality is now implemented as a separate module. Please see auth-redirect documentation for details.

The redirect module is loaded by default by seneca-auth.


Login an existing user and set a login token. A new login entity is created for each login.

  • default url path: /auth/login
  • options property: urlpath.login

Logout an existing user with an active login. The login entity is updated to reflect the end of the login.

  • default url path: /auth/logout
  • options property: urlpath.logout

Get the details of an existing, logged in user.

  • default url path: /auth/user
  • options property: urlpath.user

This was previously the /auth/instance.

Register a user and login automatically.

  • default url path: /auth/register
  • options property: urlpath.register
  • body should contain user information. Please refer to seneca-user at cmd: register documentation for details.

Create a reset token

  • default url path: /auth/create_reset
  • options property: urlpath.create_reset
  • Please refer to seneca-user at cmd: create_reset documentation for details.

Note: The response will not contain reset token or user data. The client of this application should make sure to re-define this action and send email to the user with reset token.

Load a user entity using a reset token.

  • default url path: /auth/load_reset
  • options property: urlpath.load_reset
  • Please refer to seneca-user at cmd: load_reset documentation for details.

Execute a password reset action.

  • default url path: /auth/execute_reset
  • options property: urlpath.execute_reset
  • Please refer to seneca-user at cmd: execute_reset documentation for details.

Update user data.

  • default url path: /auth/update_user
  • options property: urlpath.update_user
  • Please refer to seneca-user at cmd: update_user documentation for details.

Change user password.

  • default url path: /auth/change_password
  • options property: urlpath.change_password
  • Please refer to seneca-user at cmd: change_password documentation for details.

Example of using seneca-auth with Hapi

var _ = require('lodash')
var Chairo = require('chairo')
var Hapi = require('hapi')
var Bell = require('bell')
var Hapi_Cookie = require('hapi-auth-cookie')
var server = new Hapi.Server()
server.register([Hapi_Cookie, Bell, Chairo], function (err) {
  var si = server.seneca
      secure: true,
      restrict: '/api'
  si.add({role: 'test', cmd: 'service'}, function (args, cb) {
    return cb(null, {something: 'else'})
    role: 'web',
    plugin: 'test',
    use: {
      prefix: '/api',
      pin: {role: 'test', cmd: '*'},
      map: {
        service: {GET: true}
  }, function(err){
    server.start(function () {


npm test