苍穹OpenAPI入门篇之JWT认证

栏目：云苍穹知识作者：金蝶来源：金蝶云社区发布：2024-09-23浏览：1

苍穹OpenAPI入门篇之JWT认证

在前面的OpenAPI认证方式系列文章中，我们已经介绍了金蝶云苍穹三种认证方式中的AccessToken认证和摘要认证，本期小编为大家介绍最后一种登录认证方式：JWT认证。

1 应用场景

第三方系统调用金蝶云苍穹API服务时，需先通过身份认证。

2 解决方案

金蝶云苍穹支持通过JWT认证进行身份认证。

2.1 JWT简介

JWT(全称为JSON WEB TOKEN)是一种用于双方之间传递安全信息的表述性声明规范。和AccessToken一样，JWT也是访问资源的令牌，但服务端验证客户端发来的Token信息时，需要进行数据的查询操作；而JWT验证客户端发来的Token信息时，不需要查询数据库，只需在服务端进行密钥校验。

2.2 JWT结构

JWT结构分为三部分：头部（Header）、载荷（Payload）和签名(Signature)。

在Header中声明加密算法和常量，使用Json把Header转化为字符串；
在Payload中声明用户信息以及一些公共和私有的声明，再次使用Json把载荷部分转化为字符串；
使用Header中声明的加密算法和随机生成的secret进行加密，把第一部分和第二部分的字符串使用Header中指定签名算法进行加密。

注：解密的时候只要客户端发起请求时携带JWT，服务端就直接使用secret进行解密。

2.3 JWT价值

金蝶云苍穹JWT认证通过使用非对称加密算法生成摘要，保障客户端与服务端通信的内容不被第三方篡改，提高破解和报文重放攻击的难度，是一种安全性更高的认证方式。

3 功能实现

金蝶云苍穹的JWT认证的整体流程为：

1. 通过请求指定参数（如appId、appSecret、keytype）一次性获取JWT；

2. 客户端拿到该JWT后，在后续的每次请求中，客户端都会把Token放在请求Header中发送给服务器。然后，服务器验证签名是否有效，如果有效则认证成功，可以返回客户端需要的数据。

接下来，小编为大家详细介绍每个流程的操作步骤。

步骤一：获取JWT

请求示例如下：

//URL:
http://localhost:8080/ierp/api/login.do
//请求Header参数：
Content-Type=application/json
//请求BODY参数：
{
    "user": "130****2580",
    "appId": "test",
    "appSecret": "123456789123456789",
    "tenantid": "baseline_a",
    "accountId": "1173910536060928000",
    "usertype": "Mobile",
    "keytype":"JWT"
}
//请求结果：
{
    "data": {
        "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmaWQiOiIxMzQ2NjczOSIsInN1YiI6Imtkand0IiwiZnBob25lIjoiMTcyOTk5OTk5OTkiLCJlaWQiOiIxMTQ3NTYxNyIsImZ0cnVlbmFtZSI6IklFUlAiLCJmb3JnaWQiOiIxMDAwMDAiLCJpc3MiOiJrZCIsInVzZXJpZCI6IjEzNDY2NzM5IiwiZmxhc3Rsb2dpbmlwIjoiMTcyLjIwLjIwMC41NCIsImZpc2FjdGl2ZWQiOiIxIiwiZm9wZW5pZCI6IjVhMmRlZmNiZTRiMDk1N2ZhMDhmOGM3MiIsImZsYXN0bG9naW50aW1lIjoiMjAyMS0wOC0yMCAwMDowMDowMCIsImZlbmFibGUiOiIxIiwiZnVpZCI6IjEzNDY2NzM5IiwidXNlclR5cGUiOiIxIiwiZXhwIjoxNjI5NDQ3MDM1LCJpYXQiOjE2Mjk0Mzk4MzUsImZpc3JlZ2lzdGVkIjoiMSIsInVzZXJvcGVuaWQiOiI1YTJkZWZjYmU0YjA5NTdmYTA4ZjhjNzIiLCJ1c2VybmFtZSI6IklFUlAifQ.kf_UfkQuAPb_qHZAc2ovB7nzpnWIKpl_7eXw42UjNYM",
        "success": true,
        "error_desc": "",
        "expire_time": 1629447035019,
        "error_code": "0"
    },
    "state": "success"
}

HTTP 请求参数说明如下：

HTTP 请求参数说明

步骤二：通过JWT调用API服务

1）GET API 实例

请求示例：

//URL：
https://feature.kingdee.com:2024/baseline_a/kapi/sys/isc_demo_basedata_1/query?select=name,number&filter=name eq 123asd&jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmaWQiOiIxMzQ2NjczOSIsInN1YiI6Imtkand0IiwiZnBob25lIjoiMTcyOTk5OTk5OTkiLCJlaWQiOiIxMTQ3NTYxNyIsImZ0cnVlbmFtZSI6IklFUlAiLCJmb3JnaWQiOiIxMDAwMDAiLCJpc3MiOiJrZCIsInVzZXJpZCI6IjEzNDY2NzM5IiwiZmxhc3Rsb2dpbmlwIjoiMTcyLjIwLjIwMC41NCIsImZpc2FjdGl2ZWQiOiIxIiwiZm9wZW5pZCI6IjVhMmRlZmNiZTRiMDk1N2ZhMDhmOGM3MiIsImZsYXN0bG9naW50aW1lIjoiMjAyMS0wOC0yMCAwMDowMDowMCIsImZlbmFibGUiOiIxIiwiZnVpZCI6IjEzNDY2NzM5IiwidXNlclR5cGUiOiIxIiwiZXhwIjoxNjI5NDQ3MDM1LCJpYXQiOjE2Mjk0Mzk4MzUsImZpc3JlZ2lzdGVkIjoiMSIsInVzZXJvcGVuaWQiOiI1YTJkZWZjYmU0YjA5NTdmYTA4ZjhjNzIiLCJ1c2VybmFtZSI6IklFUlAifQ.kf_UfkQuAPb_qHZAc2ovB7nzpnWIKpl_7eXw42UjNYM&appId=TEST&accountId=1173910536060928000
//请求结果：
{
    "success": "true",
    "data": {
        "count": 1,
        "header": [
            {
                "name": "name",
                "caption": "名称",
                "type": "String"
            },
            {
                "name": "number",
                "caption": "编码",
                "type": "String"
            }
        ],
        "rows": [
            [
                "123asd",
                "123asd"
            ]
        ]
    }
}

HTTP query 查询参数说明如下：

HTTP query 查询参数说明

2）POST API 实例

请求示例：

//URL：
http://localhost:8080/ierp/kapi/sys/pm_purorderbill/save
//请求Header参数：
jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmaWQiOiIxMzQ2NjczOSIsInN1YiI6Imtkand0IiwiZnBob25lIjoiMTcyOTk5OTk5OTkiLCJlaWQiOiIxMTQ3NTYxNyIsImZ0cnVlbmFtZSI6IklFUlAiLCJmb3JnaWQiOiIxMDAwMDAiLCJpc3MiOiJrZCIsInVzZXJpZCI6IjEzNDY2NzM5IiwiZmxhc3Rsb2dpbmlwIjoiMTcyLjIwLjIwMC41NCIsImZpc2FjdGl2ZWQiOiIxIiwiZm9wZW5pZCI6IjVhMmRlZmNiZTRiMDk1N2ZhMDhmOGM3MiIsImZsYXN0bG9naW50aW1lIjoiMjAyMS0wOC0yMCAwMDowMDowMCIsImZlbmFibGUiOiIxIiwiZnVpZCI6IjEzNDY2NzM5IiwidXNlclR5cGUiOiIxIiwiZXhwIjoxNjI5NDQ3MDM1LCJpYXQiOjE2Mjk0Mzk4MzUsImZpc3JlZ2lzdGVkIjoiMSIsInVzZXJvcGVuaWQiOiI1YTJkZWZjYmU0YjA5NTdmYTA4ZjhjNzIiLCJ1c2VybmFtZSI6IklFUlAifQ.kf_UfkQuAPb_qHZAc2ovB7nzpnWIKpl_7eXw42UjNYM
appId=TEST
accountId=1173910536060928000    //有默认数据中心可以不传
//请求BODY参数：
{
    "data": {
        "number": "cugk",
        "name": "cugk",
        "alias_name": "cugk"
    }
}
//请求结果：
{
    "data": {
        "success": true,
        "needSign": false,
        "needWfAssignPersons": false,
        "cancelWriteLog": true,
        "showMessage": true,
        "billCount": 1,
        "successPkIds": [
            1226640481962735668
        ],
        "billNos": {
            "1226640481962735668": "cugk"
        },
        "validateResult": {
            "validateErrors": [],
            "success": true,
            "message": "",
            "errorPkIds": [],
            "errorDataIndexs": []
        },
        "runSecond": 0,
        "allErrorOrValidateInfo": [],
        "allErrorInfo": []
    },
    "success": true,
    "errorCode": "success",
    "message": null
}

HTTP query请求头参数说明如下：