具体的实践可以看我github上的例子。
用法
jwt.sign(payload, secretOrPrivateKey, [options, callback])
(异步)如果提供回调,则使用err或JWT 调用回调。
(同步)将JsonWebToken返回为字符串。
payload必须是一个object, buffer或者string。请注意, exp只有当payload是object字面量时才可以设置。
secretOrPrivateKey 是包含HMAC算法的密钥或RSA和ECDSA的PEM编码私钥的string或buffer。
options:
-
algorithm:加密算法(默认值:HS256)
-
expiresIn:以秒表示或描述时间跨度zeit / ms的字符串。如60,"2 days","10h","7d",Expiration time,过期时间
-
notBefore:以秒表示或描述时间跨度zeit / ms的字符串。如:60,"2days","10h","7d"
-
audience:Audience,观众
-
issuer:Issuer,发行者
-
jwtid:JWT ID
-
subject:Subject,主题
-
noTimestamp
-
header
如果payload不是buffer或string,它将被强制转换为使用的字符串JSON.stringify()。
在expiresIn,notBefore,audience,subject,issuer没有默认值时。也可以直接在payload中用exp,nbf,aud,sub和iss分别表示,但是你不能在这两个地方同时设置。
请记住exp,nbf,iat是NumericDate类型。
生成的jwts通常会包含一个iat值除非指定了noTimestamp。如果iat插入payload中,则将使用它来代替实际的时间戳来计算其他事情,诸如options.expiresIn给定一个exp这样的时间间隔。
// sign with default (HMAC SHA256)
var jwt = require('jsonwebtoken');
var token = jwt.sign({ foo: 'bar' }, 'shhhhh');
//backdate a jwt 30 seconds
var older_token = jwt.sign({ foo: 'bar', iat: Math.floor(Date.now() / 1000) - 30 }, 'shhhhh');
// sign with RSA SHA256
var cert = fs.readFileSync('private.key'); // get private key
var token = jwt.sign({ foo: 'bar' }, cert, { algorithm: 'RS256'});
// sign asynchronously
jwt.sign({ foo: 'bar' }, cert, { algorithm: 'RS256' }, function(err, token) {
console.log(token);
});
Token Expiration (exp claim)
签署1小时期限的token:
jwt.sign({
exp: Math.floor(Date.now() / 1000) + (60 * 60),
data: 'foobar'
}, 'secret');
使用此库生成令牌的另一种方法是:
jwt.sign({
data: 'foobar'
}, 'secret', { expiresIn: 60 * 60 });
//or even better:
jwt.sign({
data: 'foobar'
}, 'secret', { expiresIn: '1h' });
jwt.verify(token,secretOrPublicKey,[options,callback])
验证token的合法性
jwt.decode(token [,options])
(同步)返回解码没有验证签名是否有效的payload。
警告:这不会验证签名是否有效。你应该不为不可信的消息使用此。你最有可能要使用jwt.verify()。
错误与代码
TokenExpiredError
如果令牌过期,则抛出错误。
错误对象:
-
name:'TokenExpiredError'
-
message:'jwt expired'
-
expiredAt:[ExpDate]
JsonWebTokenError
错误对象:
-
name:'JsonWebTokenError'
-
message:
-
jwt异常
-
jwt签名是必需的
-
无效签名
-
jwt观众无效 预期:[OPTIONS AUDIENCE]
-
jwt发行人无效。预期:[OPTIONS ISSUER]
-
jwt id无效。预期:[OPTIONS JWT ID]
-
jwt主题无效。预期:[OPTIONS SUBJECT]
-
JWT应用场景?
简介中提到两个场景,我认为主要第一种--身份认证。为什么采用这种方式呢?我总结了下
1、json格式简单,相比xml,我更喜欢json;Self-contained,一般都翻译成自包含,意思是jwt中已经有了你需要的全部信息,拿出来用就行。
2、同session相比,性能更好一些,省去了处理分布session的问题;对于大行其道的restful来讲,支持得很好;浏览器+app+pc,这种多终端开发,是很好的选择。
JWT有什么好处?
1、支持跨域访问: Cookie是不允许垮域访问的,这一点对Token机制是不存在的,前提是传输的用户认证信息通过HTTP头传输.
2、无状态(也称:服务端可扩展行):Token机制在服务端不需要存储session信息,因为Token 自身包含了所有登录用户的信息,只需要在客户端的cookie或本地介质存储状态信息.
4、更适用CDN: 可以通过内容分发网络请求你服务端的所有资料(如:javascript,HTML,图片等),而你的服务端只要提供API即可.
5、去耦: 不需要绑定到一个特定的身份验证方案。Token可以在任何地方生成,只要在你的API被调用的时候,你可以进行Token生成调用即可.
6、更适用于移动应用: 当你的客户端是一个原生平台(iOS, Android,Windows 8等)时,Cookie是不被支持的(你需要通过Cookie容器进行处理),这时采用Token认证机制就会简单得多。
7、CSRF:因为不再依赖于Cookie,所以你就不需要考虑对CSRF(跨站请求伪造)的防范。
8、性能: 一次网络往返时间(通过数据库查询session信息)总比做一次HMACSHA256计算 的Token验证和解析要费时得多.
9、不需要为登录页面做特殊处理: 如果你使用Protractor 做功能测试的时候,不再需要为登录页面做特殊处理.
10、基于标准化:你的API可以采用标准化的 JSON Web Token (JWT). 这个标准已经存在多个后端库(.NET, Ruby, Java,Python, PHP)和多家公司的支持(如:Firebase,Google, Microsoft).
补充:Base64URL
这个算法跟 Base64 算法基本类似,但有一些小的不同。
JWT 作为一个令牌(token),有些场合可能会放到 URL(比如 api.example.com/?token=xxx)。Base64 有三个字符+、/和=,在 URL 里面有特殊含义,所以要被替换掉:=被省略、+替换成-,/替换成_ 。这就是 Base64URL 算法。