什么是基于JWT的token认证,如何配置token认证

很多对外开放的API需要识别请求者的身份，并据此判断所请求的资源是否可以返回给请求者。token就是一种用于身份验证的机制，基于这种机制，应用不需要在服务端保留用户的认证信息或者会话信息，可实现无状态、分布式的Web应用授权，为应用的扩展提供了便利。

上图是API网关利用JWT鉴权插件实现认证的整个业务流程时序图，下面我们用文字来详细描述图中标注的步骤：

客户端向API网关发送请求，请求中携带token；

API网关使用用户插件中配置的公钥对请求中的token进行验证，验证通过后，将请求透传给后端服务；

后端服务进行处理后返回应答；

API网关将后端服务应答返回给客户端。

在整个过程中，API网关利用token认证机制，实现了用户使用自己的用户体系对API进行授权的能力。下面我们就要介绍API网关实现token认证所使用的结构化令牌Json Web Token(JWT)。

Json Web Token（JWT），是为了在网络应用环境间传递声明而执行的一种基于JSON的开放标准RFC7519。JWT一般可以用作独立的身份验证令牌，可以包含用户标识、用户角色和权限等信息，以便于从资源服务器获取资源，也可以增加一些额外的其他业务逻辑所必须的声明信息，特别适用于分布式站点的登录场景。

如上面的例子所示，JWT就是一个字符串，由三部分构成：

Header（头部）

Payload（数据）

Signature（签名）

JWT的头部承载两个信息：

声明类型，这里是JWT

声明加密的算法

完整的头部就像下面这样的JSON：

然后将头部进行Base64编码（该编码是可以对称解码的），构成了第一部分。

载荷就是存放有效信息的地方。定义细节如下：

也可以新增用户系统需要使用的自定义字段，比如下面的例子添加了name 用户昵称：

然后将其进行Base64编码，得到Jwt的第二部分：

这个部分需要Base64编码后的Header和Base64编码后的Payload使用 . 连接组成的字符串，然后通过Header中声明的加密方式进行加密（$secret 表示用户的私钥），然后就构成了jwt的第三部分。

将这三部分用 . 连接成一个完整的字符串，就构成了 1.3.2 节最开始的JWT示例。

API网关会认为用户颁发的token有权利访问整个分组下的所有绑定JWT插件的API。如果需要更细力度的权限管理，还需要后端服务自己解开token进行权限认证。API网关会验证token中的exp字段，一旦这个字段过期了，API网关会认为这个token无效而将请求直接打回。过期时间这个值必须设置，并且过期时间一定要小于7天。

JWT 默认是不加密，不能将秘密数据写入 JWT。

JWT 不仅可以用于认证，也可以用于交换信息。有效使用 JWT，可以降低服务器查询数据库的次数。JWT 的最大缺点是，由于服务器不保存 session 状态，因此无法在使用过程中废止某个 token，或者更改 token 的权限。也就是说，一旦 JWT 签发了，在到期之前就会始终有效，除非服务器部署额外的逻辑。

JWT 本身包含了认证信息，一旦泄露，任何人都可以获得该令牌的所有权限。为了减少盗用，JWT 的有效期应该设置得比较短。对于一些比较重要的权限，使用时应该再次对用户进行认证。

为了减少盗用，JWT 不应该使用 HTTP 协议明码传输，要使用HTTPS 协议传输。

用户可以在这个站点https://mkjwk.org 生成用于token生成与验证的私钥与公钥， 私钥用于授权服务签发JWT，公钥配置到JWT插件中用于API网关对请求验签，目前API网关支持的密钥对的加密算法为RSA SHA256，密钥对的加密的位数为2048。

本文应用Java示例说明，其他语言用户也可以找到相关的工具生成密钥对。 新建一个Maven项目，加入如下依赖：

使用如下的代码生成一对RSA密钥：

需要使用2.1节中在线生成的 Keypair JSON字符串（三个方框内的第一个）或者本地生成的 privateKeyString JSON字符串作为私钥来颁发token，用于授权可信的用户访问受保护的API，具体实现请参考本文第四节的示例。 向客户颁发token的形式由用户根据具体的业务场景决定，可以将颁发token的功能部署到生产环境，配置成普通API后由访问者通过用户名密码获得，也可以直接在本地环境生成token 后，直接拷贝给指定用户使用。

登录API网关控制台。

在左侧导航栏单击开放API——插件管理。

在插件管理页面，单击右上角的创建插件。

在创建插件页面，插件类型选择JWT鉴权，下面是一个JWT鉴权插件的配置及说明，具体配置说明可以参考文档JWT认证插件。

在插件列表页找到刚刚创建好的JWT鉴权插件，单击绑定API按钮，在弹出框中添加指定分组和环境下的API到弹出框右侧API列表中，单击确定，绑定完成。

目前，控制台的API调试功能并没有支持JWT插件，建议用户通过Postman或者直接在系统命令行中应用curl命令测试绑定JWT插件的API。

Status

Code

Message

Description

400

I400JR

JWT required

未找到JWT参数

403

S403JI

Claim jti is required when preventJtiReplay:true

当在JWT授权插件中配置了防重放功能时，请求未提供有效的jti

403

S403JU

Claim jti in JWT is used

当在JWT授权插件中配置了防重放功能时，请求提供的jti已被使用

403

A403JT

Invalid JWT: ${Reason}

请求中提供的JWT非法

400

I400JD

JWT Deserialize Failed: ${Token}

请求中提供的JWT解析失

403

A403JK

No matching JWK, kid:${kid} not found

请求JWT中的kid没有匹配的JWK

403

A403JE

JWT is expired at ${Date}

请求中提供的JWT已过期

400

I400JP

Invalid JWT plugin config: ${JWT}

JWT授权插件配置错误

当出现非预期应答码时，请检查HTTP应答中的X-Ca-Error-Code头中获取ErrorCode，从X-Ca-Error-Message头中获取ErrorMessage当出现A403JT或I400JD错误码时，可访问jwt.io网站来检查自己的Token合法性与格式。

上述示例中有以下几个地方需要重点关注：

keyId需要三个环节都一致，且全局唯一：

使用2.1节生成密钥时填写的keyId;

在本文3.2.1节设置的keyId；

代码中的keyId，JsonWebSignature 对象的KeyIdHeaderValue的取值，该属性为必填

privateKeyJson 使用2.1节中在线生成的 Keypair JSON字符串（三个方框内的第一个）或者本地生成的

privateKeyString JSON字符串；

过期时间一定要设置，并且小于7天；

添加自定义参数，所有值请都使用String类型。