摘要：機(jī)翻潤色這個(gè)模塊可以讓你在你的應(yīng)用中通過使用以下簡稱認(rèn)證請求這個(gè)文檔做了一個(gè)很好的介紹如果你使用版本同時(shí)你有一個(gè)低于版本的安裝主分支倉庫上的譯者注上的版本使用所以必須是以上如果你使用你需要從安裝這個(gè)代碼在分支上安裝用例認(rèn)證中間件

node>=7.6.0

npm v3.2.2

這個(gè)模塊可以讓你在你的KOA應(yīng)用中通過使用JSON WEB TOKEN(以下簡稱JWT)認(rèn)證HTTP請求

這個(gè)文檔做了一個(gè)很好的介紹.

如果你使用KOA版本2.+,同時(shí)你有一個(gè)低于7.6版本的node. 安裝koa-jwt@2

主分支(Koajwt git倉庫上的.譯者注)上的koa-jwt版本3+使用async/await,所以必須是node 7.6以上

如果你使用koa1,你需要從npm安裝koa-jwt@1.這個(gè)代碼在koa-v1分支上

$ npm install koa-jwt

JWT認(rèn)證中間件的認(rèn)證通過使用JWT令牌(token,譯者注).如果令牌有效,ctx.state.user(默認(rèn)情況下)會被設(shè)置成解碼的JSON對象,以便于在稍后的中間件中進(jìn)行認(rèn)證或訪問控制.

令牌通常被包產(chǎn)在一個(gè)名為Authorization的HTTP頭中,但也能通過cookie來進(jìn)行,但是也可以使用Cookie來提供令牌,只要在opts.cookie選項(xiàng)上設(shè)置為包含令牌的cookie的名稱.也可以通過opts.getToken選項(xiàng)完成自定義的令牌檢索.返回的函數(shù)應(yīng)該匹配以下接口:

/**
 * 自定義令牌解析器
 * @this 傳入中間件的CTX對象
 *
 * @param  {object} opts     中間件選項(xiàng)
 * @return {String|null}    返回被解析的令牌,如果沒有找到則返回null
 */

令牌解析順序如下所示.第一個(gè)被解析的非空令牌將被用于驗(yàn)證

運(yùn)行opts.getToken 函數(shù)

檢查cookies(如果cookies被設(shè)置了)

檢查承載令牌的認(rèn)證頭(header)

通常你在opts.secret中提供了一個(gè)多帶帶的開放密鑰,但是另一個(gè)替代方案是在一個(gè)更靠前的中間件中設(shè)置ctx.state.secret,通常是每個(gè)請求中.如果這個(gè)屬性存在,它將用來替換opts.secret中的密鑰.

你可以提供一個(gè)異步的函數(shù)來讓koa-jwt檢查令牌是否被撤銷.這個(gè)函數(shù)應(yīng)該被設(shè)置再opts.isRevoked屬性中.你提供的函數(shù)應(yīng)該匹配以下接口:

/**
 * 你自定義的檢索撤銷解析器
 *
 * @param  {object}      ctx     傳遞給中間件的CTX對象
 * @param  {object}      token     令牌
 * @param  {object}      user     令牌的內(nèi)容
 * @return {Promise}     如果令牌沒有被銷毀, Promise必須被解析為false,其他情況下(Promise解析為true或erro)令牌被銷毀.
 */

var Koa = require("koa");
var jwt = require("koa-jwt");

var app = new Koa();

// Custom 401 handling if you don"t want to expose koa-jwt errors to users
app.use(function(ctx, next){
  return next().catch((err) => {
    if (401 == err.status) {
      ctx.status = 401;
      ctx.body = "Protected resource, use Authorization header to get access
";
    } else {
      throw err;
    }
  });
});

// Unprotected middleware
app.use(function(ctx, next){
  if (ctx.url.match(/^/public/)) {
    ctx.body = "unprotected
";
  } else {
    return next();
  }
});

// Middleware below this line is only reached if JWT token is valid
app.use(jwt({ secret: "shared-secret" }));

// Protected middleware
app.use(function(ctx){
  if (ctx.url.match(/^/api/)) {
    ctx.body = "protected
";
  }
});

app.listen(3000);

你也可以在某些條件下有條件的運(yùn)行koa-jwt中間件:

var koa = require("koa");
var jwt = require("koa-jwt");

var app = new Koa();

// Middleware below this line is only reached if JWT token is valid
// unless the URL starts with "/public"
app.use(jwt({ secret: "shared-secret" }).unless({ path: [/^/public/] }));

// Unprotected middleware
app.use(function(ctx, next){
  if (ctx.url.match(/^/public/)) {
    ctx.body = "unprotected
";
  } else {
    return next();
  }
});

// Protected middleware
app.use(function(ctx){
  if (ctx.url.match(/^/api/)) {
    ctx.body = "protected
";
  }
});

app.listen(3000);

更多關(guān)于unless的例子,請點(diǎn)擊koa-unless

即使沒有找到認(rèn)證頭,你也可以通過添加一個(gè)passthrough選項(xiàng)來保證始終傳遞到下一個(gè)(中間件)

app.use(jwt( { secret: "shared-secret", passthrough:true }))

通過這個(gè)選項(xiàng),使得下游中間件可以基于ctx.state.user是否設(shè)置做出決定

如果你更喜歡使用另外一個(gè)ctx key來表示解碼數(shù)據(jù),只需要傳入key屬性,如下:

app.use(jwt({ secret: "shared-secret", key: "jwtdata" }));

此時(shí)解碼數(shù)據(jù)可以通過ctx.state.jwtdata得到(替換掉默認(rèn)的ctx.state.user)

你同樣可以指定audience和/或issuer

app.use(jwt({ secret:   "shared-secret",
              audience: "http://myapi/protected",
              issuer:   "http://issuer" }));

如果koa-jwt有設(shè)置一個(gè)expiration(exp),它將會被檢查到.

如果存在tokenkey 選項(xiàng),并且找到有效的令牌,原始令牌數(shù)據(jù)可以從隨后的中間件中的ctx.state[opts.tokenKey]屬性中得到.

這個(gè)模塊也支持令牌標(biāo)記為公鑰/私鑰對. 作為秘鑰的替代,你可以通過Buffer指定一個(gè)Public key

var publicKey = fs.readFileSync("/path/to/public.pub");
app.use(jwt({ secret: publicKey }));

當(dāng)sercret選項(xiàng)是一個(gè)函數(shù)時(shí),這個(gè)函數(shù)將會被每個(gè)koa-jwt接受到,用于決定哪個(gè)密鑰會被用于驗(yàn)證JWT

這個(gè)方法的簽名應(yīng)該是這樣的: (header) => [Promise(secret)], header表示令牌頭, 如果想作為支持JWKS的令牌頭的實(shí)例, 應(yīng)當(dāng)包含alg和kid:算法和密鑰ID字段

通過使用 node-jwks-rsa 組件,這個(gè)選項(xiàng)也可以用于支持JWKS(JSON Web Set),如下:

const { koaJwtSecret } = require("jwks-rsa");

app.use(jwt({ secret: koaJwtSecret({
                        jwksUri: "https://sandrino.auth0.com/.well-known/jwks.json",
                        cache: true,
                        cacheMaxEntries: 5,
                        cacheMaxAge: ms("10h") }),
              audience: "http://myapi/protected",
              issuer:   "http://issuer" }));

jsonwebtoken — JSON Web Token signing and verification

注意koa-v2版本的koa-jwt不再支持從jsonwebtoken中導(dǎo)出sign,verify和decode函數(shù)

原文地址: https://github.com/koajs/jwt