钉钉企业应用C#开发笔记之一（免登）

2023-08-10 16:41:46

关于钉钉

钉钉是阿里推出的企业移动OA平台，本身提供了丰富的通用应用，同时其强大的后台API接入能力让企业接入自主开发的应用成为可能，可以让开发者实现几乎任何需要的功能。

近期因为工作需要研究了一下钉钉的接入，发现其接入文档、SDK都是基于java编写的，而我们的企业网站使用Asp.Net MVC（C#）开发，所以接入只能从头自己做SDK。

接入主要包括免登、获取数据、修改数据等接口。

免登流程

首先需要理解一下钉钉的免登流程，借用官方文档的图片：

是不是很熟悉？是的，基本是按照OAUTH的原理来的，版本嘛，里面有计算签名的部分，我觉得应该是OAUTH1.0。

有的读者会问，那第一步是不是应该跳转到第三方认证页面啊。我觉得“魔法”就藏在用来打开页面的钉钉内置浏览器里，在dd.config()这一步里，“魔法”就生效了。

其实简单来说，主要分为五步：

在你的Web服务器端调用api，传入CorpId和CorpSecret，获取accessToken，即访问令牌。
在服务器端调用api，传入accessToken，获取JsApiTicket，即JsApi的访问许可（门票）。
按照既定规则，在后台由JsApiTicket、NonceStr、Timestamp、本页面Url生成字符串，计算SHA1消息摘要，即签名Signature。
将AgentId、CorpId、Timestamp、NonceStr、Signature等参数传递到前台，在前台调用api，得到authCode，即授权码。
根据授权码，在前台或后台调用api，获得userId，进而再根据userId，调用api获取用户详细信息。

PS:为什么需要在后台完成一些api的调用呢？应该是因为js跨域调用的问题，我具体没有深究。

实践方法

理解了上述步骤，我对登陆过程的实现也大致有了一个设想，既然免登需要前后端一起来完成，那就添加一个专门的登陆页面，将登陆过程都在里面实现，将登陆结果写入到Session，并重定向回业务页面，即算完成。图示如下：

其中每个api的调用方式，在官方文档中都有说明。同时，我在阿里云开发者论坛找到了网友提供的SDK，有兴趣可以下载：钉钉非官方.Net SDK

另外，GitHub上还有官方的JQuery版免登开发Demo，可以参考：GitHub JQuery免登。

我参考的是.Net SDK，将其中的代码，提取出了我所需要的部分，做了简化处理。基本原理就是每次调用API都是发起HttpRequest，将结果做JSON反序列化。

核心代码如下：

 using System;

 using System.Collections.Generic;

 using System.Linq;

 using System.Web;

 using System.IO;

 using Newtonsoft.Json;

 using Newtonsoft.Json.Linq;

 using DDApi.Model;

 namespace DDApi

 {

     public static class DDHelper

     {

         public static string GetAccessToken(string corpId, string corpSecret)

         {

             string url = string.Format("https://oapi.dingtalk.com/gettoken?corpid={0}&corpsecret={1}", corpId, corpSecret);

             try

             {

                 string response = HttpRequestHelper.Get(url);

                 AccessTokenModel oat = Newtonsoft.Json.JsonConvert.DeserializeObject<AccessTokenModel>(response);

                 if (oat != null)

                 {

                     if (oat.errcode == )

                     {

                         return oat.access_token;

                     }

                 }

             }

             catch (Exception ex)

             {

                 throw;

             }

             return string.Empty;

         }

         /* https://oapi.dingtalk.com/get_jsapi_ticket?access_token=79721ed2fc46317197e27d9bedec0425

          *

          * errmsg    "ok"

          * ticket    "KJWkoWOZ0BMYaQzWFDF5AUclJOHgO6WvzmNNJTswpAMPh3S2Z98PaaJkRzkjsmT5HaYFfNkMdg8lFkvxSy9X01"

          * expires_in    7200

          * errcode    0

          */

         public static string GetJsApiTicket(string accessToken)

         {

             string url = string.Format("https://oapi.dingtalk.com/get_jsapi_ticket?access_token={0}", accessToken);

             try

             {

                 string response = HttpRequestHelper.Get(url);

                 JsApiTicketModel model = Newtonsoft.Json.JsonConvert.DeserializeObject<JsApiTicketModel>(response);

                 if (model != null)

                 {

                     if (model.errcode == )

                     {

                         return model.ticket;

                     }

                 }

             }

             catch (Exception ex)

             {

                 throw;

             }

             return string.Empty;

         }

         public static long GetTimeStamp()

         {

             TimeSpan ts = DateTime.UtcNow - new DateTime(, , , , , , );

             return Convert.ToInt64(ts.TotalSeconds);

         }

         public static string GetUserId(string accessToken, string code)

         {

             string url = string.Format("https://oapi.dingtalk.com/user/getuserinfo?access_token={0}&code={1}", accessToken, code);

             try

             {

                 string response = HttpRequestHelper.Get(url);

                 GetUserInfoModel model = Newtonsoft.Json.JsonConvert.DeserializeObject<GetUserInfoModel>(response);

                 if (model != null)

                 {

                     if (model.errcode == )

                     {

                         return model.userid;

                     }

                     else

                     {

                         throw new Exception(model.errmsg);

                     }

                 }

             }

             catch (Exception ex)

             {

                 throw;

             }

             return string.Empty;

         }

         public static string GetUserDetailJson(string accessToken, string userId)

         {

             string url = string.Format("https://oapi.dingtalk.com/user/get?access_token={0}&userid={1}", accessToken, userId);

             try

             {

                 string response = HttpRequestHelper.Get(url);

                 return response;

             }

             catch (Exception ex)

             {

                 throw;

             }

             return null;

         }

         public static UserDetailInfo GetUserDetail(string accessToken, string userId)

         {

             string url = string.Format("https://oapi.dingtalk.com/user/get?access_token={0}&userid={1}", accessToken, userId);

             try

             {

                 string response = HttpRequestHelper.Get(url);

                 UserDetailInfo model = Newtonsoft.Json.JsonConvert.DeserializeObject<UserDetailInfo>(response);

                 if (model != null)

                 {

                     if (model.errcode == )

                     {

                         return model;

                     }

                 }

             }

             catch (Exception ex)

             {

                 throw;

             }

             return null;

         }

         public static List<DepartmentInfo> GetDepartmentList(string accessToken, int parentId = )

         {

             string url = string.Format("https://oapi.dingtalk.com/department/list?access_token={0}", accessToken);

             if (parentId >= )

             {

                 url += string.Format("&id={0}", parentId);

             }

             try

             {

                 string response = HttpRequestHelper.Get(url);

                 GetDepartmentListModel model = Newtonsoft.Json.JsonConvert.DeserializeObject<GetDepartmentListModel>(response);

                 if (model != null)

                 {

                     if (model.errcode == )

                     {

                         return model.department.ToList();

                     }

                 }

             }

             catch (Exception ex)

             {

                 throw;

             }

             return null;

         }

     }

 }

 using System.IO;

 using System.Net;

 namespace DDApi

 {

     public class HttpRequestHelper

     {

         public static string Get(string url)

         {

             WebRequest request = HttpWebRequest.Create(url);

             WebResponse response = request.GetResponse();

             Stream stream = response.GetResponseStream();

             StreamReader reader = new StreamReader(stream);

             string content = reader.ReadToEnd();

             return content;

         }

         public static string Post(string url)

         {

             WebRequest request = HttpWebRequest.Create(url);

             request.Method = "POST";

             WebResponse response = request.GetResponse();

             Stream stream = response.GetResponseStream();

             StreamReader reader = new StreamReader(stream);

             string content = reader.ReadToEnd();

             return content;

         }

     }

 }

HttpRequestHelper

其中的Model，就不再一一贴出来了，大家可以根据官方文档自己建立，这里只举一个例子，即GetAccessToken的返回结果：

    public class AccessTokenModel

    {

        public string access_token { get; set; }

        public int errcode { get; set; }

        public string errmsg { get; set; }

    }

我创建了一个类DDApiService，将上述方法做了封装：

using DDApi.Model;

using System;

using System.Collections.Generic;

using System.Configuration;

using System.Security.Cryptography;

using System.Text;

namespace DDApi

{

    /// <summary>

    ///

    /// </summary>

    public class DDApiService

    {

        public static readonly DDApiService Instance = new DDApiService();

        public string CorpId { get; private set; }

        public string CorpSecret { get; private set; }

        public string AgentId { get; private set; }

        private DDApiService()

        {

            CorpId = ConfigurationManager.AppSettings["corpId"];

            CorpSecret = ConfigurationManager.AppSettings["corpSecret"];

            AgentId = ConfigurationManager.AppSettings["agentId"];

        }

        /// <summary>

        /// 获取AccessToken

        /// 开发者在调用开放平台接口前需要通过CorpID和CorpSecret获取AccessToken。

        /// </summary>

        /// <returns></returns>

        public string GetAccessToken()

        {

            return DDHelper.GetAccessToken(CorpId, CorpSecret);

        }

        public string GetJsApiTicket(string accessToken)

        {

            return DDHelper.GetJsApiTicket(accessToken);

        }

        public string GetUserId(string accessToken, string code)

        {

            return DDHelper.GetUserId(accessToken, code);

        }

        public UserDetailInfo GetUserDetail(string accessToken, string userId)

        {

            return DDHelper.GetUserDetail(accessToken, userId);

        }

        public string GetUserDetailJson(string accessToken, string userId)

        {

            return DDHelper.GetUserDetailJson(accessToken, userId);

        }

        public UserDetailInfo GetUserDetailFromJson(string jsonString)

        {

            UserDetailInfo model = Newtonsoft.Json.JsonConvert.DeserializeObject<UserDetailInfo>(jsonString);

            if (model != null)

            {

                if (model.errcode == )

                {

                    return model;

                }

            }

            return null;

        }

        public string GetSign(string ticket, string nonceStr, long timeStamp, string url)

        {

            String plain = string.Format("jsapi_ticket={0}&noncestr={1}&timestamp={2}&url={3}", ticket, nonceStr, timeStamp, url);

            try

            {

                byte[] bytes = Encoding.UTF8.GetBytes(plain);

                byte[] digest = SHA1.Create().ComputeHash(bytes);

                string digestBytesString = BitConverter.ToString(digest).Replace("-", "");

                return digestBytesString.ToLower();

            }

            catch (Exception e)

            {

                throw;

            }

        }

        public List<DepartmentInfo> GetDepartmentList(string accessToken, int parentId = )

        {

            return DDHelper.GetDepartmentList(accessToken, parentId);

        }

    }

}

DDApiService

以上是底层核心部分。登录页面的实现在控制器DDController中，代码如下：

using DDApi;

using DDApi.Model;

using System;

using System.Web.Mvc;

namespace AppointmentWebApp.Controllers

{

    public class DDController : Controller

    {

        //

        // GET: /DD/

        public ActionResult GetUserInfo(string accessToken, string code, bool setCurrentUser = true)

        {

            try

            {

                string userId = DDApiService.Instance.GetUserId(accessToken, code);

                string jsonString = DDApiService.Instance.GetUserDetailJson(accessToken, userId);

                UserDetailInfo userInfo = DDApiService.Instance.GetUserDetailFromJson(jsonString);

                if (setCurrentUser)

                {

                    Session["AccessToken"] = accessToken;

                    Session["CurrentUser"] = userInfo;

                }

                return Content(jsonString);

            }

            catch (Exception ex)

            {

                return Content(string.Format("{{'errcode': -1, 'errmsg':'{0}'}}", ex.Message));

            }

        }

        public ActionResult Login()

        {

            BeginDDAutoLogin();

            return View();

        }

        private void BeginDDAutoLogin()

        {

            string nonceStr = "helloDD";//todo:随机

            ViewBag.NonceStr = nonceStr;

            string accessToken = DDApiService.Instance.GetAccessToken();

            ViewBag.AccessToken = accessToken;

            string ticket = DDApiService.Instance.GetJsApiTicket(accessToken);

            long timeStamp = DDHelper.GetTimeStamp();

            string url = Request.Url.ToString();

            string signature = DDApiService.Instance.GetSign(ticket, nonceStr, timeStamp, url);

            ViewBag.JsApiTicket = ticket;

            ViewBag.Signature = signature;

            ViewBag.NonceStr = nonceStr;

            ViewBag.TimeStamp = timeStamp;

            ViewBag.CorpId = DDApiService.Instance.CorpId;

            ViewBag.CorpSecret = DDApiService.Instance.CorpSecret;

            ViewBag.AgentId = DDApiService.Instance.AgentId;

        }

    }

}

DDController

视图View的代码：

@{

    ViewBag.Title = "Login";

}

<!DOCTYPE html>

<html>

<head>

    <meta charset="utf-8" />

    <meta name="viewport" content="width=device-width" />

    <title>@ViewBag.Title</title>

</head>

<body>

    <h2 id="notice">正在登录...</h2>

    <script src="//cdn.bootcss.com/jquery/1.12.4/jquery.min.js"></script>

    <script type="text/javascript" src="http://g.alicdn.com/dingding/open-develop/1.5.1/dingtalk.js"></script>

    <script type="text/javascript">

        var _config = [];

        _config.agentId = "@ViewBag.AgentId";

        _config.corpId = "@ViewBag.CorpId";

        _config.timeStamp = "@ViewBag.TimeStamp";

        _config.nonceStr = "@ViewBag.NonceStr";

        _config.signature = "@ViewBag.Signature";

        dd.config({

            agentId: _config.agentId,

            corpId: _config.corpId,

            timeStamp: _config.timeStamp,

            nonceStr: _config.nonceStr,

            signature: _config.signature,

            jsApiList: ['runtime.info', 'biz.contact.choose',

                    'device.notification.confirm', 'device.notification.alert',

                    'device.notification.prompt', 'biz.ding.post',

                    'biz.util.openLink']

        });

        dd.ready(function () {

            dd.runtime.info({

                onSuccess: function (info) {

                    logger.e('runtime info: ' + JSON.stringify(info));

                },

                onFail: function (err) {

                    logger.e('fail: ' + JSON.stringify(err));

                }

            });

            dd.runtime.permission.requestAuthCode({

                corpId: _config.corpId,

                onSuccess: function (info) {//成功获得code值,code值在info中

                    //alert('authcode: ' + info.code);

                    //alert('token: @ViewBag.AccessToken');

                    /*

                    *$.ajax的是用来使得当前js页面和后台服务器交互的方法

                    *参数url:是需要交互的后台服务器处理代码，这里的userinfo对应WEB-INF -> classes文件中的UserInfoServlet处理程序

                    *参数type:指定和后台交互的方法，因为后台servlet代码中处理Get和post的doGet和doPost

                    *原本需要传输的参数可以用data来存储的，格式为data:{"code":info.code,"corpid":_config.corpid}

                    *其中success方法和error方法是回调函数，分别表示成功交互后和交互失败情况下处理的方法

                    */

                    $.ajax({

                        url: '@Url.Action("GetUserInfo", "DD")?code=' + info.code + '&accessToken=@ViewBag.AccessToken',//userinfo为本企业应用服务器后台处理程序

                        type: 'GET',

                        /*

                        *ajax中的success为请求得到相应后的回调函数，function(response,status,xhr)

                        *response为响应的数据，status为请求状态，xhr包含XMLHttpRequest对象

                        */

                        success: function (data, status, xhr) {

                            alert(data);

                            var info = JSON.parse(data);

                            if (info.errcode != 0) {

                                alert(data);

                            } else {

                                //alert("当前用户:" + info.name);

                                $('#notice').text("欢迎您：" + info.name + "。浏览器正在自动跳转...");

                                location.href = "@Url.Action("Index", "Home")";

                            }

                        },

                        error: function (xhr, errorType, error) {

                            logger.e("尝试获取用户信息失败:" + info.code);

                            alert(errorType + ', ' + error);

                        }

                    });

                },

                onFail: function (err) {//获得code值失败

                    alert('fail: ' + JSON.stringify(err));

                }

            });

        });

        dd.error(function (err) {

            alert('dd error: ' + JSON.stringify(err));

        });

    </script>

</body>

</html>

其中nonstr理论上最好应该每次都随机，留待读者去完成吧:-)

钉钉免登就是这样，只要弄懂了就会觉得其实不难，还顺便理解了OAUTH。

后续改进

这个流程没有考虑到AccessToken、JsApiTicket的有效期时间（2小时），因为整个过程就在一个页面中都完成了。如果想要进一步扩展，多次调用api的话，需要考虑到上述有效期。

如果为了图简便每都去获取AccessToken也是可以的，但是会增加服务器负担，而且api的调用频率是有限制的（1500次/s好像），所以应当采取措施控制。例如可以将AccessToken、JsApiTicket存放在this.HttpContext.Application["accessToken"]中，每次判断有效期是否过期，如果过期就调用api重新申请一个。

以上就是这样，感谢阅读。

20170710编辑，更新mvc免登流程图片，修正一处错误。

码农公寓

关于钉钉

免登流程

实践方法

后续改进

相关文章