Excalidraw SSO单点登录配置教程（企业微信/钉钉）

Excalidraw SSO 单点登录配置实践（企业微信/钉钉）

在现代企业协作环境中，设计与沟通的效率往往决定了项目的推进速度。Excalidraw 作为一款轻量、开源且支持手绘风格的在线白板工具，因其极简界面和出色的实时协作能力，逐渐成为技术团队绘制架构图、流程图和原型设计的首选。尤其是结合 AI 功能后，仅通过自然语言就能生成可视化图表，进一步提升了创作效率。

但当企业希望将 Excalidraw 私有化部署并用于内部协作时，一个现实问题浮现：如何让员工无需注册新账号、直接使用现有的企业身份一键登录？这正是单点登录（SSO）的价值所在。

国内大多数企业已深度依赖企业微信或钉钉进行日常办公，这些平台不仅承载了组织架构，也集成了统一的身份认证体系。若能将 Excalidraw 接入其中，不仅能避免账号分散管理的混乱，还能显著提升安全性和用户体验。本文将从实战角度出发，深入解析如何基于 OAuth2.0 协议，完成 Excalidraw 与企业微信、钉钉的 SSO 集成，并提供可落地的技术方案与代码参考。

理解 SSO 的核心机制

单点登录的本质是“信任委托”——你信任某个权威机构（如企业微信）来验证用户身份，而你的应用只需确认这个验证结果是否合法即可。这种模式下，Excalidraw 不再需要存储任何密码，也不用处理复杂的注册流程，所有身份校验都由第三方完成。

整个过程基于OAuth2.0 授权码模式展开，这是目前最安全、最广泛采用的标准之一。其典型流程如下：

1. 用户访问私有部署的 Excalidraw 实例；
2. 若未认证，系统将其重定向至企业微信或钉钉的授权页面；
3. 用户在可信平台上完成登录（可能自动跳过，取决于配置）；
4. 平台返回一个临时的code到预设的回调地址；
5. Excalidraw 后端拿着这个code去换access_token和用户信息；
6. 获取成功后创建本地会话（如 Session 或 JWT），用户正式进入系统。

这一流程的关键在于：敏感凭证始终不经过前端，也不会被 Excalidraw 持久保存，从而极大降低了数据泄露风险。

相比传统用户名+密码的方式，SSO 在安全性、运维成本和用户体验上都有明显优势。更重要的是，它允许企业通过组织架构实现细粒度权限控制——比如只允许特定部门访问某些白板空间，或者自动禁用离职员工的访问权限。

企业微信集成：静默与非静默授权的选择

企业微信为第三方应用提供了完善的 OAuth2.0 支持，开发者可以根据场景选择两种授权模式：

• snsapi_base：静默授权，只能获取用户的UserId，无需用户点击确认，适合后台系统识别身份；
• snsapi_privateinfo：非静默授权，需用户手动同意，可获取姓名、头像等个人信息，更适合协作类应用。

对于 Excalidraw 这种强调多人协同的工具，推荐使用snsapi_privateinfo，以便在画布中标注真实用户信息，提升协作体验。

配置准备

在开始编码前，你需要在企业微信管理后台完成以下操作：

1. 创建一个自建应用，记录下CORPID（企业 ID）和SECRET（应用密钥）；
2. 设置可信域名，确保回调地址属于该域；
3. 开启“网页授权及JS-SDK”权限；
4. 添加REDIRECT_URI到授权回调域名列表中。

注意：企业微信要求回调路径必须是 HTTPS，且不能携带参数。

实现逻辑详解

下面是一个基于 Flask 的 Python 示例，完整展示了从跳转授权到建立本地会话的全过程：

from flask import Flask, request, redirect, session import requests app = Flask(__name__) app.secret_key = 'your-super-secret-key' # 应从环境变量读取 # 配置项（建议使用环境变量） CORPID = 'ww1234567890abcdef' SECRET = 'your-corp-secret' REDIRECT_URI = 'https://excalidraw.example.com/auth/wechat/callback' @app.route('/auth/wechat/login') def wechat_login(): auth_url = ( "https://open.weixin.qq.com/connect/oauth2/authorize?" f"appid={CORPID}&" f"redirect_uri={REDIRECT_URI}&" "response_type=code&" "scope=snsapi_privateinfo&" "state=EXCALI_SSO_STATE#wechat_redirect" ) return redirect(auth_url) @app.route('/auth/wechat/callback') def wechat_callback(): code = request.args.get('code') if not code: return "授权失败，缺少 code 参数", 400 # 1. 获取 access_token token_url = f"https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid={CORPID}&corpsecret={SECRET}" try: token_resp = requests.get(token_url).json() access_token = token_resp.get("access_token") if not access_token: return f"获取 access_token 失败: {token_resp}", 500 except Exception as e: return f"请求异常: {str(e)}", 500 # 2. 使用 code 换取用户基本信息 user_info_url = f"https://qyapi.weixin.qq.com/cgi-bin/user/getuserinfo?access_token={access_token}&code={code}" user_resp = requests.get(user_info_url).json() userid = user_resp.get("UserId") if not userid: return "无法获取用户 UserId", 401 # 3. 获取详细信息（姓名、头像等） detail_url = f"https://qyapi.weixin.qq.com/cgi-bin/user/get?access_token={access_token}&userid={userid}" user_detail = requests.get(detail_url).json() # 4. 建立本地会话 session['user'] = { 'id': userid, 'name': user_detail.get('name'), 'avatar': user_detail.get('avatar', ''), 'department': user_detail.get('department', []) } return redirect("/excalidraw")

关键注意事项：

• state 参数防 CSRF：虽然示例中固定为EXCALI_SSO_STATE，但在生产环境中应生成随机字符串并存入 session，回调时比对；
• 错误处理要全面：每个 API 调用都应检查errcode字段，避免因网络波动导致流程中断；
• 敏感信息脱敏：除非必要，不要持久化手机号、邮箱等字段，符合《个人信息保护法》要求；
• Session 安全性：启用 Secure、HttpOnly Cookie，设置合理的过期时间（建议 2 小时）；

此外，若企业规模较大，建议引入缓存机制（如 Redis）存储access_token，避免频繁调用/gettoken接口（每日调用上限有限）。

钉钉集成：扫码登录的流畅体验

相较于企业微信的链接跳转式授权，钉钉更倾向于“扫码登录”，尤其适合移动端用户。其实现方式略有不同，主要依赖前端 JS SDK 渲染二维码，扫码后由后端完成授权码交换。

钉钉的 OAuth2.0 流程分为两步：

1. 前端加载dingtalk.js，调用DDLogin()显示二维码；
2. 用户扫码后跳转至回调 URL，携带tmp_auth_code；
3. 后端使用该 code 换取openid和unionid，进而查询用户信息。

需要注意的是，普通 OAuth 返回的是开放身份标识（openid/unionid），如果想获取企业在钉钉内的userid（用于消息通知或权限判断），还需额外申请“企业内部免登”权限，并由管理员授权。

前端接入方式

钉钉提供了简洁的 JS 组件，只需在登录页嵌入以下代码：

<div id="login-container"></div> <script src="https://g.alicdn.com/dingding/open-develop/1.10.5/dingtalk.js"></script> <script> DDLogin({ id: "login-container", goto: encodeURIComponent("https://your-excalidraw-domain/auth/dingtalk/callback"), style: "border:none;background-color:#FFFFFF;", width: "360px", height: "400px" }); </script>

该组件会自动渲染一个美观的二维码区域，支持 PC 和手机适配。

后端处理逻辑

from flask import Flask, request, session, redirect import requests app = Flask(__name__) app.secret_key = 'your-secret-key' DINGTALK_APPKEY = 'your-dingtalk-appkey' DINGTALK_APPSECRET = 'your-dingtalk-secret' @app.route('/auth/dingtalk/callback') def dingtalk_callback(): tmp_auth_code = request.args.get('code') # 注意：钉钉叫 code，实为 tmp_auth_code if not tmp_auth_code: return "缺少临时授权码", 400 # 1. 获取 sns_access_token token_url = "https://oapi.dingtalk.com/sns/gettoken" params = {'appid': DINGTALK_APPKEY, 'appsecret': DINGTALK_APPSECRET} resp = requests.get(token_url, params=params).json() sns_access_token = resp.get('access_token') if not sns_access_token: return f"获取 sns_access_token 失败: {resp}", 500 # 2. 换取用户信息 auth_url = f"https://oapi.dingtalk.com/sns/getuserinfo_bycode?access_token={sns_access_token}" data = {'tmp_auth_code': tmp_auth_code} headers = {'Content-Type': 'application/json'} user_resp = requests.post(auth_url, json=data, headers=headers).json() if user_resp.get("errcode") != 0: return f"获取用户信息失败: {user_resp.get('errmsg')}", 500 userinfo = user_resp['user_info'] openid = user_resp['openid'] unionid = user_resp['unionid'] # 3. 建立会话 session['user'] = { 'id': unionid, 'name': userinfo.get('nick'), 'avatar': userinfo.get('avatar'), 'openid': openid } return redirect("/excalidraw")

特别提醒：

• tmp_auth_code有效期仅为 15 分钟，务必及时处理；
• 如果后续需要调用企业级接口（如发送工作通知），必须通过 CorpId + UnionId 映射出userid；
• 钉钉的 UnionId 是跨应用唯一的，适合做用户去重和关联分析；
• 所有接口调用频率受限，建议做好失败重试和日志追踪。

架构设计与最佳实践

典型的集成架构可以划分为三层：

[用户浏览器] ↓ [Excalidraw 前端] → (静态资源，Nginx/CDN) ↓ [认证服务层] → (Flask/FastAPI/Node.js) ↓ [身份提供商] → (企业微信 / 钉钉 OpenAPI)

为了提高系统的可维护性和扩展性，建议在实现时遵循以下原则：

抽象认证模块

不要把企业微信和钉钉的逻辑写死在主流程中。可以通过策略模式封装不同的 IdP 实现，例如定义统一接口：

class AuthProvider: def get_authorize_url(self) -> str: ... def authenticate(self, code: str) -> dict: ...

这样未来若要接入 LDAP、Keycloak 或飞书，只需新增一个实现类即可。

使用成熟库替代手动请求

虽然手动调用 HTTP 接口有助于理解流程，但在生产环境中建议使用专业库，如 Python 的 Authlib 或 Node.js 的 Passport.js，它们内置了多种 OAuth 提供商的支持，减少了出错概率。

安全加固措施

• 强制启用 HTTPS，防止中间人攻击；
• 所有回调接口校验state参数；
• 敏感配置（AppSecret、CORPID）全部通过环境变量注入；
• 记录关键操作日志（登录、登出、失败尝试），便于审计；
• 对高权限操作增加二次确认机制。

用户体验优化

• 登录页清晰展示“企业微信”和“钉钉”两个入口按钮；
• 支持移动端扫码自动唤起 App；
• 提供管理员紧急登录通道（如 Token 登录），以防 IdP 故障；
• 会话过期后引导重新认证，而非直接报错。

写在最后

将 Excalidraw 接入企业微信或钉钉的 SSO 体系，看似只是多了一个登录按钮，实则打通了整个组织的身份脉络。员工不再需要记忆额外账号，管理者也能借助 HR 系统实现账号生命周期自动化管控——入职即可用，离职即失效。

更重要的是，这种集成方式体现了现代企业应用的发展趋势：专注核心功能，复用已有基础设施。Excalidraw 专注于提供极致的绘图体验，而身份认证交给更专业的平台处理，双方各司其职，共同构建高效、安全的协作生态。

通过本文提供的配置思路与代码模板，企业可在数小时内完成基础集成。当然，实际部署中还需考虑负载均衡、日志监控、多实例会话共享等问题。但对于绝大多数团队而言，这套方案已经足够支撑起一个稳定可靠的私有化白板平台。

最终你会发现，真正推动 Adoption 的不是功能有多强大，而是“用起来够简单”。当一名工程师能在钉钉群里随手点开一个链接就开始画架构图时，协作就已经悄然发生了。