Koa-jwt 申明文档(机翻润饰)

2024年1月17日 253次阅读 来源: 熊猫眼

KOA-JWT (机翻润饰)

node>=7.6.0

npm v3.2.2

这个模块能够让你在你的KOA运用中经由过程运用JSON WEB TOKEN(以下简称JWT)认证HTTP要求

这个文档做了一个很好的引见.

  • 假如你运用KOA版本2.+,同时你有一个低于7.6版本的node. 装置koa-jwt@2

  • 主分支(Koajwt git堆栈上的.译者注)上的koa-jwt版本3+运用async/await,所以必需是node 7.6以上

  • 假如你运用koa1,你需要从npm装置koa-jwt@1.这个代码在koa-v1分支上

装置

$ npm install koa-jwt

用例

JWT认证中间件的认证经由过程运用JWT令牌(token,译者注).假如令牌有用,ctx.state.user(默许情况下)会被设置成解码的JSON对象,以便于在稍后的中间件中举行认证或接见掌握.

检索令牌

令牌一般被包产在一个名为Authorization的HTTP头中,但也能经由过程cookie来举行,然则也能够运用Cookie来供应令牌,只要在opts.cookie选项上设置为包括令牌的cookie的称号.也能够经由过程opts.getToken选项完成自定义的令牌检索.返回的函数应该婚配以下接口:

/**
 * 自定义令牌剖析器
 * @this 传入中间件的CTX对象
 *
 * @param  {object} opts     中间件选项
 * @return {String|null}    返回被剖析的令牌,假如没有找到则返回null
 */

令牌剖析递次以下所示.第一个被剖析的非空令牌将被用于考证

  • 运转opts.getToken 函数

  • 搜检cookies(假如cookies被设置了)

  • 搜检承载令牌的认证头(header)

通报密钥

一般你在opts.secret中供应了一个零丁的开放密钥,然则另一个替代计划是在一个更靠前的中间件中设置ctx.state.secret,一般是每一个要求中.假如这个属性存在,它将用来替代opts.secret中的密钥.

搜检烧毁密钥

你能够供应一个异步的函数来让koa-jwt搜检令牌是不是被打消.这个函数应该被设置再opts.isRevoked属性中.你供应的函数应该婚配以下接口:

/**
 * 你自定义的检索打消剖析器
 *
 * @param  {object}      ctx     通报给中间件的CTX对象
 * @param  {object}      token     令牌
 * @param  {object}      user     令牌的内容
 * @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\n';
    } else {
      throw err;
    }
  });
});

// Unprotected middleware
app.use(function(ctx, next){
  if (ctx.url.match(/^\/public/)) {
    ctx.body = 'unprotected\n';
  } 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\n';
  }
});

app.listen(3000);

你也能够在某些条件下有条件的运转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\n';
  } else {
    return next();
  }
});

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

app.listen(3000);

更多关于unless的例子,请点击koa-unless

纵然没有找到认证头,你也能够经由过程增加一个passthrough选项来保证一直通报到下一个(中间件)

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

经由过程这个选项,使得下流中间件能够基于ctx.state.user是不是设置做出决议

假如你更喜好运用别的一个ctx key来示意解码数据,只需要传入key属性,以下:

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

此时解码数据能够经由过程ctx.state.jwtdata获得(替代掉默许的ctx.state.user)

你一样能够指定audience和/或issuer

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

假如koa-jwt有设置一个expiration(exp),它将会被搜检到.

假如存在tokenkey 选项,而且找到有用的令牌,原始令牌数据能够从随后的中间件中的ctx.state[opts.tokenKey]属性中获得.

这个模块也支撑令牌标记为公钥/私钥对. 作为秘钥的替代,你能够经由过程Buffer指定一个Public key

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

当sercret选项是一个函数时,这个函数将会被每一个koa-jwt接受到,用于决议哪一个密钥会被用于考证JWT

这个要领的署名应该是如许的: (header) => [Promise(secret)], header示意令牌头, 假如想作为支撑JWKS的令牌头的实例, 应该包括alg和kid:算法和密钥ID字段

经由过程运用 node-jwks-rsa 组件,这个选项也能够用于支撑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中导出sign,verify和decode函数

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

    原文作者：熊猫眼
    原文地址: https://segmentfault.com/a/1190000009788117
    本文转自网络文章，转载此文章仅为分享知识，如有侵权，请联系博主进行删除。
点赞