EOS Low-Code Platform 8
学习指南
更新说明
初见EOS
专业代码开发手册
智能体开发手册
公共服务框架

# 集成第三方登录认证

第三方集成登录认证配置现在都需要在连接器中进行配置。

image-20250407160709978

其中SSO配置包含oauth2客户端、cas客户端及申石客户端配置，可以搭配首选项SSO配置，进行访问首页即可跳转默认认证服务进行认证。

SSO配置首选项如下：

image-20250409160355332

# OAuth2集成方案

Oauth2认证集成准备流程如下如，本章节讲解AFCenter做客户端，配置参考下图蓝色部分。

认证集成流程

AFCenter提供了默认的基于(授权码模式)OAuth2-Client实现，只需要稍加配置即可使用，如果认证服务器有特殊需求可在此基础上进行修改或者参照去实现就行。

# 默认实现

连接器配置：

1、选择连接器中的SSO配置

image-20250407160855728

2、新建Oauth2类型配置，并按照要求填写配置项

image-20250407161102761

配置项释义：

  1. authorize-url：认证端授权地址，eg，http://localhost:1111/oauth2/authorize
  2. token-url：认证端获取token地址，eg，http://localhost:1111/oauth2/token
  3. client-id：clientid，应用code/租户Id，eg：XXX/123
  4. client-secret：clientSecret
  5. redirect-url：客户端登录页前端地址
  6. userinfo-url：认证端获取用户信息的地址
  7. user-key：如果获取的用户信息是json对象，映射关系是某个属性，则填写属性名称，否则默认返回的数据就是映射关系值，例如返回的userId
  8. access-token-key：使用code获取access_token时，如果直接返回值，则无需配置，返回的是json对象，需要配置access_token属性名称
  9. 是否默认：配置多个Oauth2-Client配置时，默认使用的(默认设置必须是启用状态)
  10. 启用状态：配置是否生效

AFCenter和微应用使用oauth2-sso时都需要配置这个属性,其中微应用的redirect-url是AFCenter的地址

# 默认实现流程步骤

下面罗列 AFC 作为 OAuth2 客户端，默认实现的标准流程。

基于该流程，结合 OAuth2 认证端提供的对接文档进行判断，是否符合 AFC 的默认实现标准：

  • 如满足，则直接通过首选项配置即可；
  • 如不满足，则需要定制开发。

# 完整时序图

img-login_3rd-01.png

# 第 1 步：获取三方认证端服务授权地址

GET {authorize-url}?response_type=code
        &client_id={client-id}
        &redirect_uri={redirect-url（URLEncode）}
        &state={state}

验证方法： 浏览器 F12 → Network → 找到 authorize 请求

排查方向： 检查参数是否一致有缺失

# 第 2 步：用户在第三方系统完成认证，获取授权码

浏览器跳转到第三方认证服务登录页，用户完成身份认证后，第三方服务将 302 重定向到：

{redirect_uri}?code={authorization_code}&state={state}

验证方法： 在F12接口中，检查是否携带 code 参数和 state参数

排查方向：

  • 如没有 code：检查第三方平台 redirect_uri 白名单配置
  • 如 state 不一致：可能是 CSRF 攻击，也可能是浏览器缓存问题

# 第 3 步：前端将 code 传递给 AFCenter 后端

AFCenter 前端将 URL 中的 code 和 state 通过 POST 请求传递给后端：

POST /afc/login/third-party/auth
Content-Type: application/json

{
    "code": "获取到的授权码",
    "state": "原始state参数"
}

验证方法： F12 Network → 找到 auth 请求 → 查看 Response 是否返回用户信息

排查方向： 如返回 INVALID_CODE，code 已过期（默认 60 秒），需重新触发登录

# 第 4 步：AFCenter 后端用 code 换取 Access Token

POST {token-url}?grant_type={authorization_code}
        &client_id={client-id}
        &client_secret={client-secret}
        &code={authorization_code}
        &redirect_uri={redirect-url}
Content-Type: application/json

第三方服务端返回响应示例：
// 情形1：直接返回 access_token 字符串（access-token-key 不配置）
"eyJhbGciOiJSUzI1NiJ9.xxxx"

// 情形2：返回 JSON 对象（需配置 access-token-key）。如下，如果 access-token-key 配置为 access_token，则 AFCenter 从 JSON 中提取该字段值作为 access_token 使用
{
    "access_token": "eyJhbGciOiJSUzI1NiJ9.xxxx",
    "expires_in": 3600,
    "token_type": "Bearer"
}

验证方法： 从此步开始，接口请求发生在后端，浏览器F12已无法捕获。查看 AFCenter 后端日志，搜索 accessToken 关键字

排查方向：

  • 如返回 OAUTH_SSO_ACCESSTOKEN_EMPTY：检查 access-token-key 配置是否正确
  • 如返回错误：检查 client_secret 是否正确、code 是否已过期

# 第 5 步：AFCenter 后端获取用户信息

POST {userinfo-url}
Content-Type: application/json
Authorization: {access_token}

（body 为空）


第三方服务端返回响应示例：
// 情形1：直接返回用户标识字符串（user-key 不配置）
"user123"

// 情形2：返回 JSON 对象（需配置 user-key）。如下，如果 user-key 配置为 userId，则 AFCenter 从 JSON 中提取该字段值作为用户标识，用于在本地账户中查找对应用户
{
    "userId": "user123",
    "username": "张三",
    "email": "zhangsan@example.com"
}

验证方法： 查看 AFCenter 后端日志，搜索 ueserInfo 关键字

排查方向： 如返回 OAUTH_SSO_USERINFO_EMPTY，检查 user-key 是否与返回 JSON 的字段名一致

# 第 6 步：AFCenter 本地用户匹配与登录

// AFCenter 用 "user123" 在本地用户表中查找:
// - 找到 → 取用户 ID，创建会话，返回登录成功
// - 未找到 → 直接用 "user123" 创建新用户并登录

登录成功后返回 UserObject，前端获取 AFCenter 本地认证令牌，完成登录

验证方法： 登录后查看 AFCenter 右上角是否显示正确用户名

排查方向： 如显示的用户不对，确认第三方返回的 userId 是否与 AFCenter 用户编码一致

# 自定义实现

如果默认实现不满足需求，比如认证服务器的所有接口都是post请求(默认的获取token的接口是post请求，获取用户信息的是get请求)，则可以实现该类

com.primeton.gocom.afcenter.api.oauth.IOauthCustomService

重写对应的三个方法

//初始化userObject
IUserObject initUserObject(String userValue) throws Exception;
//获取用户信息
String ueserInfo(String accessToken,String userinfoUrl) throws Exception;
//获取accessToken
String accessToken(String code,String tokenUrl,String clientId,String clientSecret,String redirectUrl) throws Exception;

实现完成后，在com.primeton.gocom.afcenter.starter.config.AFCServerAutoConfiguration类中声明一个bean，bean的名称必须为oauth2Client- + 连接器配置编码，例如连接器编码为idmesh-iam-java，则bean的名称就为oauth2Client-idmesh-iam-java

@Bean("oauth2Client-idmesh-iam-java")
public IOauthCustomService customService() {
    //自定义实现类是指：实现了com.primeton.gocom.afcenter.api.oauth.IOauthCustomService的自定义类
    return new 自定义实现类();
}

确保该实现可以被spring的ioc容器管理即可。

# 自定义实现场景示例

自定义实现场景示例

# CAS集成方案

# pc端集成

连接器配置：

1、选择连接器中的SSO配置

image-20250407160855728

2、新建CAS类型配置，并填写相关配置

image-20250407173310080

配置项释义：

  1. service-url:cas回调地址，一般配置为afc的前端pc/移动端首页地址；例如http://10.15.15.151:14082(pc) http://10.15.15.151:14082/mobile(移动)。
  2. sso-validate-url:ticket校验url
  3. sso-login-url:cas登录地址
  4. proxy-callback-url:代理回调URL（可以没有）
  5. sso-logout-url:cas登出地址
  6. 是否默认：配置多个CAS配置时，默认使用的(默认设置必须是启用状态)
  7. 启用状态：配置是否生效
注：

1：需确保service-url与cas客户端配置的service-url完全一致；afc的service-url配置也可为空，默认是当前window.location.origin。

2：AFCenter中需要有对应的账户信息

# 移动端集成：

移动端同样支持cas集成登陆；

第一步：确认第三方sso统一认证中心，配置service,service-url就是配置移动端首页地址，例如：http://10.15.15.151:14082/mobile。

第二步：在AFCenter移动端前端介质中config文件夹下的app-config.json文件里面ssoService参数值，可以配置为http://10.15.15.151:14082/mobile。（注：多域名场景下，首选项平台登陆页开启了SSO自动登陆后，ssoService参数值可不配置，默认取当前域名。）

第三步：在app-config.json文件中将loginType参数值设置为 'normal'。

# 集成场景与常见问题

1.第三方系统通过 iframe 嵌套 AFC 前端页面，CAS 登录三方系统后，点击三方菜单直接访问 AFC 菜单页面如何实现？

实现方式：三方系统登录后，访问 AFC 前端地址并拼接 CAS 颁发的 ticket 参数，即可完成 AFC 的 CAS 认证登录。示例：

https://ai.scjgj.sh.cegn.cn?ticket=5a286dc643df0c1ddbdaa4028f6d963a

说明：

https://ai.scjgj.sh.cegn.cn：AFC 前端页面地址； ticket：CAS 登录集成颁发的票据。

2.集成cas，需要同时满足cas登录和密码登录

请查看赋能平台知识库集成cas需要同时满足cas登录和密码登录。

# 集成企业微信

在AFCenter中，像企业微信、钉钉这些第三方认证可以配置多个，供用户登录时选择不同生态。集成时需要在AFCenter的组织权限中心-组织管理-机构管理-员工管理中给员工的详细信息中配置员工的电话(非工作电话)，这个电话要和员工的第三方系统中使用的电话号码相同。

1、选择连接器中的企业微信配置

image-20250408091816027

2、选择登录认证，填写企业微信认证配置

image-20250408092238787

配置项释义：

  1. CropId：是企业的CorpID

  2. AgentId：是应用的id

  3. Secret：是应用的密钥

  4. 重定向URI：是PC端前端的域名和端口(需要在企业微信的应用管理中开启企业微信授权登录，并配置Web网页授权回调域)

  5. 移动端重定向URI：是移动端前端的域名和端口(此域名需要在企业微信中配置可信回调域)

  6. 兼容方案：是一个可选配置，默认是false，此配置如果设置为true则不使用手机号进行用户身份认证，改用企业微信中的userId进行身份认证，注意，userId需要跟AFCenter中的员工编码一致，需要手动提前配置。

  7. 企业微信中配置afc移动端首页时需要增加type=weixin参数，例如：http://localhost:81/#/login?type=weixin

# 集成钉钉

公共说明参考集成企业微信。

1、选择连接器中的钉钉配置

image-20250409103124484

2、选择登录认证，填写登录认证配置

image-20250409103105807

配置释义：

  1. AppKey：是钉钉中应用的唯一标识、

  2. AppSecret：是钉钉中应用的密钥、

  3. AgentId：是微应用的agent_id

  4. 重定向URI：是PC端集成钉钉时的前端域名和端口，移动端的配置在钉钉中进行配置

  5. 集成钉钉时还需要给该应用下的组织机构人员在钉钉中配置权限，需要个人手机号信息、通讯录个人信息读权限、邮箱等个人信息、企业员工手机号信息、成员信息读权限、根据手机号姓名获取成员信息的接口访问权限、企业微应用后台免登接口的访问权限、调用OpenApp专有API时需要具备的权限。具备以上这些权限才能保证AFCenter中钉钉集成相关功能可用。

  6. 钉钉中配置afc移动端首页时需要增加type=dingding参数和corpId=$CORPID$参数，其中corpId=$CORPID$参数是钉钉官方定义的参数会把corpId通过这种方式再访问时携带上，例如：http://localhost:81/#/login?corpId=$CORPID$&type=dingding

# 集成飞书

公共说明参考集成企业微信。

1、选择连接器中的飞书配置

image-20250409112045520

2、选择登录认证，填写登录认证配置

image-20250409112131234

配置释义：

  1. App ID：飞书appId配置

  2. App Secret：飞书secret配置

  3. 重定向URI：PC端飞书认证后的回调地址，就是AFCenter的前端地址

  4. 移动端重定向URI：移动端飞书认证后的回调地址，就是移动端AFCenter的前端地址

  5. 权限范围：飞书集成权限信息包含用户信息权限及消息发送权限，如果有其他改造需求只需在此添加相应权限按空格隔开contact:contact.base:readonly contact:user.base:readonly contact:user.phone:readonly contact:user.id:readonly contact:user.employee_id:readonly im:message im:message:send_as_bot im:message:send_multi_users

  6. 飞书如果要使用发消息的功能，还需要在对应的飞书应用中添加机器人功能，并搭配上述scope中的所有权限

  7. 飞书中配置afc移动端首页时需要增加type=feishu参数，例如：http://localhost:81/#/login?type=feishu

# 集成申石（IDMesh）

公共说明参考集成企业微信。

1、选择连接器中的SSO配置

image-20250409150520669

2、新建认证配置，类型选择idmesh

image-20250409150642389

配置释义：

  1. App ID：申石appId

  2. App Secret：申石appSecret

  3. 申石服务地址：申石应用配置地址从申石应用管理页面获取

  4. 重定向URI：申石认证后的回调地址只需要修改端口和域名

  5. 在申石的应用管理-认证配置种需要开启OAuth2.0认证方式，同时配置授权范围如下图，否则无法集成成功

    image-20240606145031633

  6. 是否默认：配置多个sso配置时，默认使用的(默认设置必须是启用状态)

← 提供OAuth2服务 →