# Title: Passport

Login authentication is a common business scenario, including "account password login" and "third-party unified login".

Among them, we often use the latter, such as Google, GitHub, QQ unified login, which are based on OAuth specification.

Passport is a highly scalable authentication middleware that supports the Strategy of Github ,Twitter,Facebook, and other well-known service vendors. It also supports login authorization verification via account passwords.

Egg provides an egg-passport plugin which encapsulates general logic such as callback processing after initialization and the success of authentication so that the developers can use Passport with just a few API calls.

The execution sequence of Passport is as follows:

# Using egg-passport

Below, we will use GitHub login as an example to demonstrate how to use it.

# Installation

$ npm i --save egg-passport
$ npm i --save egg-passport-github

For more plugins, see GitHub Topic - egg-passport .

# Configuration

Enabling the plugin:

// config/plugin.js
module.exports.passport = {
  enable: true,
  package: 'egg-passport'
};

module.exports.passportGithub = {
  enable: true,
  package: 'egg-passport-github'
};

Configuration:

Note: The egg-passport standardizes the configuration fields, which are unified as key and secret.

// config/default.js
config.passportGithub = {
  key: 'your_clientID',
  secret: 'your_clientSecret'
};

note:

# Mounting Routes

// app/router.js
module.exports = app => {
  const { router, controller } = app;

  // Mount the authentication route
  app.passport.mount('github');

  // The mount above is syntactic sugar, which is equivalent to
  // const github = app.passport.authenticate('github', {});
  // router.get('/passport/github', github);
  // router.get('/passport/github/callback', github);
}

# User Information Processing

Then we also need:

// app.js
module.exports = app => {
  app.passport.verify(async (ctx, user) => {
    // Check user
    assert(user.provider, 'user.provider should exists');
    assert(user.id, 'user.id should exists');

    // Find user information from the database
    //
    // Authorization Table
    // column   | desc
    // ---      | --
    // provider | provider name, like github, twitter, facebook, weibo and so on
    // uid      | provider unique id
    // user_id  | current application user id
    const auth = await ctx.model.Authorization.findOne({
      uid: user.id,
      provider: user.provider,
    });
    const existsUser = await ctx.model.User.findOne({ id: auth.user_id });
    if (existsUser) {
      return existsUser;
    }
    // Call service to register a new user
    const newUser = await ctx.service.user.register(user);
    return newUser;
  });

  // Serialize and store the user information into session. Generally, only a few fields need to be streamlined/saved.
  app.passport.serializeUser(async (ctx, user) => {
  // process user
  // ...
  // return user;
  });

  // Deserialize the user information from the session, check the database to get the complete information
  app.passport.deserializeUser(async (ctx, user) => {
  // process user
  // ...
  // return user;
  });
};

At this point, we have completed all the configurations. For a complete example, see: eggjs/examples/passport

# API

egg-passport provides the following extensions:

The API also be provided for:

# Using Passport Ecosystem

Passport has many middleware and it is impossible to have the second encapsulation. Next, let's look at how to use Passport middleware directly in the framework. We will use passport-local for "account password login" as an example:

# Installation

$ npm i --save passport-local

# Configuration

// app.js
const LocalStrategy = require('passport-local').Strategy;

module.exports = app => {
  // Mount strategy
  app.passport.use(new LocalStrategy({
    passReqToCallback: true,
  }, (req, username, password, done) => {
    // format user
    const user = {
      provider: 'local',
      username,
      password,
    };
    debug('%s %s get user: %j', req.method, req.url, user);
    app.passport.doVerify(req, user, done);
  }));

  // Process user information
  app.passport.verify(async (ctx, user) => {});
  app.passport.serializeUser(async (ctx, user) => {});
  app.passport.deserializeUser(async (ctx, user) => {});
};

# Mounting Routes

// app/router.js
module.exports = app => {
  const { router, controller } = app;
  router.get('/', controller.home.index);

  // Callback page after successful authentication
  router.get('/authCallback', controller.home.authCallback);

  // Render login page, user inputs account password
  router.get('/login', controller.home.login);
  // Login verification
  router.post('/login', app.passport.authenticate('local', { successRedirect: '/authCallback' }));
};

# How to develop an egg-passport plugin

In the previous section, we learned how to use a Passport middleware in the framework. We can further encapsulate it as a plugin and give back to the community.

initialization:

$ egg-init --type=plugin egg-passport-local

Configure dependencies in package.json:

{
  "name": "egg-passport-local",
  "version": "1.0.0",
  "eggPlugin": {
    "name": "passportLocal",
    "dependencies": ["passport"]
  },
  "dependencies": {
    "passport-local": "^1.0.0"
  }
}

Configuration:

// {plugin_root}/config/config.default.js
// https://github.com/jaredhanson/passport-local
exports.passportLocal = {
};

Note: egg-passport standardizes the configuration fields, which are unified as key and secret, so if the corresponding Passport middleware attribute names are inconsistent, the developer should do the conversion.

Register the passport middleware:

// {plugin_root}/app.js
const LocalStrategy = require('passport-local').Strategy;

module.exports = app => {
  const config = app.config.passportLocal;
  config.passReqToCallback = true;

  app.passport.use(new LocalStrategy(config, (req, username, password, done) => {
    // Cleans up the data returned by the Passport plugin and returns the User object
    const user = {
      provider: 'local',
      username,
      password,
    };
    // This does not process application-level logic and passes it to app.passport.verify for unified processing.
    app.passport.doVerify(req, user, done);
  }));
};