JSAPI鉴权

更新于 2024-11-18钉钉提供的JSAPI有很多是手机的基础能力，对这些JSAPI的调用不需要进行鉴权（不需要进行dd.config），只需要在dd.ready里调用。对于一些钉钉业务、安全相关的JSAPI的调用，需要先鉴权，然后再调用。

了解JSAPI是否需要鉴权，请查看H5微应用JSAPI总览。

接入必读

鉴权是针对微应用页面实现的。如果当前页面用到需要鉴权的JSAPI，此页面就需要执行鉴权流程。钉钉开放平台会获取当前页面中需要鉴权的JSAPI，然后执行鉴权。
要求开发者的签名signature值必须与开放平台的保持一致。
重要
计算签名时用到的URL，必须是使用了需要鉴权的JSAPI的页面。
针对VUE单页面应用，鉴权需要对父页面实现，因为计算签名方法不支持路由页面地址。
实现流程如下，当使用了需要鉴权的子页面加载时，需要刷新父页面，使父页面完成鉴权流程，然后该子页面上就可以调用需要鉴权的JSAPI。

重要

必须使用当前微应用的参数获取access_token，

通过获取jsapi_ticket接口获取jsapi_ticket时，请注意：

企业内部应用和第三方企业应用获取 jsapiTicket 后，如果 jsapiTicket 尚未过期，再次调用获取jsapiTicket接口时，返回的 jsapiTicket 值与之前的相同，只是续期了 2 小时。需要注意的是，从 jsapiTicket 生成起，最大过期时间为 24 小时，即使续期后，最大过期时间仍从 jsapiTicket 生成起计算。
例如：当你早上 9 点，生成一个 jsapiTicket 时，即使一直续期，第二天早上9点，jsapiTicket 也会过期，需要重新生成一个新的 jsapiTicket。
企业内部应用获取jsapi_ticket，一个appKey对应一个jsapi_ticket，所以在使用的时候需要将jsapi_ticket以appKey为维度进行缓存下来（设置缓存过期时间2小时），并不需要每次都通过接口拉取。

在前端进行鉴权之前，需要获取以下签名所需的参数：

参数	说明	开发企业内部应用	ISV开发第三方企业应用
url	当前网页的URL，不包含#及其后面部分。说明如果是单页面应用，请参考本文的最上方接入必读。必须是当前页面的 location.href 的原内容，请勿提前进行encode/urlencode处理，否则会引起编码不一致最终导致签名校验失败。	—	—
nonceStr	自定义固定字符串。	—	—
agentId	应用的标识	可以在开发者后台的应用详情页中获取。	可以从授权信息中获取到。
timeStamp	时间戳	当前时间，但是前端和服务端进行校验时候的值要一致。	当前时间，但是前端和服务端进行校验时候的值要一致。
corpId	企业ID	企业的corpid，可以在开发者后台首页获取。	通过在页面地址上追加?`corpId=$CORPID$`进行获取。

在服务端通过sign(ticket, nonceStr, timeStamp, url)计算前端校验需要使用的签名信息。

示例代码：

示例代码：

重要

参数说明：

参数	类型	是否必填	说明
agentId	String	是	微应用ID。
corpId	String	是	企业的corpid。
timeStamp	String	是	生成签名的时间戳。
nonceStr	String	是	自定义固定字符串。
signature	String	是	JSAPI签名，可以参考简易教程中的获取签名的示例代码。
type	number	否	如果是要调用服务窗的jsapi，请填1。
jsApiList	Array	是	需要调用的jsapi列表。

完成鉴权后，便可以在dd.ready里调用JSAPI了。

代码示例：

dd.config错误说明，提示“jsapi ticket读取失败”
"jsapi ticket读取失败"，这个错误是因为钉钉服务器没有成功读取到该企业的jsticket数据，原因可能为：
1. corpid不一致：
  调用获取jsapi_ticket接口，使用的access_token对应的corpid和dd.config中传递的corpid不一致。
2. 开发者缓存的jsticket时间过长导致jsticket已经过期。
报错提示“无效的agent_id”
需要检查appkey和agent_id所对应的应用，是否为同一个应用，必须是同一个应用下的agent_id和appkey才可以正常使用。
查看以下两项的值是否属于同一个应用。例如appkey对应的应用的agent_id为23456，b所对应的agent_id为23457，agent_id不同，可判断不是同一个应用，则会报错。
1. 调用获取jsapi_ticket接口，使用的access_token，使用的appkey
2. dd.config中传递的agent_id
免登报错52013，签名校验失败
1. 用户后端签名使用的url地址和前端访问地址需要严格一致，包括端口号。前端部分可以用alert显示出当前的location.href，后端部分请在签名的时候打印日志。
2. 访问通过反向代理服务器、各种NAT等场景下容易出现这种问题，如http缺省的80端口，和显式增加80的不是同一个URL。
3. 检查确认获取的jsapiticket是否正确或者过期。jsapiticket是否有效期内重复获取导致jsapiticket被覆盖。

这篇文档是否有帮助？

本页内容