koa Passport中间件

刘浩思

2023-12-01

1.综述 GENERAL
- 1.1. 概览 Overview
- 1.2. 认证 Authenticate
  - 1.2.1. 重定向 Redirects
  - 1.2.2. 快报 Flash Messages
  - 1.2.3. 禁用会话 Disable Sessions
  - 1.2.4. 自定义回调函数 Custom Callback
- 1.3. 配置 Configure
  - 1.3.1. 策略 Strategies
  - 1.3.2. 验证回调 Verify Callback
  - 1.3.3. 中间件 Middleware
  - 1.3.4. 会话 Session
- 1.4. 用户名和密码 Username & Password
  - 1.4.1. 配置 Configuration
  - 1.4.2. 表格 Form
  - 1.4.3. 路由 Route
  - 1.4.4. 参数 Parameters
- 1.5. OpenID
- 1.6. OAuth
2.内置操作 Operations
- 2.1. 登录 Log In
- 2.2. 注销 Log Out
- 2.3. 授权 Authorize
3.具体流程
- 3.1. 第一次访问 (GET)
- 3.2. 第二次访问 (POST)
- 3.3. 第三次访问 (GET)
- 3.4. 用户注销 (GET)

1.1. 概览 Overview

Passport 是 Node 的认证中间件，它的存在只有一个单一的目的，就是认证请求。
在 Passport 设计理念中就认为每一个网络应用拥有不同的认证需求。因此为了满足各种网络应用，被称作策略的认证机制被封装成单一的模块中，网络应用可自由选择不同策略来实现认证功能。认证机制本身可能比较复杂，但是在 Passport 中编写的代码并没有那么繁琐：

app.post('/login', 
	passport.authenticate('local', 
	{ successRedirect: '/', 
	  failureRedirect: '/login' 
	} ));

当然首先需要安装 Passport：

$ npm install passport

1.2. 认证 Authenticate

通过调用 passport.authenticate()方法及配置相应的策略，就可实现认证网络请求。 authenticate()方法是标准的Node 中间件，在 Express 应用中可以非常方便的作为路由使用

app.post('/login',
  passport.authenticate('local'),
  function(req, res) {
    // 如果认证通过，将触发该函数
    // `req.user` 字段内有认证的用户名.
    res.redirect('/users/' + req.user.username);
  });

在默认情况下，认证失败后 Passport 会返回 401 Unauthorized 状态的响应，其后面的处理函数也不会被触发。当然认证成功后，处理函数被触发并将认证用户信息作为值赋值给 req.user

注意：策略必须在路由使用它之前进行配置。

1.2.1. 重定向 Redirects

在认证请求后通常接下来需要处理的事务就是重定向

app.post('/login',
  passport.authenticate('local', 
  { successRedirect: '/',
    failureRedirect: '/login' 
  })
);

上述代码中，如果认证成功将会被重定向到首页，如果失败会重新来到登录页面。

1.2.2. 快报 Flash Messages

当认证失败后客户端被重定向到登录页面，重定向后的页面中经常会显示一些状态提示信息，如：登录失败。那么如何分辨登录页面是认证失败后的重定向还是第一次访问？区别它们的方法就是在 session 中写入一个特殊的标识 flash 。

app.post('/login',
  passport.authenticate('local', 
  { successRedirect: '/',
    failureRedirect: '/login',
    failureFlash: true 
  })
);

上述代码会在认证失败后，将策略的认证函数中返回的信息写入 flash。这是最常用和最好的方法，因为每个策略的认证函数都会把认证失败的准确信息返回。
当然也可以自定义快报：

passport.authenticate('local',
  {failureFlash: 'Invalid username or password.' }
);

或者是认证成功后的快报：

passport.authenticate('local', 
  { successFlash: 'Welcome!' }
);

注意：在 Express 4.x 中使用快报需要添加 connect-flash 中间件。

1.2.3. 禁用会话 Disable Sessions

由于 HTTP 是无状态协议，所以在认证成功后通常是将登录信息保存在 session 中。但是在某些情况下并不需要 session，如 API 服务需要证书来认证，此时可以放心的禁用会话。

app.get('/api/users/me',
  passport.authenticate('basic', 
  { session: false }),
  function(req, res) {
    res.json({ id: req.user.id, 
      username: req.user.username 
  	});
  });

1.2.4. 自定义回调函数 Custom Callback

在处理认证请求时，可自定义回调函数来处理成功或失败的认证。

app.get('/login', function(req, res, next) {
  passport.authenticate('local', 
    function(err, user, info) {
      if (err) { return next(err); }
      if (!user) { return res.redirect('/login'); }
      req.logIn(user, function(err) {
        if (err) { return next(err); }
        return res.redirect('/users/' + user.username);
    });
  })(req, res, next);
});

上例中，方法 authenticate() 没有作为路由的中间件出现，而是在路由的处理函数中被调用。该方法的回调函数的参数通过闭包从路由中传入。如果认证失败user将被赋值为 false。出现异常 err会被初始化并返回异常信息。可选的 info则返回策略中相关信息。

注意：使用自定义回调函数，应用必须建立一个 session （上例通过 req.logIn()）并发送响应。

1.3. 配置 Configure

在认证过程中 Passport 需要配置三个部分：

认证策略
应用中间件
会话（可选）

1.3.1. 策略 Strategies

Passport 通过策略来认证网络请求。策略可以是用户名和密码的确认认证，可以是 OAuth 的委派认证，还可以是 OpenID 的联合认证。正如上文所提到的策略在使用前必须进行配置。
策略及其配置通过 use()方法实现。比如接下来的通过用户名和密码的认证策略LocalStrategy:

var passport = require('passport')
var LocalStrategy = require('passport-local').Strategy;

passport.use(new LocalStrategy(
  function(username, password, done) {
    User.findOne({ username: username }, 
    function (err, user) {
      if (err) { return done(err); }
      if (!user) {
        return done(null, false, 
        { message: 'Incorrect username.' });
      }
      if (!user.validPassword(password)) {
        return done(null, false, 
        { message: 'Incorrect password.' });
      }
      return done(null, user);
    });
  }
));

1.3.2. 验证回调 Verify Callback

上面的例子中有个很重要的概念：策略中需要验证回调。验证回调目的是找到拥有认证信息的用户。
当 Passport 验证一个请求时，会解析请求中的认证信息，然后将认证信息发送给验证回调函数同时触发该函数。如果认证信息有效，验证回调函数触发done函数，将认证的用户信息返回给 Passport 。

return done(null, user);

如果认证信息无效， done 函数同样也会被触发，但是返回的是false。

return done(null, false);

些附加信息可以追加在 done函数的第三个参数中，这些信息可用来呈现快报。

return done(null, false, { message: 'Incorrect password.' });

最后如果在验证过程中出现异常，done函数可以传递一个 Node 风格的 err 信息。

return done(err);

注意：区分开两种验证失败的原因，如果是服务器的异done函数的第一个参数 err设置为非空值；验证条件的失败要确保 err为 null。

这种委派方式确保了 Passport 数据库对验证回调函数的透明，应用可任意选择用户信息的存储方式。

1.3.3. 中间件 Middleware

在 Express 应用中，passport.initialize()中间件可初始化 Passport，passport.session()中间件用来存储用户登录的 session 信息。

var app = express();
app.use(require('serve-static')(__dirname + '/../../public'));
app.use(require('body-parser').urlencoded({ extended: true }));
app.use(require('express-session')({ secret: 'keyboard cat', resave: true, saveUninitialized: true }));
app.use(passport.initialize());
app.use(passport.session());

注意：passport.initialize()中间件应该在passport.session()中间件前面。

1.3.4. 会话 Session

在典型的网络应用中，登录请求中包含验证用户的认证信息。如果认证成功，用户浏览器中通过 cookie 创建并保存 sessionID。随后所有的请求不再需要验证，而是通过 sessionID 来识别用户。Passport 可以将 session 中的用户信息序列化或反序列化，以此支持 session 机制。

passport.serializeUser(function(user, done) {
  done(null, user.id);
});

passport.deserializeUser(function(id, done) {
  User.findById(id, function(err, user) {
    done(err, user);
  });
});

上述代码中，user ID 被序列化到 session 中，接下来的请求中，通过 user ID 获取用户信息并将其存入到 req.user中
序列化和反序列化的逻辑由应用提供，可以选择适合的数据库存储会话，在认证层面这些操作没有任何的限制。

1.4. 用户名和密码 Username & Password

网络中最常用的方式就是通过用户名和密码进行认证，提供这种认证的策略是 passport-local。

npm install passport-local

1.4.1. 配置 Configuration

var passport = require('passport')
  , LocalStrategy = require('passport-local').Strategy;

passport.use(new LocalStrategy(
  function(username, password, done) {
    User.findOne({ username: username }, function(err, user) {
      if (err) { return done(err); }
      if (!user) {
        return done(null, false, 
        { message: 'Incorrect username.' });
      }
      if (!user.validPassword(password)) {
        return done(null, false, 
        { message: 'Incorrect password.' });
      }
      return done(null, user);
    });
  }
));

本地认证的验证回调函数接受username和password两个参数。

1.4.2. 表格 Form

表格提供了username和password这两个参数：

<form action="/login" method="post">
    <div>
        <label>Username:</label>
        <input type="text" name="username"/>
    </div>
    <div>
        <label>Password:</label>
        <input type="password" name="password"/>
    </div>
    <div>
        <input type="submit" value="Log In"/>
    </div>
</form>

1.4.3. 路由 Route

登录表格信息通过POST方法提交给服务器，local策略使用authenticate()函数处理登录请求：

app.post('/login',
  passport.authenticate('local', 
    { successRedirect: '/',
      failureRedirect: '/login',
      failureFlash: true 
    })
);

设置failureFlash选项为true，意味着在验证回调函数中返回的message信息将成为错误快报的值。

1.4.4. 参数 Parameters

默认情况下，localStrategy策略使用username 和 password作为认证机制的参数，实际上其他字段也可以作为参数进行验证：

passport.use(new LocalStrategy({
    usernameField: 'email',
    passwordField: 'passwd'
  },
  function(username, password, done) {
    // ...
  }
));

1.5. OpenID

暂时用不到

1.6. OAuth

暂时用不到

2. 内置操作 Operations

2.1. 登录 Log In

Passport 通过暴露给req的login()方法建立登录会话。

req.login(user, function(err) {
  if (err) { return next(err); }
  return res.redirect('/users/' + req.user.username);
});

登录操作完成后，用户信息被指派在req.user 上。

注意：passport.authenticate()中间件会自动触发req.login()。这项功能主要使用在用户注册时，调用 req.login()方法自动登录新注册的用户。

2.2. 注销 Log Out

与login()相反，logout()方法用来结束登录会话。调用 logout()方法会删除req.user属性并清除登录会话。

app.get('/logout', function(req, res){
  req.logout();
  res.redirect('/');
});

2.3. 授权 Authorize

暂时用不到

3. 具体流程

3.1. 第一次访问 (GET)

客户端访问服务器登录页面。
服务器生成sessionid。 (express-session)
服务器将seesionid对应的session保存在数据库中。 (express-session)
在session中添加crsf。 (cursf)
服务器将sessionid保存到cookie中，返回给客户端，同时将csrf token返回给客户端。 (express-session)
客户端保存cookie。
客户端填写登录内容。

3.2. 第二次访问 (POST)

客户端将登陆内容、cookie和csrf token发送给服务器。
服务器查找对应sessionid的session。 (express-session)
服务器验证csrf token。 (cursf)
服务器验证登录内容。 (passport/autenticate)
服务器将用户信息挂载在 req.user。 (passport/req.login)
将用户信息序列化成userid保存到session中。 (passport/serialize)
服务器重定向。

3.3. 第三次访问 (GET)

客户端访问页面。
客户端发送cookie和csrf token。
服务器查找与sessionid对应session。 (express-session)
服务器验证csrf token。(GET 方法忽略验证)
服务器将session中的userid反序列化，附加到 req.user。 (passport/deserialize)
服务器返回用户内容。

3.4. 用户注销 (GET)

客户端发送注销信息
客户端发送出去cookie和csrf token。
服务器查找sessionid对应的session。 (express-session)
服务器调用req.logout将userid从session删除。 (passport/req.logout)
服务器重定向。

koa Passport中间件

1.1. 概览 Overview

1.2. 认证 Authenticate

1.2.1. 重定向 Redirects

1.2.2. 快报 Flash Messages

1.2.3. 禁用会话 Disable Sessions

1.2.4. 自定义回调函数 Custom Callback

1.3. 配置 Configure

1.3.1. 策略 Strategies

1.3.2. 验证回调 Verify Callback

1.3.3. 中间件 Middleware

1.3.4. 会话 Session

1.4. 用户名和密码 Username & Password

1.4.1. 配置 Configuration

1.4.2. 表格 Form

1.4.3. 路由 Route

1.4.4. 参数 Parameters

1.5. OpenID

1.6. OAuth

2. 内置操作 Operations

2.1. 登录 Log In

2.2. 注销 Log Out

2.3. 授权 Authorize

3. 具体流程

3.1. 第一次访问 (GET)

3.2. 第二次访问 (POST)

3.3. 第三次访问 (GET)

3.4. 用户注销 (GET)

相关阅读

相关文章

相关问答

相关文档