API认证方式-Accesstoken认证/JWT认证

变更记录

本文档适用于苍穹版本为V6.0以下，通过access_token或JWT调用OpenAPI。

1 简介      

      Token认证是指客户端登陆完成之后，服务端会生成一个有时效性的token返回给客户端，以后每次请求客户端都需要带上token。它可以当作URL参数或在请求头中发送，如“http://demo.com/users?accessToken=xxxxxx”，服务端以此来控制身份。当token过期后，服务端会销毁token，客户端需要重新请求获得token。

1.1  AccessToken认证流程

1、在金蝶云苍穹开放平台注册第三方应用，注册后就会生成一个appId（系统编码）和appSecret（系统密码）；

2、请求参数中输入appId和appSecret，通过客户端发送请求给服务器，获取临时appToken；

3、客户端通过请求发送用户名和上一步获取的appToken等信息给服务器，正确的话就返回access_token；

4、客户端拿到这个access_token，后续每次请求中，客户端会把token放在请求Header中发送给服务器，服务器验证签名是否有效，如果有效那么认证就成功，可以返回客户端需要的数据。

• appId和appSecret

appId是第三方应用的唯一标识，appSecret是第三方应用的密钥，它们相当于用户名和密码。注册第三方应用之后就会生成一个appId和appSecret。另外appSecret和密码一样也可以重置，在第三方应用的编辑页面可以重置密钥。

• app_token

即应用临时令牌。当用户在开放平台访问API前，需对应用进行授权，授权后第三方应用可访问用户的隐私数据。app_token为一次性令牌，有效期为2小时。

• access_token

即用户授权令牌，为用户一次会话的授权标识，有效期2小时。在获得app_token后，通过调用开放平台后台接口getAppToken来获取access_token。第三方应用在调用API服务时，需要带上access_token信息作为访问的凭证。

1）获取app_token

请求Body参数

请求示例

URL:http://{{localhost:}}/api/getAppToken.do
 
请求Header参数：
Content-Type=application/json
 
请求BODY参数：
{
    "appId": "test",
    "appSecret": "123456789Asd!@123456789",
    "tenantid": "tenant_devother_dev",
    "accountId": "666522411780278272"
}
 
请求结果：
{
    “data”: {
        "app_token": "d1106e34-8766-47cf-a75c-cd6b24a00c62",
        "success": true,
        "error_desc": "",
        "expire_time": 1621249899783,
        "error_code": "0"
    },
    "state": "success"
}

2）获取access_token 

请求Body参数

请求示例

URL：http://{{localhost:}}/api/login.do
 
请求Header参数：
Content-Type=application/json
 
请求Body参数：
{
    "user": "130****2580",
    "apptoken": "9c13aa2f-d99b-4884-8a52-d1a065a392cc",
    "tenantid": "",
    "accountId": "666522411780278272",
    "usertype": "Mobile",
    "language":"zh_CN"
}
请求结果：
{
    "data": {
        "access_token": "666522411780278272_ZOmaYoNRmT4XRl9k8RHlt1xuyxJ5fDhf0vFxNpN4EVb37eSAawuQN9RgfuO8hsSGuPHtEb849W5Y0RQxp6CR9Qcm9E4l15h6Cs2B",
        "success": true,
        "error_desc": "",
        "expire_time": 1621250199609,
        "error_code": "0"
    },
    "state": "success"
}

1.2  JWT认证流程

JWT(全称是JSON WEB TOKEN)是一种用于双方之间传递安全信息表述性声明规范，和access_token一样，都是访问资源的令牌。

金蝶云苍穹JWT认证流程:

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

2、客户端拿到这个JWT，后续每次请求中，客户端会把token放在请求Header中发送给服务器，服务器验证签名是否有效，如果有效那么认证就成功，可以返回客户端需要的数据。

1）获取JWT

请求Body参数

请求示例

URL:http://{{localhost:}}/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"
}

下面详细介绍如何通过JWT调用API服务。

2）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.eyJmaWQiOiIxMzQ2NjczOSIsInN1YiI6Imtkand0IiwiZnBob25lIjoiMTcyOTk5OTk5OTkiLCJlaWQiOiIxMTQ3NTYxNyIsImZ0cnVlbmFtZSI6IklFUlAiLCJmb3JnaWQiOiIxMDAwMDAiLCJpc3MiOiJrZCIsInVzZXJpZCI6IjEzNDY2NzM5IiwiZmxhc3Rsb2dpbmlwIjoiMTcyLjIwLjIwMC41NCIsImZpc2FjdGl2ZWQiOiIxIiwiZm9wZW5pZCI6IjVhMmRlZmNiZTRiMDk1N2ZhMDhmOGM3MiI