电脑桌面
添加蚂蚁七词文库到电脑桌面
已经有10万+用户把蚂蚁七词文库添加到电脑桌面，以后点击桌面图标一键打开，无需搜索，非常快捷！
上传文档
开通会员限时优惠
充值
登录  |  注册
首页文章金蝶知识文章云苍穹知识金蝶云苍穹OpenAPI增强型Token认证

金蝶云苍穹OpenAPI增强型Token认证

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

金蝶云苍穹OpenAPI增强型Token认证

变更记录


产品版本

更新内容更新日期
V6.0.1新增增强型Token认证模式2023年10月



1. 简介

1.1 背景介绍

为优化产品体验，进一步提升安全性，并进行资源隔离，苍穹V6.0版本新增了增强型Token认证模式，支持通过接口获取、刷新、验证及失效请求令牌，管理请求令牌的的全生命周期。


1.2 注意事项

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

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


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 接口列表

序号接口名称接口地址说明
1获取access_token令牌/kapi/oauth2/getToken

获取请求令牌access_token，在第三方应用中启用JWT token后还会返回id_token，均可用于访问接口

2

检测令牌有效性/kapi/oauth2/verifyToken 检测access_token/refresh_token有效性及过期时间，检测JWT token(id_token)有效性

3

刷新令牌/kapi/oauth2/refreshToken刷新access_token的有效性
4撤回密钥令牌/kapi/oauth2/withdrawToken撤回access_token/refresh_token

开放平台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分），可重新调用接口获取或调用刷新令牌接口延长有效期。

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

  • 注册第三方应用是获取access_token的前提条件，可点击查看第三方应用介绍。


请求Body参数

请求参数必传类型说明
client_id是
String

第三方应用系统编码，即appId

client_secret

是String第三方应用AccessToken认证密钥，即appSecret

username

是String第三方应用代理用户的用户名
accountId是String数据中心id
language否String语言字串： zh_CN，zh_TW、en_US等。 默认系统默认语言，查询接口会返回对应的多语言文本字段
nonce是String随机数
timestamp是String时间戳，当前时间前后5分钟


请求参数示例

{
    "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
String请求令牌，第三方应用调用OpenAPI的凭证

- token_type
String令牌类型，默认为Bearer，即任何持有token的用户都可以访问对应的资源
- refresh_token
String刷新令牌，使用refresh_token 去刷新获得新的access_token，只能使用1次
- scope
String作用域，用户授权给第三方的权限，默认为API
- expires_in
Intaccess_token的有效期，即距离过期的剩余时长（单位：毫秒）
- id_token
StringJWT（Json Web Token）
- id_token_expires_inIntJWT的有效期，即距离过期的剩余时长（单位：毫秒）
- language
String浏览器接收语言
errorCode
String错误码，成功时为0
messageString错误消息
statusBoolean请求状态，true/false


返回参数示例

{
"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
}


错误码说明

错误码说明
0

请求成功

401不正确的第三方应用编码client_id或client_secret
603请求参数错误


2.2 verifyToken

  • 功能描述：检测请求令牌的有效性。

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

  • 调用方式：HTTP调用

  • 请求方式：POST

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

  • 调用频率：1分钟30次

  • token有效期：2小时


请求Body参数

请求参数必传类型说明
client_id是
String

第三方应用系统编码，即appId

token_type_hint

是String令牌类型，access_token/refresh_token/id_token

token

是String令牌值
accountId是String数据中心id
nonce是String随机数
timestamp是String

时间戳，当前时间前后5分钟


请求参数示例

{
  "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
Int令牌的有效期，即距离过期的剩余时长（单位：毫秒）
- active
Boolean是否有效，true/false
- scope
String作用域，用户授权给第三方的权限，默认为API
errorCode
String错误码，成功时为0
messageString错误消息
statusBoolean请求状态，true/false


返回参数示例

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


错误码说明

错误码说明
0

请求成功

603请求参数错误
612AccessToken verify failed/refresh_token/JWT(id_token) 验证失败：已过期/refresh_token 验证失败：已过期


2.3 refreshToken

  • 功能描述：用户通过getToken接口获取请求令牌后，可以通过该接口不断刷新access_token有效期。

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

  • 调用方式：HTTP调用

  • 请求方式：POST

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

  • 调用频率：1分钟30次

  • token有效期：2小时


请求Body参数

请求参数必传类型说明
client_id是
String

第三方应用系统编码，即appId

grant_type

是String授权类型，默认为刷新令牌refresh_token

refresh_token

是String刷新令牌，注意，该令牌只能使用1次
accountId是String数据中心id
nonce是String随机数
timestamp是String时间戳，当前时间前后5分钟


请求参数示例

{
    "client_id": "thirdappunittest_003",
    "grant_type": "refresh_token",
    "refresh_token": "df591867-fb0d-4375-9e77-98ea276f59c0",
    "accountId": "1355633519610561536",
    "nonce": "123",
    "timestamp": "2023-09-08 11:47:00"
}


返回参数

返回参数类型说明
data


- access_token
String请求令牌，第三方应用调用OpenAPI的凭证

- token_type
String令牌类型，默认为Bearer，即任何持有token的用户都可以访问对应的资源
- refresh_token
String刷新令牌，使用refresh_token 去刷新获得新的access_token，只能使用1次
- scope
String作用域，用户授权给第三方的权限，默认为API
- expires_in
String令牌的有效期，即距离过期的剩余时长（单位：毫秒）
- id_token
StringJWT（Json Web Token）
- id_token_expires_inStringJWT的有效期，即距离过期的剩余时长（单位：毫秒）
- language
String浏览器接收语言，刷新令牌时语言环境不变，返回空
errorCode
String错误码，成功时为0
messageString错误消息
statusBoolean请求状态，true/false


返回参数示例

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


错误码说明

错误码说明
0

请求成功

400授权信息错误
603请求参数错误



2.4 withdrawToken

  • 功能描述：撤回请求令牌（暂不支持JWT）。

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

  • 调用方式：HTTP调用

  • 请求方式：POST

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

  • 调用频率：1分钟30次

  • token有效期：2小时


请求Body参数

请求参数必传类型说明
client_id是
String

第三方应用系统编码，即appId

client_secret

是String第三方应用AccessToken认证密钥，即appSecret

token_type_hint

是String令牌类型，access_token/refresh_token

token

是String令牌值
accountId是String数据中心id
nonce是String随机数
timestamp是String

时间戳，当前时间前后5分钟


请求参数示例

{
    "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


errorCode
String错误码，成功时为0
messageString错误消息
statusBoolean请求状态，true/false


返回参数示例

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


错误码说明

错误码说明
0

请求成功

401不正确的第三方应用编码client_id或client_secret
603请求参数错误
611撤回失败


3 更多资讯

关于OpenAPI的更多资讯，请随时关注新特性公告。

认证相关信息，请查看金蝶云苍穹OpenAPI开发认证指南


金蝶云苍穹OpenAPI增强型Token认证

变更记录产品版本更新内容更新日期V6.0.1新增增强型Token认证模式2023年10月1. 简介1.1 背景介绍为优化产品体验，进一步提升安全性，并进...
点击下载文档
标签： # 新特性# 金蝶云·苍穹# 精华汇总# OpenApi# 基础入门
分享：
上一篇：OpenAPI防止接口重复调用下一篇：OpenAPI新特性汇总
本文2024-09-23 00:26:28发表“云苍穹知识”栏目。
本文链接：https://wenku.my7c.com/article/kingdee-cangqiong-139478.html

相关文章

最新文档
热门文章

阅读排行

热门标签
# 常见问题# 企业版/标准版# 财务会计# EAS Cloud# K3 WISE# 功能介绍# 基础入门# 快速入门# s-HR# 金蝶云星瀚# 供应链# 金蝶云·星辰# 推送至苍穹帮助中心# 金蝶云·星空# 金蝶云·苍穹# 高级技巧# 新特性# 总账# 金蝶云·星空实施# 旗舰版
一键复制下载文档联系客服
确认删除?
取消确定
回到顶部
客服QQ
  • 客服QQ点击这里给我发消息