免登:钉钉提供了OAuth的授权登录方式,可以让用户从钉钉客户端打开的网页直接获取成员的身份信息,从而免去登录的环节。
企业或者ISV开发的应用,需要让用户在登录钉钉进入应用的时候通过授权获取用户信息而不用输入用户名密码。这里面企业授权获取access_token和ISV授权获取access_token的方式不一样。
具体请参考:
应用 | 地址 |
---|---|
企业应用access_token获取 | 企业授权流程 |
ISV应用access_token获取 | ISV授权流程 |
完整的免登鉴权流程如下:
1. 在企业管理后台:https://oa.dingtalk.com/上注册企业完成之后,在企业应用-工作台设置页面里面,可以获取到企业的corpId和CorpSecret。
2.通过调用获取access_token的接口获取企业的access_token。
ISV应用的access_token是通过企业对ISV授权获取的。
企业应用如果配置了IP白名单,则请求域名的地址必须在IP白名单里面,且2小时之内通过接口重新请求的jsticket都会变。如果企业没有配置IP白名单,则2小时之内通过接口重新请求的jsticket不会变,只是jsticket的生命周期重新延长2小时。
ISV应用必须配置IP白名单,且请求域名的地址必须在IP白名单里面,2小时之内通过接口重新请求的jsticket都会变。
通过调用获取jsticket的接口获取企业的jsticket。
在前端进行免登鉴权之前,我们要先拿到一些免登鉴权的参数,主要有’url’,‘nonceStr’,‘agentId’,‘timeStamp’,‘corpId’
参数 | 说明 | 企业 | ISV |
---|---|---|---|
url | 当前网页的URL,不包含#及其后面部分 // | // | |
nonceStr | 随机串,自己定义 | // | // |
agentId | 应用的标识 | 编辑企业应用可以看到 | 在ISV调用get_auth_info接口里面可以获取 |
timeStamp | 时间戳 | 当前时间,但是前端和服务端进行校验时候的值要一致 | 当前时间,但是前端和服务端进行校验时候的值要一致 |
corpId | 企业ID | 企业ID,在开发者后台中企业视图下开发者账号设置里面可以看到 | 通过在页面地址上追加?corpId=$CORPID$进行获取 |
ISV应用agentId获取是在企业授权完成后,在调用get_auth_info接口的返回agent字段里面获取,具体返回数据如下:
"agent":[{ "agent_name":"aaaa", "agentid":1, "appid":-3, "logo_url":"http://aaaaaa.com" } ,{ "agent_name":"bbbb", "agentid":4, "appid":-2, "logo_url":"http://vvvvvv.com" }]
ISV可以用自己开发应用的appid进行匹配查找agentId。
在服务端通过sign(ticket, nonceStr, timeStamp, url)计算前端校验需要使用的签名信息。
代码展示:
public static String sign(String ticket, String nonceStr, long timeStamp, String url) throws OApiException { String plain = "jsapi_ticket=" + ticket + "&noncestr=" + nonceStr + "×tamp=" + String.valueOf(timeStamp) + "&url=" + url; try { MessageDigest sha1 = MessageDigest.getInstance("SHA-1"); sha1.reset(); sha1.update(plain.getBytes("UTF-8")); return bytesToHex(sha1.digest()); } catch (NoSuchAlgorithmException e) { throw new OApiResultException(e.getMessage()); } catch (UnsupportedEncodingException e) { throw new OApiResultException(e.getMessage()); } }
将:‘url’,‘nonceStr’,‘agentId’,‘timeStamp’,‘corpId’,‘signature’传递到前端页面,在前端HTML5页面使用jsapi提供的dd.config(PC客户端使用DingTalkPC.config)接口进行签名校验。
代码:
dd.config({ agentId: _config.agentId, corpId: _config.corpId, timeStamp: _config.timeStamp, nonceStr: _config.nonceStr, signature: _config.signature, jsApiList: [ 'runtime.info' // 需要用到的jsAPI都列在这里 ] });
https://g.alicdn.com/dingding/open-develop/1.6.9/dingtalk.js
或者
http://g.alicdn.com/dingding/open-develop/1.6.9/dingtalk.js
(PC客户端引入https://g.alicdn.com/dingding/dingtalk-pc-api/2.7.0/index.js
使用DingTalkPC.config)。
使用钉钉js-api提供的获取免登授权码接口获取CODE
通过免登授权码CODE可以换取用户身份userid,userid用于在一个企业内唯一标识一个用户,如果需要获取用户的更多信息可以调用通讯录管理的成员接口来获取。
Java ISV项目DEMO:下载
前端免登鉴权:https://github.com/injekt/openapi-demo-php/blob/master/corp/public/javascripts/demo.js
1.在使用jsApi的时候,引入的jsapi地址为:http://g.alicdn.com/dingding/dingtalk-pc-api/2.3.1/index.js
2.在使用jsApi的时候,调用方式为:DingTalkPC.config,用DingTalkPC替换移动客户端的dd调用方式。