钉钉开发文档

身份验证

更新时间: 2019-1-3

通过本小节的阅读,您可以了解到,通过前后端代码的配合,获取正在访问您应用的当前用户身份的流程。

免登:钉钉用户在进入您开发的应用时,无需用户输入用户名密码,应用即可获取用户身份的流程。

获取用户身份流程

描述 接口 接口类型
获取免登授权码 dd.getAuthCode 前端JSAPI
获取用户基本信息 /sns/getuserinfo_bycode 服务端API

获取免登授权码

接口说明

dd.getAuthCode

返回值:

名称 类型 描述
authCode string 免登授权码(authCode) ,5分钟有效,且只能使用一次

使用说明

该接口为前端JSAPI,直接在应用页面的onLoad方法里面调用即可。

客户端 Android iOS PC
支持说明 4.3.5及以上支持 4.3.5及以上支持 不支持

获取 authCode 示例

dd.getAuthCode({
    success:(res)=>{
        dd.alert({content: res.authCode})
    },
    fail: (err)=>{
        dd.alert({content: JSON.stringify(err)})
    }
})

获取用户基本信息

通过免登授权码获取用户信息,参数authcode只能使用一次。

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/sns/getuserinfo_bycode?signature=kKlP1QmmiNR4VF&timestamp=1527130370219&accessKey=yourAppId

请求包结构体

{
    "tmp_auth_code": "23152698ea18304da4d0ce1xxxxx"
}

URL签名参数说明:

参数 说明
accessKey 应用的appId
timestamp 当前时间戳,单位是毫秒
signature 通过appSecret计算出来的签名值

参数说明

参数 参数类型 必须 说明
tmp_auth_code String 用户授权给钉钉开放应用的免登授权码,通过dd.getAuthCode获取

SDK请求示例(JAVA)

DefaultDingTalkClient  client = new DefaultDingTalkClient("https://oapi.dingtalk.com/sns/getuserinfo_bycode");
// 如果您使用的SDK中不存在该类,请下载最新的SDK
OapiSnsGetuserinfoBycodeRequest req = new OapiSnsGetuserinfoBycodeRequest();
req.setTmpAuthCode("4a2c5695b78738d495f47b5fee9160cd");
OapiSnsGetuserinfoBycodeResponse response = client.execute(req,"yourAppId","yourAppSecret");

返回结果

{ 
    "errcode": 0,
    "errmsg": "ok",
    "user_info": {
        "nick": "张三",
        "openid": "liSii8KCxxxxx",
        "unionid": "7Huu46kk"
    }
}
参数 说明
nick 用户在钉钉上面的昵称
openid 用户在当前开放应用内的唯一标识
unionid 用户在当前开放应用所属的钉钉开放平台账号内的唯一标识

返回错误码说明:

错误码 说明
853002 timestamp参数不合法,该参数值与钉钉服务器当前时间相差超过1分钟
853001 timestamp参数格式不正确,必须是当前时间的毫秒数
853003 accessKey参数不合法,必须是钉钉开放平台存在的appId
853004 signature参数不正确,与钉钉服务端计算出来的签名不一致,注意该参数传递时必须urlEncode

签名说明

签名算法为HmacSHA256,签名数据是当前时间戳timestamp, 秘钥是appId对应的appSecret计算出来的签名值。
发送http请求时需要把signature进行urlencode, 如果您使用的是http封装方法,请确保不要重复urlencode。
建议使用官方SDK, SDK中已集成签名算法。

签名参数说明

参数 说明
accessKey 扫码登录应用的appId
timestamp 当前时间戳,单位是毫秒
signature 通过appSecret计算出来的签名值, 该参数值在http请求参数中需要urlEncode(因为签名中可能包含特殊字符+)

签名计算Java

// 根据timestamp, appSecret计算签名值
String stringToSign = timestamp
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(appSecret.getBytes("UTF-8"), "HmacSHA256"));
byte[] signatureBytes = mac.doFinal(stringToSign.getBytes("UTF-8"));
String signature = new String(Base64.encodeBase64(signatureBytes));
String urlEncodeSignature = urlEncode(signature);

签名计算PHP

<?php
    // 根据timestamp, appSecret计算签名值
    $s = hash_hmac('sha256', 'timestamp', 'appSecret', true);
    $signature = base64_encode($s);
    var_dump($signature);
    $urlencode_signature = urlencode($signature);
    var_dump($urlencode_signature);
?>

java版本的urlEncode

// encoding参数使用utf-8
public static String urlEncode(String value, String encoding) {
    if (value == null) {
        return "";
    }
    try {
        String encoded = URLEncoder.encode(value, encoding);
        return encoded.replace("+", "%20").replace("*", "%2A")
            .replace("~", "%7E").replace("/", "%2F");
    } catch (UnsupportedEncodingException e) {
        throw new IllegalArgumentException("FailedToEncodeUri", e);
    }
}

签名例子参考:

  • timestamp=1546084445901
  • appSecret=testappSecret
  • signature=HCbG3xNE3vzhO+u7qCUL1jS5hsu2n5r2cFhnTrtyDAE=
  • urlEncode后的signature=HCbG3xNE3vzhO%2Bu7qCUL1jS5hsu2n5r2cFhnTrtyDAE%3D

CURL例子

curl 'https://oapi.dingtalk.com/sns/getuserinfo_bycode?signature=xxxxxx&timestamp=1527130370219&accessKey=dingxxxxyyy' -d '{"tmp_auth_code":"tmp_auth_code"}'
以上内容是否对您有帮助:
在文档使用中是否遇到以下问题(多选):
  • 内容错误
  • 更新不及时
  • 链接错误
  • 缺少代码/图片示例
  • 太简单/步骤待完善
手机号
更多建议
提交成功,感谢您的反馈!