变更记录

1. 简介

1.1 背景介绍

为优化产品体验，进一步提升安全性，金蝶AI-R202403.001（金蝶AI苍穹V6.0）以上版本OpenAPI新增了增强型Token认证模式，支持通过接口获取、验证及失效请求令牌，V6.0版本后新增的第三方应用，AccessToken认证策略卡片默认开启了增强认证，若关闭后，则仍可使用历史方式，通过/api/login.do接口获取access_token。

1.2 注意事项

• 新增第三方应用时，默认打开增强型Token认证开关，若用户关闭开关，则仍可通过getAppToken.do和login.do接口获取access_token；
  

• 若第三方系统需要免登调用附件相关接口（如attachment/preview.do等），此时不建议使用增强型Token认证，改为使用<认证方式-Accesstoken认证/JWT认证>。
  

1.3 优化内容

• 更规范：接口参考最新Oauth2.0认证方式，参数命名更加规范；

• 更易用：只需一次请求，即可获取请求令牌access_token和JWT，简单易用；

• 更安全：1）请求参数增加随机数和时间戳，有效防止恶意重放攻击，提升整体安全性；

              2）增加限流和黑白名单检查功能，并支持密钥错误锁定；

                  3）认证参数支持加密脱敏，并在打印日志时隐藏敏感信息，防止信息泄露；

                  4）请求令牌access_token只允许在请求头中传递，不允许通过URL参数传递，避免造成资源权限外泄。

1.4 使用场景

在集成项目中，通过API接口进行集成时，需要首先调用getToken接口获取请求令牌，并缓存在调用端；在access_token过期（默认2小时有效）前，调用verifyToken验证access_token的有效性，并获取最新的过期时间。

在access_token即将过期时，支持通过refreshToken接口刷新access_token的有效期，从而在不换access_token的情况下继续访问OpenAPI资源。

1.5 接口列表

开放平台OpenAPI调用流程参考

2 特性详情

2.1 getToken

• 功能描述：令牌（access_token）是第三方应用调用OpenAPI的调用凭证，每次请求客户端都需要带上token，通过请求头中发送，服务端以此来控制身份，当token过期后，服务端会销毁token，客户端需要重新请求获得token。

• 请求 URL：http://{{localhost}}/kapi/oauth2/getToken

• 调用方式：HTTP调用

• 请求方式：POST

• 请求类型：Content-Type:application/json

• 调用频率：1分钟30次

• token有效期：2小时

注意事项：

• 令牌的获取是有限制的，每个令牌的有效期为 2 小时，请自行做好令牌的管理，在令牌快过期时（通过验证接口获取剩余过期时间比如1小时50分），可重新调用接口获取或调用刷新令牌接口延长有效期。

• 数据中心accountId，同时支持在Header和Body传输。

• 生成access_token需要首先注册第三方应用，可点击查看第三方应用介绍。

请求头参数

请求Body参数

请求参数示例

请求Header参数：
Content-Type=application/json

请求Body参数：
{
    "client_id": "thirdappunittest_003",
    "client_secret": "Abcdrty@1234567890#@2",
    "username":"zhangSan",
    "accountId": "1355633519610561531",
    "language": "zh_CN",
    "nonce": "123",
    "timestamp": "2023-09-08 11:47:00"
}

返回参数

返回参数示例

{
"data": {
    "access_token":"OPENAPIAUTH_MTMzMTIwNDQ0NTk5NTc5NDQzMl9FZ3h4MXU1Zzd2Qk9kRjR4MzIxQXZKcXU5c2hpbzNCaTRtTGIzbEsyM3JnbmFJUUJEMEltZUt3UURYQmFFdDJIVnc3MWtyaTVUR01ZbTRDUGVETDVSamE2R0F1a2g5SGpVcmwx",
    "token_type": "Bearer",
    "refresh_token": "d367106c-de46-4fc4-9e1a-59cbcfc430d2",
    "scope": "API",
    "expires_in": "7199977",
    "id_token": "OPENAPIAUTH_ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKSVV6STFOaUo5LmV5Sm1hV1FpT2lJeE16UTJOamN6T1NJc0luTjFZaUk2SW10a2FuZDBJaXdpWm5Cb2IyNWxJam9pTVRjeU9UazVPVGs1T1RraUxDSmxhV1FpT2lJeE1UUTNOVFl4TnlJc0ltWjBjblZsYm1GdFpTSTZJa2xGVWxBaUxDSm1iM0puYVdRaU9pSXhJaXdpWm1WdFlXbHNJam9pYVdWeWNFQnJhVzVuWkdWbExtTnZiU0lzSW1semN5STZJbXRrSWl3aWRYTmxjbWxrSWpvaU1UTTBOalkzTXpraUxDSm1ZbWw2Y0dGeWRHNWxjbWxrSWpvaU1DSXNJbVpzWVhOMGJHOW5hVzVwY0NJNklqRTNNaTR5TUM0eE5DNDJOeUlzSW1acGMyRmpkR2wyWldRaU9pSXhJaXdpWm05d1pXNXBaQ0k2SWpWaE1tUmxabU5pWlRSaU1EazFOMlpoTURobU9HTTNNaUlzSW1ac1lYTjBiRzluYVc1MGFXMWxJam9pTWpBeU15MHdPQzB5T1NBd01Eb3dNRG93TUM0d0lpd2labVZ1WVdKc1pTSTZJakVpTENKbWRXbGtJam9pTVRNME5qWTNNemtpTENKMWMyVnlWSGx3WlNJNklqRWlMQ0psZUhBaU9qRTJPVFEyTURReU1UZ3NJbWxoZENJNk1UWTVORFU1TnpBeE9Dd2labWx6Y21WbmFYTjBaV1FpT2lJeElpd2labkJ6ZDNOMGNtRjBaV2Q1YVdRaU9pSTNOakk1TnpjM09UVTNOekl3TURVek56WWlMQ0oxYzJWeWIzQmxibWxrSWpvaU5XRXlaR1ZtWTJKbE5HSXdPVFUzWm1Fd09HWTRZemN5SWl3aWRYTmxjbTVoYldVaU9pSkpSVkpRSW4wLi1ZZEd1cWhIX25Mcm5ibURnQTlfU2FvQkZsTGJWTTJEUmp2cnR4NXZwckk=",
    "id_token_expires_in": "7199977",
    "language": "zh_CN"
        },
    "errorCode": "0",
    "message": "",
    "status": true
}

错误码说明

2.2 verifyToken

• 功能描述：检测密钥令牌的有效性。

• 请求 URL：http://{{localhost}}/kapi/oauth2/verifyToken

• 调用方式：HTTP调用

• 请求方式：POST

• 请求类型：Content-Type:application/json

• 调用频率：1分钟30次

• token有效期：2小时

请求头参数

请求Body参数

请求参数示例

请求Header参数：
Content-Type=application/json

请求Body参数：
{
  "client_id": "thirdappunittest_003",
  "token_type_hint": "access_token",
    "token":"OPENAPIAUTH_MTMzMTIwNDQ0NTk5NTc5NDQzMl9peGdobmxERWluY1FpZDc2R2pjUDcyYlg0UTNwNDhpczZXM01NYTlsTDVhNEU2TFRkT0ZIWTlybUl5SDdvQUJ1ZGFSaGtWU0hGNlNRRTBjMjZ6MkxxQWRjbkNpTzBnd1ZzMW9P",
  "nonce": "1234",
  "timestamp": "2023-09-15 16:14:00",
  "accountId": "1331204445995794432"
}

返回参数

返回参数示例

{
    "data": {
    "expires_in": "7133040",
    "active": true,
    "scope": "API"
    },
    "errorCode": "0",
    "message": "",
    "status": true
}

错误码说明

2.3 withdrawToken

• 功能描述：撤回密钥令牌。

• 请求 URL：http://{{localhost}}/kapi/oauth2/withdrawToken

• 调用方式：HTTP调用

• 请求方式：POST

• 请求类型：Content-Type:application/json

• 调用频率：1分钟30次

• token有效期：2小时

请求头参数

请求Body参数

请求参数示例

请求Header参数：
Content-Type=application/json

请求Body参数：
{
    "client_id": "thirdappunittest_003",
    "client_secret": "Abcdrty@1234567890#@2",
    "token_type_hint": "access_token",
    "token":"OPENAPIAUTH_MTMzMTIwNDQ0NTk5NTc5NDQzMl9peGdobmxERWluY1FpZDc2R2pjUDcyYlg0UTNwNDhpczZXM01NYTlsTDVhNEU2TFRkT0ZIWTlybUl5SDdvQUJ1ZGFSaGtWU0hGNlNRRTBjMjZ6MkxxQWRjbkNpTzBnd1ZzMW9P",
    "nonce": "12345",
    "timestamp": "2023-09-15 16:29:00",
    "accountId": "1331204445995794432"
}

返回参数

返回参数示例

{
    "data": true,
    "errorCode": "0",
    "message": "true",
    "status": true
}

错误码说明

3 更多资讯

金蝶AIOpenAPI开发认证指南