WorkBuddy对接企业微信SSO教程

WorkBuddy支持通过原生OIDC或桥接SAML两种方式无缝对接企业微信实现单点登录（SSO），帮助企业用户告别重复登录、统一身份管理——无需复杂开发，只需配置可信域名、AgentId/Secret、重定向URI及用户属性映射，即可让员工一键扫码或授权登录，并自动完成首次开户与身份源标记；文章手把手详解两种路径的完整配置步骤、关键参数校验、登录链路验证及高频断连问题排查，助你快速落地安全、稳定、合规的企业级统一认证。

如果您希望WorkBuddy用户通过企业微信完成统一身份认证，避免重复登录，需通过SAML或OIDC协议对接企业微信的身份提供商（IdP）能力。企业微信本身不直接提供标准SAML IdP服务，但支持以OIDC方式作为OAuth 2.0授权服务器，并可通过第三方身份中台（如EIAM、IDaaS）桥接SAML请求。以下是两种可行路径的具体配置步骤：

一、通过OIDC协议对接企业微信（原生支持路径）

企业微信开放平台提供标准OIDC授权端点，WorkBuddy可作为OIDC客户端（RP）接入，实现基于企业微信账号的单点登录。该方式无需中间身份中台，适用于已启用企业微信“应用管理→自建应用→网页授权登录”的场景。

1、在企业微信管理后台开通网页授权登录权限：使用管理员账号登录，进入【应用管理】→【自建应用】→选择目标应用→【网页授权及JS-SDK】→开启【网页授权登录】并记录“可信域名”（必须与WorkBuddy前端访问域名一致）。

2、获取企业微信OIDC配置参数：在应用详情页的【网页授权及JS-SDK】区域，复制“AgentId”（作为client_id备用）、“Secret”（作为client_secret），并构造OIDC Issuer地址：https://qyapi.weixin.qq.com/cgi-bin/connect/oidc/.well-known/openid-configuration。

3、在WorkBuddy管理后台配置OIDC身份源：进入【系统设置】→【身份提供商】→【添加OIDC应用】，依次填入client_id（可填AgentId）、client_secret（应用Secret）、Issuer URL（上一步构造地址）、Authorization Endpoint与Token Endpoint（由Issuer地址自动发现）。

4、配置重定向URI：在企业微信应用的【网页授权及JS-SDK】→【授权回调域】中，添加WorkBuddy后台生成的回调地址，格式为：https://[your-workbuddy-domain]/login/oauth2/code/wecom，确保与WorkBuddy OIDC配置中的Redirect URI完全一致。

5、启用并测试：保存配置后，在WorkBuddy登录页应出现“企业微信登录”按钮；点击跳转至企业微信授权页，确认后完成SSO登录。

二、通过SAML协议对接（需经IDaaS/EIAM中台桥接）

企业微信不原生提供SAML IdP功能，但可通过支持SAML的统一身份管理平台（如腾讯云EIAM、阿里云IDaaS）将企业微信账号同步为SAML主身份源。该方式适用于已有SAML标准化治理要求的企业，依赖中台完成协议转换与断言签发。

1、在IDaaS控制台创建企业微信连接器：登录IDaaS实例，进入【身份源】→【添加身份源】→选择“企业微信”，填写企业微信管理后台获取的CorpID与应用Secret（需提前创建具备“读取成员信息”权限的自建应用）。

2、配置SAML应用：在IDaaS中【应用】→【添加应用】→【标准协议】→选择SAML，填写WorkBuddy的SP元数据（或手动输入ACS URL与Entity ID）；ACS URL格式为：https://[your-workbuddy-domain]/login/saml/consume。

3、下载IDaaS SAML元数据：在SAML应用详情页的【单点登录】页签，下载IDP元数据XML文件（含IDPSSODescriptor节点），该文件将用于WorkBuddy端导入。

4、在WorkBuddy后台导入SAML IdP元数据：进入【系统设置】→【身份提供商】→【添加SAML IdP】→上传上一步XML文件，系统自动解析SSO URL、证书与实体ID。

5、配置SP元数据并回填至IDaaS：WorkBuddy生成SP元数据XML后，在IDaaS对应SAML应用的【应用配置】中粘贴该内容，完成双向绑定。

三、验证SAML/OIDC登录链路有效性

无论采用哪种协议，均需验证用户属性映射与会话建立是否符合预期。关键校验点包括：用户唯一标识字段（如OIDC的sub或SAML的NameID）是否与企业微信员工UserID一致；邮箱、姓名等属性是否正确传递；首次登录时是否自动创建WorkBuddy本地账户（需开启自动用户预配）。

1、使用未登录过WorkBuddy的企业微信账号，访问WorkBuddy登录页并点击对应SSO按钮。

2、观察跳转流程：OIDC路径应跳转至企业微信授权页；SAML路径应跳转至IDaaS统一登录页，并显示企业微信图标供选择。

3、授权完成后，检查WorkBuddy前端是否显示该用户头像与真实姓名，且URL中不再包含登录参数。

4、在WorkBuddy后台【用户管理】中搜索该员工手机号或UserID，确认账户状态为“已激活”，且身份源标记为“wecom-oidc”或“idp-saml”。

四、处理常见断连错误

当SSO登录失败时，典型现象包括跳转后白屏、提示“无效签名”、“state mismatch”或“invalid_redirect_uri”。这些问题多源于配置参数错位或域名策略拦截，需逐项核对。

1、检查企业微信可信域名是否包含WorkBuddy完整访问地址（含https与端口），且无多余空格或斜杠。

2、确认OIDC client_id是否误用CorpID（应使用AgentId）；SAML中NameID Format是否设为urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified以兼容企业微信同步的UserID。

3、验证时间同步：WorkBuddy服务器系统时间与NTP标准时间偏差不得超过5分钟，否则OIDC ID Token或SAML响应会被判定为过期。

4、查看WorkBuddy日志中auth模块的ERROR条目，提取原始错误码（如errcode 82001对应企业微信签名失败），据此反查密钥或Token字段是否被截断或编码异常。

今天带大家了解了的相关知识，希望对你有所帮助；关于科技周边的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~