# 单点登录集成问题排查指南

# 一、前置操作：补丁更新

在开始排查问题前，请务必完成以下补丁更新步骤，以排除已知问题的干扰：

前端： 优先安装最新的前端补丁
后端： 优先建议安装后端合集补丁，若无合集补丁通过以下链接检查是否存在相关补丁。若存在，请先安装对应补丁再进行后续问题排查

补丁参考链接：http://help.primeton.com/productcs/patches/

# 二、问题排查

前置检查：检查user-config.xml配置文件的白名单配置是否完善,以下配置是一定要有的：

Afc登录相关：
            /api/afc/validation-code （获取验证码。afc登录和oauth2登录都需要）
            /api/afc/login（登录）
            /api/afc/login/password/key（获取加密公钥）
            /api/afc/user/validation-code(根据账号查询是否需要验证码登录，afc登录和oauth2登录都需要)
            /api/afc/login/clientId(通过clientId和secret进行认证)
 三方登录：
            /api/afc/login/third-party/qrConnect（获取第三方扫码登录服务地址）
            /api/afc/login/third-party/mobile/authorize（获取第三方认证服务地址）
            /api/afc/login/third-party/auth（通过第三方授权码登录）
            /api/afc/login/web/third-party/auth（网页内第三方授权码登录）
            /api/afc/login/third-party/types（获取配置的第三方扫码登录服务类型）
            /api/afc/login/third-party/validate（判断是否需要跳转认证地址，需要则返回认证地址）
oauth2统一认证：
            /api/afc/oauth2/*

            /api/afc/sso/redirect-url/default

# 1. 登录跳转与重定向异常

# 1.1 OAuth2认证登录后未携带用户信息

典型表现：点击链接认证后打开应用，但系统内无当前登录人信息。

排查与解决方案：

参考文档检查相关配置：OAuth2集成方案 (opens new window)
检查地址栏添加 appid 时是否同时设置了 user 相关信息
配置无误后，安装最新的前端补丁

# 1.2 首选项开启SSO自动登陆后，单点登录失败情况下登录页就一直刷，无法直接进入主页

典型表现：首选项开启SSO自动登陆后，单点登录失败情况下登录页就一直刷，无法直接进入主页

排查与解决方案：正常现象，SSO自动登陆开关作用：开启sso自动登陆，自动往ssologin-url跳转，即不能走AFCENTER的登录了，只能是走SSO登录

# 1.3 钉钉/企业微信扫码登录异常

典型表现：扫码后报错或无法登录。

排查与解决方案：

安装最新的前端补丁
参考文档检查相关配置：

注意事项：

检查连接器中配置的“重定向URI”
严禁使用 127.0.0.1 或 localhost，必须填写服务器实际的IP地址或域名
修改为实际IP后重试

# 2. 第三方集成配置类问题

# 2.1 钉钉/企业微信/飞书集成失败

典型表现：提示权限不足或获取用户信息失败。

排查与解决方案：

配置检查：参考文档检查相关配置（链接同上）
权限检查：确保第三方应用后台已开通必要的接口权限，如：
- 通讯录个人信息读权限
- 成员信息读权限
信息匹配（默认模式）：在 AFCenter 的“组织权限中心 > 组织中心 > 机构管理 > 员工”中，为员工配置电话（非工作电话），该号码需与第三方系统中的手机号完全一致
信息匹配（兼容模式，仅企业微信）：若手机号不一致，可在连接器配置中开启“兼容方案”，改用 UserId 匹配（需提前在 AFCenter 维护员工编码）

# 2.2 iframe嵌套集成无法登录

典型表现：第三方系统通过 iframe 嵌入 AFC 页面后一直显示登录页。

排查与解决方案：

CAS模式：访问 AFC 地址时需拼接 ticket 参数（例：...?ticket=xxx）
OAuth2/免密模式：需在 URL 后拼接 token（参考访问凭证文档 (opens new window)），或通过拦截器实现伪登录（参考拦截器伪登录文档 (opens new window) 实现 UserLoginInterceptor）

建议：优先采用标准的登录认证集成方式，避免使用免密拼接

# 3. 常见操作建议

IP配置规范：涉及第三方回调（Redirect URI）的配置，严禁使用 127.0.0.1，必须使用局域网IP或公网域名
补丁验证：请优先安装最新的前端补丁及后端合集补丁
员工信息维护：集成钉钉、企业微信等生态时，确保系统内的员工手机号、员工编码与第三方平台严格一致，这是身份映射的关键