Koa-jwt 说明文档(机翻润色)

栏目: Node.js · 发布时间: 7年前

内容简介:Koa-jwt 说明文档(机翻润色)

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的令牌头的实例, 应当包含 algkid :算法和密钥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


以上就是本文的全部内容,希望本文的内容对大家的学习或者工作能带来一定的帮助,也希望大家多多支持 码农网

查看所有标签

猜你喜欢:

本站部分资源来源于网络,本站转载出于传递更多信息之目的,版权归原作者或者来源机构所有,如转载稿涉及版权问题,请联系我们

KK三部曲

KK三部曲

(美)凯文·凯利(Kevin Kelly) / 张行舟 / 中信出版社 / 2015-12-12 / 80.00元

《失控 全人类的*终命运和结局》这是《黑客帝国》主要演员的必读物之一,这本关于机器、系统、生物和社会的“大部头”,揭示了社会进化、特别是互联网发展的“先知预言”,从这本书里,人们可以窥探到SNS的今天和未来。 《失控 全人类的*终命运和结局》涉猎:天文、化学、生物、计算机、控制论、运筹学、社会学…… 同时又堪比《黑客帝国》中洞悉未来的“神谕”,正在兴起的“云计算”、“物联网”等都可以在......一起来看看 《KK三部曲》 这本书的介绍吧!

HTML 压缩/解压工具
HTML 压缩/解压工具

在线压缩/解压 HTML 代码

JS 压缩/解压工具
JS 压缩/解压工具

在线压缩/解压 JS 代码

HEX CMYK 转换工具
HEX CMYK 转换工具

HEX CMYK 互转工具