HR系统如何实现与钉钉或企业微信的单点登录？
最近帮公司折腾HR系统和钉钉的对接，真是踩了不少坑，也琢磨透了不少事儿。这事儿说起来挺技术的，但其实逻辑理顺了，也就是那么几个关键步骤。如果你也是个半吊子技术或者HR转过来的项目负责人，正对着一堆开发文档发愁，那我这篇流水账或许能帮上点忙。咱们不整那些虚头巴脑的理论，就聊聊怎么一步步把这事儿给办成。
先搞明白，到底什么是“单点登录”？
很多人一听到SSO（Single Sign-On）就觉得高大上，其实说白了，就是“一次登录，到处通行”。想象一下，你早上到公司，先在钉钉上扫了脸或者输了密码登录了，然后你再去点开公司的HR系统、财务系统、项目管理系统，如果每一个都要你重新输一遍账号密码，那不得烦死？
单点登录要解决的就是这个痛点。它让你在钉钉（或者企业微信）登录之后，再去访问HR系统时，不需要再输入密码，系统自动就知道“哦，是张三来了”，然后直接放行。这不仅是为了方便，更是为了统一账号管理，安全系数也高。
在技术圈里，这通常基于一套标准的协议，最常用的就是OAuth 2.0和SAML 2.0。钉钉和企业微信主要支持的是OAuth 2.0这套体系。所以，咱们接下来的讨论，基本都是围绕这个展开的。
准备工作：手里得有“钥匙”
在动手写代码之前，你得先在钉钉和企业微信的后台把“通行证”申请下来。这就好比你要进一个高档小区，得先去物业登记，拿到门禁卡。
1. 钉钉侧的操作
你需要登录钉钉的开发者后台（通常是https://open.dingtalk.com）。
- 创建应用： 你得先创建一个“企业内部应用”。这个应用就是你的HR系统在钉钉上的“分身”。
- 获取凭证： 创建好后，你会拿到两个非常重要的东西：AppKey 和 AppSecret。这俩就像账号和密码，是你后续所有API调用的身份证明，千万不能泄露。
- 配置回调域名： 在应用设置里，有一个“开发配置”或者“回调地址”的地方。你必须把你HR系统的域名（比如
hr.yourcompany.com）填进去。如果不填，钉钉登录后跳转回来会报错，因为它不信任你的网站。 - 权限开通： 别忘了去“权限管理”里，把需要的接口权限开了。比如获取用户信息的权限。不然光有钥匙，进屋发现没开卧室门的权限也不行。
2. 企业微信侧的操作
企业微信的逻辑差不多，只是界面长得不一样。
- 创建自建应用： 在企业微信管理后台的“应用管理” -> “自建应用”里点创建应用。
- 获取AgentId和Secret： 这里你会得到 AgentId 和 Secret，作用和钉钉的AppKey/AppSecret类似。
- 配置可信域名： 同样，需要把你的HR系统域名加到“可信域名”列表里，并且要上传验证文件来证明这个域名是你的。
搞定了这些，手里就有了入场券。接下来就是代码层面的硬仗了。
核心流程：手把手教你“跳转”
单点登录的整个过程，其实就是一个“踢皮球”的过程。用户、HR系统、钉钉（或企微）三方来回倒手，最后把用户的身份确认下来。
我画个简单的流程图（文字版的），你感受一下：
用户访问HR系统 -> HR系统发现用户没登录 -> 跳转到钉钉登录页 -> 用户在钉钉扫码/输密码 -> 钉钉把用户“踢”回HR系统，并附带一个“临时票”（code） -> HR系统拿这个“临时票”去找钉钉换“真身证明”（access_token） -> 拿到“真身证明”再去查这个用户到底是谁 -> 查到后，在HR系统里创建Session，登录成功。
第一步：触发跳转
当用户打开你的HR系统网址时，你的后端代码首先要判断这个用户的Session里有没有登录信息。如果没有，那就得把他扔到钉钉去登录。
这个跳转地址是有固定格式的。以钉钉为例，大概是这样：
https://oapi.dingtalk.com/connect/qrconnect?appid=APPID&redirect_uri=REDIRECT_URI&response_type=code&scope=snsapi_login&state=STATE
这里面：
appid：就是你刚才申请的那个AppKey。redirect_uri：这是个非常关键的参数，它告诉钉钉，用户登录成功后，要把他跳回到哪个地址。这个地址必须是你刚才在后台配置的回调域名之一，并且需要进行URL编码。state：这是一个防CSRF攻击的参数，你可以随机生成一个字符串，先存起来，等钉钉跳回来的时候再比对一下，防止有人伪造请求。
企业微信的流程类似，只不过接口地址和参数名略有不同，叫corp_id之类的。
第二步：接收“临时票”并换取身份
用户在钉钉那边扫码确认后，浏览器会带着一个code参数跳回到你刚才填的redirect_uri地址上。比如：https://hr.yourcompany.com/callback?code=abcdefg123456&state=刚才生成的那个state。
你的后端这时候要做的第一件事是校验state对不对，防止 CSRF 攻击。对上了，就说明这个请求是合法的。
接下来，你就要拿着这个code去钉钉换access_token。这一步是纯后端操作，不能暴露给前端，因为要用到你的AppSecret。
请求地址大概是这样：
https://oapi.dingtalk.com/sns/gettoken?appid=APPID&appsecret=APPSECRET
然后用拿到的access_token，再带上刚才的code，去换取用户信息：
https://oapi.dingtalk.com/sns/get_persistent_code?access_token=ACCESS_TOKEN&tmp_auth_code=CODE
这一套操作下来，你就能拿到一个openid和unionid。这两个ID是用户在钉钉生态里的唯一标识。
第三步：映射到HR系统的用户
现在问题来了：你拿到了钉钉的unionid，但你的HR系统里存的是员工工号或者手机号。怎么把它们对应起来？
这就是实施过程中最需要花心思的地方。通常有几种做法：
- 预先绑定： 在HR系统里，有一个员工信息管理的模块。管理员在录入员工信息时，要求员工提供他们的钉钉/企微账号，或者由管理员统一在后台把员工的工号和他们的
unionid关联起来。这是最稳妥的方式。 - 首次登录时绑定： 如果HR系统里没有预先绑定，当用户第一次通过SSO登录时，系统会提示“未找到关联账号，请输入工号/手机号进行绑定”。用户输入后，系统验证通过，就把这个
unionid和该账号绑定，下次再登录就自动关联了。
一旦关联成功，你的HR系统就可以根据这个unionid查到对应的员工ID，然后在自己的系统里创建Session，标记用户已登录。至此，整个单点登录流程就走通了。
企业微信和钉钉的区别
虽然大体原理一样，但细节上还是有不少坑的。企业微信因为和微信打通，有时候会涉及到“微信授权”的问题，情况会稍微复杂一点。钉钉则相对纯粹，就是企业内部的逻辑。
另外，企业微信在获取用户信息时，有时候需要先获取userid，再通过userid去获取详细信息。而钉钉的unionid体系相对独立一些。所以在写代码的时候，一定要把两个平台的官方文档摆在手边，对着参数一个一个看，千万别想当然。
| 对比项 | 钉钉 (DingTalk) | 企业微信 (WeCom) |
|---|---|---|
| 核心凭证 | AppKey, AppSecret | CorpID, AgentId, Secret |
| 用户唯一标识 | UnionID, OpenID | UserID, OpenID |
| 登录协议 | OAuth 2.0 (主要) | OAuth 2.0 (主要) |
| 配置复杂度 | 中等，主要是配置回调域名和权限 | 中等，可信域名需要文件验证 |
常见问题与“填坑”指南
代码写完了，联调的时候往往会遇到各种奇葩问题。这里总结几个我遇到的，或者听说比较多的坑。
- 回调地址不匹配： 这是最常见的。检查一下是不是多了个斜杠，或者用了
http而钉钉后台配的是https。特别是本地开发的时候，很多人用localhost，但钉钉可能不支持，需要用127.0.0.1或者穿透工具。 - state校验失败： 检查一下生成state和校验state的逻辑是不是在同一个会话里。有时候用户登录时间太长，session过期了，就会导致校验失败。
- 权限不足： 拿到token了，但调用获取用户信息的接口报错“无权限”。多半是你在钉钉后台忘记勾选对应的API权限了，回去补上。
- 网络问题： 你的HR系统服务器如果在内网，访问钉钉的公网API可能会被防火墙挡住。需要确认网络策略，加白名单。
- UnionID映射问题： 用户换了部门，或者管理员在后台把用户删了重加，可能会导致UnionID变化。这种情况下，如果HR系统里是死绑定，用户就登录不上了。所以最好设计一个解绑和重新绑定的机制，或者在用户信息变更时同步更新。
安全性，永远是第一位的
做单点登录，方便是方便了，但安全这根弦时刻不能松。
首先，AppSecret这种东西，绝对不能硬编码在前端代码里，也不能直接写死在客户端App里。它必须安安稳稳地待在你的后端服务器上，最好是放在配置中心或者环境变量里。
其次，code是一次性的，而且有效期很短（通常是5分钟）。用过一次就得作废，防止被人截获后重放攻击。
再者，state参数一定要用，而且要足够随机。这是防御CSRF（跨站请求伪造）的最后一道防线。
最后，整个通信链路最好全站HTTPS，防止中间人窃听。毕竟传输的都是用户的敏感身份信息。
写在最后
折腾这套东西，技术上其实不算特别难，难的是细心和耐心。文档要读细，参数要对准，测试要覆盖各种边缘情况。有时候你会觉得，不就是登录一下嘛，至于这么麻烦吗？但当你看到用户点一下按钮，刷一下脸，就直接进入了HR系统，那种顺畅感，还是挺有成就感的。
这事儿本质上是把你的系统接入到企业统一的身份认证体系里。想通了这一点，不管是钉钉、企微，还是以后可能冒出来的什么新平台，逻辑都是一样的。无非就是换个地方申请钥匙，换个接口地址跳转而已。
希望这些乱七八糟的经验能帮你少走点弯路。如果还有哪块不清楚的，欢迎随时交流，毕竟这行就是得互相踩坑才能进步嘛。
紧急猎头招聘服务