<p class="shortdesc">jwt具体说明请参考：<a class="xref" href="https://jwt.io/" target="_blank" rel="external noopener">https://jwt.io/</a></p> <section class="section" id="jwt__section_py4_rzw_2sb"><h2 class="doc-tairway">获取token方式</h2> <div class="p"> <ol class="ol" id="jwt__ol_e3m_szw_2sb"> <li class="li">通过uri_param_names获取。</li> <li class="li">第一步获取不到后，会通过cookie_names获取。</li> <li class="li">第二步获取不到后，会通过header中的header_names获取（header示例：Authorization: Bearer “token”）。</li> </ol> </div> </section> <section class="section" id="jwt__section_p1y_szw_2sb"><h2 class="doc-tairway">配置说明</h2> <ol class="ol" id="jwt__ol_z5f_wzw_2sb"> <li class="li"><strong class="ph b">配置参数说明</strong><table class="table" id="jwt__table_wrl_xzw_2sb"><caption></caption><colgroup><col><col><col><col><col></colgroup><thead class="thead"> <tr class="row"> <th class="entry align-left" id="jwt__table_wrl_xzw_2sb__entry__1">参数名</th> <th class="entry align-left" id="jwt__table_wrl_xzw_2sb__entry__2">参数类型</th> <th class="entry align-left" id="jwt__table_wrl_xzw_2sb__entry__3">是否必须</th> <th class="entry align-left" id="jwt__table_wrl_xzw_2sb__entry__4">默认值</th> <th class="entry align-left" id="jwt__table_wrl_xzw_2sb__entry__5">参数说明</th> </tr> </thead><tbody class="tbody"> <tr class="row"> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__1 ">uri_param_names</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__2 ">array</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__3 ">N</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__4 ">{“jwt”}</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__5 ">不能为空，从请求参数中获取token</td> </tr> <tr class="row"> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__1 ">cookie_names</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__2 ">array</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__3 ">N</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__4 "></td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__5 ">通过该cookie名获取token</td> </tr> <tr class="row"> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__1 ">header_names</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__2 ">array</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__3 ">N</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__4 ">{“authorization”}</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__5 ">从header中此header_name中获取token如果此项为空则默认读取authorization，如果不为空，则按顺序读取。（kong-1.2.6版本支持）</td> </tr> <tr class="row"> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__1 ">key_claim_name</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__2 ">string</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__3 ">N</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__4 ">iss</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__5 ">签发人参数名称。（即对应密钥设置中的Key）</td> </tr> <tr class="row"> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__1 ">secret_is_base64</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__2 ">boolean</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__3 ">N</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__4 ">false</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__5 ">是否base64加密，即用于加密的secret或rsa public key是否是经过base64加密的</td> </tr> <tr class="row"> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__1 ">claims_to_verify</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__2 ">array</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__3 ">N</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__4 "></td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__5 ">1、值选项{“exp”, “nbf”}，此处声明的规则，需要在token中拥有相应的值。2、如果设置了maximum_expiration>0，则claims_to_verify值必须包括“exp”exp: token过期时间。nbf：token生效时间。</td> </tr> <tr class="row"> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__1 ">anonymous</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__2 ">string</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__3 ">N</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__4 "></td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__5 ">(只能为空或者满足正则表达式：[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})</td> </tr> <tr class="row"> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__1 ">run_on_preflight</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__2 ">boolean</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__3 ">N</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__4 ">true</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__5 ">如果请求方法是OPTIONS，并且run_on_preflight=true则不执行验证</td> </tr> <tr class="row"> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__1 ">maximum_expiration</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__2 ">number</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__3 ">N</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__4 ">0</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__5 ">即将过期的最大时间间隔（expire_time-now()的最大时间间隔），必须>=0</td> </tr> <tr class="row"> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__1 ">anonymous_urls</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__2 ">array</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__3 ">N</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__4 "></td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__5 ">不需要验证的链接列表</td> </tr> <tr class="row"> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__1 ">refresh_token_enabled</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__2 ">boolean</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__3 ">N</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__4 ">false</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__5 ">是否刷新token</td> </tr> <tr class="row"> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__1 ">refresh_token_buffer_time</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__2 ">number</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__3 ">N</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__4 ">30</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__5 ">1、离过期多久(缓冲时间)就可以开始交换token的时间，值必须>=0，单位为秒2、refresh_token_enabled=true后则不能为空</td> </tr> <tr class="row"> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__1 ">refresh_token_url</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__2 ">url</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__3 ">N</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__4 "></td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__5 ">token刷新的链接，refresh_token_enabled=true后则不能为空</td> </tr> <tr class="row"> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__1 ">write_back_cookie_name</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__2 ">string</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__3 ">N</td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__4 "></td> <td class="entry align-left" headers="jwt__table_wrl_xzw_2sb__entry__5 ">将token写入到cookie内。这个属性定义cookie的名字。（kong-1.2.7-beta或以上版本支持）</td> </tr> </tbody></table></li> <li class="li"><strong class="ph b">配置示例</strong><ol class="ol" type="a" id="jwt__ol_hgw_yzw_2sb"> <li class="li"><strong class="ph b">refresh_token_url接口说明</strong><p class="p">jwt插件会通过如下形式调用refresh_token_url，新token需要写入到请求的返回体内。</p><pre class="pre codeblock" id="jwt__codeblock_szd_11x_2sb"><code> local resp, err = client:request_uri(conf.refresh_token_url, { method = "PUT", headers = { ["Content-Type"] = "application/json", ["Authorization"] = "Bearer "..token, }, })</code></pre></li> <li class="li"><strong class="ph b">示例</strong><pre class="pre codeblock" id="jwt__codeblock_m51_c1x_2sb"><code>{ "uri_param_names": ["jwt"], "header_names": ["authorization"], "cookie_names": [], "key_claim_name": "iss", "secret_is_base64": false, "claims_to_verify": ["exp"], "anonymous": "", "run_on_preflight": true, "maximum_expiration": 0, "anonymous_urls": [], "refresh_token_enabled": false, "refresh_token_buffer_time": 30, "refresh_token_url": "" }</code></pre></li> </ol><img class="image" id="jwt__image_rkf_m1x_2sb" src="https://obs-cn-shanghai.fincloud.pinganyun.com/pacloud/20220910180811-1ea726919eab.png" width="800"></li> <li class="li"><strong class="ph b">JWT 密钥配置说明</strong><div class="p"> <ol class="ol" type="a" id="jwt__ol_hjt_p1x_2sb"> <li class="li">需要先在Consumer配置模块添加Consumer账号。（参数内容没有限制，可以是系统名）</li> <li class="li">在Jwt密钥管理部分添加JWT密钥。<table class="table" id="jwt__table_gf4_q1x_2sb"><caption></caption><colgroup><col><col><col><col><col></colgroup><tbody class="tbody"> <tr class="row"> <td class="entry">参数名</td> <td class="entry">参数类型</td> <td class="entry">是否必须</td> <td class="entry">默认值</td> <td class="entry">参数说明</td> </tr> <tr class="row"> <td class="entry">consumer name</td> <td class="entry">string</td> <td class="entry">是</td> <td class="entry"></td> <td class="entry">JWT插件需要关联认证用户，此处即认证用户的用户名，只是一个标识如果有多个密钥，name必须唯一值格式无特殊要求。例如jwt-user1</td> </tr> <tr class="row"> <td class="entry">consumer id</td> <td class="entry">string</td> <td class="entry">是</td> <td class="entry"></td> <td class="entry">关联认证用户的ID，只是一个标识如果有多个密钥，name必须唯一值格式无特殊要求。例如：jwt-id1</td> </tr> <tr class="row"> <td class="entry">算法</td> <td class="entry">string</td> <td class="entry">是</td> <td class="entry">HS256</td> <td class="entry">即加密JWT信息的算法，HS开头即HMAC算法。RS开头即RSA算法。</td> </tr> <tr class="row"> <td class="entry">key</td> <td class="entry">string</td> <td class="entry">是</td> <td class="entry"></td> <td class="entry">即该密钥的标识，值格式无特殊要求（可以使用UUID）。此值确定后需要后端在生成token时写入到JWT配置中的key_claim_name声明的字段名中。</td> </tr> <tr class="row"> <td class="entry">secret</td> <td class="entry">string</td> <td class="entry">是</td> <td class="entry"></td> <td class="entry">即HMAC算法加密时使用的secret（HS算法时必填）</td> </tr> <tr class="row"> <td class="entry">rsa public key</td> <td class="entry">string</td> <td class="entry">是</td> <td class="entry"></td> <td class="entry">即RSA算法加密时使用的public key（RS算法时必填）</td> </tr> </tbody></table><strong class="ph b">HS算法</strong><p class="p">即HMAC算法，需要通过secret来加密数据。</p><img class="image" id="jwt__image_qj4_ghx_2sb" src="https://obs-cn-shanghai.fincloud.pinganyun.com/pacloud/20220910180811-106078689936.png" width="800"><p class="p"><strong class="ph b">RS算法</strong></p><p class="p">即RSA算法，需要通过public key加密数据。</p><img class="image" id="jwt__image_hnv_shx_2sb" src="https://obs-cn-shanghai.fincloud.pinganyun.com/pacloud/20220910180811-1222a99e98e4.png" width="800"></li> </ol> </div></li> </ol> </section>