# E10 认证接入 ecode 二开方案

> 来源:`docs/E10认证接入二开方案.doc`(WPS 文档,17 页)
> 作者:吴琦 | 主题:E10 自定义接口登录开发案例
> 提取日期:2026-06-23 | 提取方式:macOS `textutil -convert txt`

## 目录

1. [文档版本控制](#文档版本控制)
2. [一、概述](#一概述)
3. [1.1 认证接入 ecode 二开方案说明](#11-认证接入-ecode-二开方案说明)
4. [1.2 认证接入 ecode 二开方案时序图](#12-认证接入-ecode-二开方案时序图)
5. [二、ecode 本地开发环境搭建](#二ecode-本地开发环境搭建)
6. [2.1 项目模板下载](#21-项目模板下载)
7. [2.2 项目结构设置](#22-项目结构设置)
8. [2.3 项目依赖设置](#23-项目依赖设置)
9. [三、E10 自定义认证登录接口开发示例](#三e10-自定义认证登录接口开发示例)
10. [3.1 创建包路径及单点类](#31-创建包路径及单点类)
11. [3.2 自定义接口方法作用](#32-自定义接口方法作用)
12. [3.3 自定义接口 - 接入第三方认证中心 CAS 协议认证案例](#33-自定义接口---接入第三方认证中心-cas-协议认证案例)
13. [3.4 制作 jar 包](#34-制作-jar-包)
14. [四、部署 jar 包](#四部署-jar-包)
15. [五、前端中转页二开](#五前端中转页二开)
16. [六、其他配置](#六其他配置)

## 一、概述

本文档介绍 E10 通过 ecode-gradle 项目二开自定义接口登录 E10 系统的示例。

最低基线要求:E10 `10.0.2503.01` 及以上。

### 1.1 认证接入 ecode 二开方案说明

E10 认证接入自定义认证类原二开方案需要将二开 jar 包打到 E10 标准认证服务依赖上,侵入性较强,不符合二开开发规范。新方案增加认证接入 ecode 前后端接口二开方案。

此方案包含两部分开发:

- **前端二开 ecode 认证地址**:作为认证登录入口地址和后端 ecode 认证接口中转页。认证登录时需要直接访问二开的前端 ecode 地址才能走认证登录逻辑。认证中心如果需要绑定接入端系统回调地址,应绑定前端 ecode 接口地址,不是后端地址。
- **后端二开 ecode 认证地址**:与第三方认证中心接口地址直接请求交互。比如前端 ecode 认证地址从认证中心回调拿到授权码,传给后端 ecode 认证接口,后端用授权码请求第三方认证中心 token 接口获取 token 和用户信息,最终完成认证登录。

### 1.2 认证接入 ecode 二开方案时序图

> 原文档此处为时序图,提取时无法保留,需查阅原文图片。

## 二、ecode 本地开发环境搭建

E10、ecode 后端自定义接口本地二开项目可以使用认证登录二开项目模板。二开项目文件附件地址:<https://www.e-cology.com.cn/sp/doc/docDetail/2000913662777997088>

### 2.1 项目模板下载

1. 下载二开项目模板,解压到本地目录。
2. 使用 IDEA 打开该模板项目。

> 该模板项目需要 IDEA 安装 Gradle 插件。没有 Gradle 插件,开发完成后无法打包 jar。

### 2.2 项目结构设置

项目打开后,对项目结构进行设置:

1. 设置 JDK 为 Java 1.8。
2. 设置源码路径和测试文件夹路径。

### 2.3 项目依赖设置

引入 E10 环境 jar 包依赖:

1. 设置项目下的 `secDevLib` 文件夹为项目 jar 来源库。
2. 到二开服务 `weaver-secondev-service/webapps/ROOT/WEB-INF/lib`,将整个文件夹的 jar 包文件打包导入 `secDevLib`。

完成后即可开始自定义认证登录接口开发。

## 三、E10 自定义认证登录接口开发示例

### 3.1 创建包路径及单点类

在项目 `src/main/java/` 下新建对应开发目录和自定义接口类,可参考附件 demo。

### 3.2 自定义接口方法作用

**认证登录方法 `AuthSso()`**:

- 接收认证票据。
- 执行认证授权逻辑。
- 获取认证端用户信息。
- 默认路由:`/papi/secondev/auth/sso/login`(可根据自定义调整)。

**认证配置属性项**:

查看 `SecondAuthConfig` 类,可参考示例自定义需要用到的配置项。

登录账号规则的账号匹配规则:

| 值 | 匹配规则 |
| --- | --- |
| 1 | 登录名,默认 |
| 3 | 人员 ID |
| 4 | 人员编号 |
| 5 | 电子邮箱 |
| 6 | 手机号码 |

**认证退出方法 `AuthSsoLogout()`**:

- E10 服务退出调用。
- 可自定义认证登录后的退出逻辑。
- 默认路由:`/papi/secondev/auth/sso/logout`(可根据自定义调整)。

### 3.3 自定义接口 - 接入第三方认证中心 CAS 协议认证案例

> 原文档此处为示例图片/嵌入对象,提取时无法保留,需查阅原文图片或附件 demo。

### 3.4 制作 jar 包

开发完成后,在 IDEA 中执行 Gradle build,将项目打成 jar 包。

## 四、部署 jar 包

1. 主团队管理员访问 `/ecode/monitor/loom/deploy/jar`,服务节点选择二开服务 `weaver-secondev-service`,检测服务状态。
2. 点击上传,选择刚才本地 build 好的 jar 包。
3. 1101 基线及以上,且运维平台版本 `V5.0.9.920241128-RC` 及以上,增加二开 jar 包上传校验功能。参考:<https://weapp.eteams.cn/build/techdoc/wdoc/index.html> 二开 jar 包上传校验功能文档。
4. 上传 jar 后进入运维平台重启二开服务。

## 五、前端中转页二开

前端中转页通过 ecode 二开,可导入前端二开示例包并在其基础上开发。

### 5.1 前端二开示例包导入

注意:通过 ecode 开发中转页会加载较多静态资源,访问速度会有一定影响。如果客户对性能要求较高:

1. 如不依赖三方 JS SDK,前端中转页不是必须的,可以直接配置后端接口。
2. 如依赖三方 JS SDK 必须经过前端中转,可以通过静态 HTML 文件开发,开发后把 HTML 文件放置到服务器中,通过对应路径访问。

导入步骤:

1. 进入 E10 ecode,访问 OA 域名 + `/ecode/project`。
2. 新建项目,输入名称。如果已存在项目,可忽略。
3. 导入二开包。
4. 使用主租户账号发布为公共应用。

### 5.2 二开包开发说明

中转页二开包发布后,访问 `E10 域名 + /sp/custom/intbssso/freepass`,即可看到 loading 效果。

功能地址:

```text
PC: /sp/custom/intbssso/freepass
Mobile: /mobile/custom/intbssso/freepass
```

入参:

- `ticket`:登录凭证。
- `gopage`:登录后跳转地址。如不传,跳转根目录。

核心实现在 `ssoCore()` 方法中:

```js
const ssoCore = () => {
  const { ticket } = urlParams;
  return new Promise(async (rs, rj) => {
    const data = await request({
      method: 'get',
      url: '/papi/secondev/auth/sso',
      data: {
        ticket
      }
    })
    rs(!!data.data)
  })
}
```

Ecode 开发文档参考:<https://www.e-cology.com.cn/ecode/playground/doc/share/view/916733818655342593>

## 六、其他配置

### 组合环境

在 nacos `weaver-common-cas-core.properties` 添加:

```properties
weaver.cas.base.custom.config=JSON字符串
```

配置后重启 base 服务。

### 单体环境

修改服务器文件:

```text
e10-server0/E10/webapps/ROOT/WEB-INF/classes/weaver/config/config-center/weaver-common-cas-core.properties
```

添加:

```properties
weaver.cas.base.custom.config=JSON字符串
```

修改后重启服务。

### 统一认证配置参数

250601 基线后支持。全资源拦截配置后,访问 OA 任意页面都会拦截到二开 ecode 页面。

注意:前端 ecode 地址路由必须包含 `freepass`,才能被当做免登接口拦截。

配置示意:

```js
weaver.cas.base.custom.config = {
  "weappLogoutRedirectConfig": [{
    "condition": "window.TEAMS&&window.TEAMS.currentUser&&window.location.href.indexOf('wea_link_keep_intunifyauth_client=freepass')===-1",
    "cusurl": "'e10地址/papi/secondev/auth/sso/logout'"
  }, {
    "condition": "!(window.TEAMS&&window.TEAMS.currentUser)&&window.location.href.indexOf('wea_link_keep_intunifyauth_client=freepass')===-1",
    "cusurl": "'e10地址/sp/custom/intbssso/freepass?oaAddress='+encodeURIComponent(window.location.href)"
  }]
}
```

说明:

- 第一个 `cusurl` 配二开的认证统一登出地址。
- 第二个 `cusurl` 配二开的认证全拦截登录地址,即二开 ecode 认证前端回调地址。
- 录入 nacos 前先在浏览器控制台验证配置合法性,避免 JSON 字符串错误。

常见问题:

1. 开启全拦截后,如何认证登录后跳回登录前页面?
   - 登录地址携带 `oaAddress` 参数。前端 ecode 地址将该地址写入 localStorage,后端 ecode 地址认证登录返回后,前端直接跳转 `oaAddress`。
2. 管理员等特殊账号没有认证账号时,如何继续走 E10 标准登录页?
   - 当前请求地址添加 `?intunifyauth_client=freepass`,即可不拦截到认证登录页,直接跳标准登录页。

> 原文档含多张示意图、`INCLUDEPICTURE` 和 `EMBED`,提取时无法保留,需查阅原文 doc 文件。
