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:

User accesses page
Check Session
Intercept and jump to authentication login page
Strategy Authentication
Check and store user information
Serialize user information to Session
Jump to the specified page

# 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:

Create a GitHub OAuth Apps to get the clientID and clientSecret information.
Specify a callbackURL, such as http://127.0.0.1:7001/passport/github/callback - You need to update to the corresponding domain name when deploying online - The path is configured via options.callbackURL, which defaults to /passport/${strategy}/callback

# 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:

When signing in for the first time, you generally need to put user information into the repository and record the Session.
In the second login, the user information obtained from OAuth or Session, and the database is read to get the complete user information.

// 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:

ctx.user - Get current logged in user information
ctx.isAuthenticated() - Check if the request is authorized
ctx.login(user, [options]) - Start a login session for the user
ctx.logout() - Exit and clear user information from session
ctx.session.returnTo= - Set redirect address after authentication page success

The API also be provided for:

app.passport.verify(async (ctx, user) => {}) - Check user
app.passport.serializeUser(async (ctx, user) => {}) - Serialize user information into session
app.passport.deserializeUser(async (ctx, user) => {}) - Deserialize user information from the session
app.passport.authenticate(strategy, options) - Generate the specified authentication middleware - options.successRedirect - specifies the redirect address after successful authentication - options.loginURL - jump login address, defaults to /passport/${strategy} - options.callbackURL - callback address after authorization, defaults to /passport/${strategy}/callback
app.passport.mount(strategy, options) - Syntactic sugar for developers to configure routing

Note:

app.passport.authenticate, if options.successRedirect or options.successReturnToOrRedirect is null, it will redirect to / by default

# 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:

$ npm init egg --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);
  }));
};

Passport

# Using egg-passport

# Installation

# Configuration

# Mounting Routes

# User Information Processing

# API

# Using Passport Ecosystem

# Installation

# Configuration

# Mounting Routes

# How to develop an egg-passport plugin

# Using `egg-passport`