配置API的JWT认证

约束与限制

• 同一个环境中，一个API只能被一个JWT认证策略绑定，但一个JWT认证策略可以绑定多个API。
• 同一个APIG实例内最多可创建5个JWT认证策略。如需调整配额，请提交工单，申请修改。
• 用户需要通过工具或平台自行生成公私密钥对，在JWT认证策略中配置公钥，并使用对应的私钥生成Token。请妥善保管私钥避免泄露。
• 请求中携带的Token应当符合RFC 7519规范；JWT认证策略配置的公钥应当是符合RFC 7517规范的JSON格式字符串。
• 由于JWT并不会对数据进行加密，请勿将敏感数据设置在Token中。此外为了避免Token泄露，建议您不要对请求协议为HTTP的API使用JWT认证。
• Token校验支持的加密算法包含RS256、RS384 、RS512、ES256、ES384和ES512。使用RSA算法时，建议密钥长度大于等于3072位。
• JWKS_URI返回的公钥和固定设置的公钥大小，支持最大为50KB。
• 网关会校验Token中的nbf（生效时间）和exp（过期时间）字段，如果校验失败会拒绝请求。
• 当选择“定时拉取”的公钥设置方式时，必须保证JWKS_URI和APIG实例网络互通。网关内部的定时任务会每隔5min请求JWKS_URI，将返回的响应体作为公钥，并且当次请求的结果会覆盖上次请求的结果。如果要实现公私钥轮转，建议在每次轮换时，留出一段宽限时间，令JWKS_URI返回新公钥和本次轮转被替换的旧公钥，使得新旧私钥签发的Token在这段时间均有效。
• 网关会根据Token和JWKS公钥中的kid进行匹配验签。如果JWKS中只存在一个JWK则kid可以为空，否则不可以为空；JWKS中任意两个JWK的kid不可以相同。如果未设置kid，则公私钥替换后，之前签发的Token无法校验通过。
• 策略和API本身相互独立，只有为API绑定策略后，策略才对API生效。为API绑定策略时需指定发布环境，策略只对指定环境上的API生效。
• 策略的绑定、解绑、更新会实时生效，不需要重新发布API。
• API的下线操作不影响策略的绑定关系，再次发布后仍然会带有下线前绑定的策略。
• 如果策略与API有绑定关系，则策略无法执行删除操作。

创建JWT认证策略

1. 进入API网关控制台页面。
2. 根据实际业务在左侧导航栏上方选择实例。
3. 在左侧导航栏选择“API管理 > API策略”。
4. 在“策略管理”页面，单击“创建策略”。
5. 在“选择策略类型”弹窗中，选择“插件策略 > JWT认证”。
6. 在“创建策略”弹窗中，根据下表参数说明，配置策略信息。

   表1 JWT认证参数说明

   参数	说明
   策略名称	填写策略的名称，根据业务规划自定义。建议您按照一定的命名规则填写策略名称，方便您快速识别和查找。
   策略类型	固定为“JWT认证”。
   描述	填写策略的描述信息。长度为1-255个字符。
   策略内容	策略的配置内容，支持表单配置和脚本配置两种方式。
   设置方式	获取公钥的方式。 定时拉取：网关会每隔5min请求JWKS_URI获取公钥。 固定设置：网关会将所填入的JWKS值作为公钥。
   JWKS_URI	仅当选择“定时拉取”方式时需配置。 响应返回JWKS公钥的URI地址，公钥需为遵循RFC 7517规范的JSON字符串，需保证JWKS_URI和APIG实例网络互通。网关内部的定时任务会每隔5min请求JWKS_URI，将返回的响应体作为公钥，并且当次请求的结果会覆盖上次请求的结果。 网关请求URI地址的方法为GET，如果未指定请求协议，则使用HTTPS。返回的JWKS大小最大支持50KB。
   JWKS	仅当选择“固定设置”方式时需配置。 验证Token的JWKS公钥，需为遵循RFC 7517规范的json字符串。最大支持50KB。
   超时时间	仅当选择“定时拉取”方式时需配置。 网关请求JWKS服务的超时时间（1-60000ms），单位为毫秒。
   缓存时间	仅当选择“定时拉取”方式时需配置。 网关会将JWKS服务返回的JWKS进行缓存，允许您自定义缓存时间（600-86400s），单位为秒。
   自定义host头域	仅当选择“定时拉取”方式时需配置。 请求JWKS服务前，允许您自定义请求的host头域，默认将使用请求中原始的host头域。
   Token位置	Token参数的位置：header，query，cookie。
   Token名称	设置Token参数名称。 当Token位置为header时默认值为Authorization，该参数不区分大小写。 当Token位置为query时默认值为access_token。 当Token位置为cookie时该参数必填，该参数不区分大小写。
   Token前缀	仅当Token位置选择“header”时需配置。 Token字符串将去除该前缀，再用于鉴权。默认值为Bearer。
   Token过期时钟偏移量	若token在payload中设置了过期时间（exp），网关会对其进行校验，允许您自定义校验token是否过期的时钟偏移量（0-86400s）。
   Token透传至后端	是否允许将原始token透传至后端。默认值为false。
   Token不存在时跳过验证	当请求未携带Token时，是否允许跳过JWT认证直接访问后端。
   忽略超期时间校验	是否允许网关忽略对Token的超期时间exp字段值的校验。默认值为false。
   Payload传递至后端	是否允许将Token解析出的payload传递至后端。默认值为false。
   Payload所在请求头名称	仅当“Payload传递至后端”开启时需配置。 将Token解析出的Payload写入到指定名称的请求头。该参数不区分大小写。
   传递字段值至后端	网关将Payload中指定字段（claim）的值，设置到指定名称的请求头中，传递至后端。您可以通过设is_override来控制是否对同名的请求头进行重写。 当is_override为true时，如果存在同名的请求头会将其值覆盖。 当is_override为false时，会额外追加同名的请求头。 is_override默认为true，最多支持设置16个字段值传递至后端。
   黑名单配置	网关将根据黑名单配置，对payload中指定字段的值执行黑名单校验。如果payload中claim对应键值对匹配了黑名单配置中任意一条规则，即claim的值和某条规则中填入的字段值相等，则会拒绝请求。

脚本配置示例

{
    "jwks_service": {
        "uri": "https://example.com",
        "timeout": 5000,
        "ttl": 7200,
        "custom_host": "xxx.xxx"
    },
    "jwks": "{\"keys\":[{\"kty\": \"EC\",\"crv\": \"P-256\",\"x\": \"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4\",\"y\": \"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM\",\"use\": \"enc\",\"kid\": \"1\"}] }",
    "token_location": "header",
    "token_name": "Authorization",
    "token_prefix": "Bearer",
    "token_expiration_tolerance": 0,
    "token_pass_through_enabled": true,
    "missing_token_skip_auth_enabled": false,
    "ignore_expiration_validation_enabled": false,
    "claims_to_headers": [
        {
            "claim": "iat",
            "header": "iat_value",
            "is_override": true
        },
        {
            "claim": "sub",
            "header": "sub_value",
            "is_override": false
        }
    ],
    "blacklist": [
        {
            "claim": "iat",
            "value": ""
        },
        {
            "claim": "sub",
            "value": "test"
        }
    ]
}