单点登录-网易企业邮箱

如何通过数犀集成平台实现与网易企业邮箱的单点登录集成，实现从集成平台直接访问网易企业邮箱，无需重复登录。

概述

本文详细介绍如何通过数犀集成平台的自定义集成对接功能，实现与网易企业邮箱的单点登录集成。通过此配置，用户可以从数犀集成平台直接访问网易企业邮箱，无需重复登录，大幅提升用户体验和工作效率。

核心功能

无缝单点登录

用户从集成平台直接跳转访问网易企业邮箱，无需再次输入账号密码

安全凭证管理

通过 ssoAuthToken 和数字签名机制确保单点登录安全性

灵活账号匹配

支持 username 或邮箱前缀等多种方式匹配网易邮箱账号

可视化流程编排

通过图形化流程编排配置单点登录逻辑

快速入门

步骤 1：准备工作

阅读自定义集成对接通用指引，准备网易企业邮箱参数

步骤 2：平台配置

创建应用并选择自定义集成对接协议

步骤 3：流程编排

配置 Webhook 和 HTTP 节点实现单点登录

前置条件

在开始配置之前，请先阅读自定义集成单点登录配置说明，了解：

如何判断系统是否支持自定义集成对接

需要向目标系统确认哪些关键信息

自定义集成对接的通用配置流程

本文档将基于通用指引，详细介绍网易企业邮箱的具体配置步骤。

适用对象

角色	关注点
平台管理员	配置流程、参数准备
运维工程师	故障排查、接口调试
终端用户	使用单点登录功能

单点登录场景

网易企业邮箱提供了开放平台接口，支持通过 API 调用获取单点登录凭证，然后拼接成单点登录 URL。通过数犀集成平台的自定义集成对接功能，可以：

用户在数犀集成平台输入账号密码完成身份认证

系统自动调用网易企业邮箱的 API 接口获取单点登录凭证

自动拼接生成网易企业邮箱的单点登录 URL

用户自动跳转到网易企业邮箱，无需再次登录

接口调用流程

整体流程

接口调用时序图

关键接口说明

获取单点登录辅助凭证

接口地址：POST /api/pub/token/ssoAuthToken

接口说明：获取用于单点登录的辅助凭证（ssoAuthToken），该凭证是调用单点登录签名接口的前置条件。

请求参数：

参数名称	参数说明	是否必须	数据类型
appId	应用ID，由网易企业邮箱管理后台提供	是	string
authCode	应用授权码，由网易企业邮箱管理后台提供	是	string
orgOpenId	企业OpenId，由网易企业邮箱管理后台提供	是	string

返回结果：

参数名称	参数说明	数据类型
ssoAuthToken	单点登录辅助凭证	string
ssoAuthTokenExpiredTime	单点登录辅助凭证有效期截止时间	string

返回示例：

{
  "code": 0,
  "success": true,
  "message": "",
  "data": {
    "ssoAuthToken": "PfSKtimiXoY/ePJTiw76iXUTBe9HHpVZZYfFuxaqtlC0Xv9kilLYUpEpf3D+9kRp",
    "ssoAuthTokenExpiredTime": "2025-09-22 17:11:45"
  }
}

获取单点登录签名

接口地址：POST /api/sso/ssoSign

接口说明：获取单点登录签名值和端点地址，用于拼接生成最终的单点登录 URL。

请求头参数：

参数名称	参数说明	是否必须
qiye-sso-auth-token	单点登录辅助凭证（从ssoAuthToken接口获取）	是
qiye-app-id	应用ID	是
qiye-org-open-id	企业OpenId	是

请求参数：

参数名称	参数说明	是否必须	数据类型
accountName	用户账号名，邮箱格式的前缀（如：zhangsan）	是	string
domain	企业邮箱域名（如：abc.com）	是	string
pass_2fa	是否强制跳过二次验证（默认0: 否；1:跳过二次验证）	否	integer

返回结果：

参数名称	参数说明	数据类型
sign	用于单点登录的签名值	string
endpoint	单点登录跳转URL	string

返回示例：

{
  "code": 0,
  "success": true,
  "message": "",
  "data": {
    "sign": "a3a2660f296a4aa28bd39adacdd97131",
    "endpoint": "https://entry.qiye.163.com/login/ssoLogin"
  }
}

拼接单点登录URL

URL格式：

{endpoint}?sso_token={sign}&language=0

参数说明：

参数名称	参数说明	示例值
endpoint	单点登录跳转URL（从ssoSign接口获取）	https://entry.qiye.163.com/login/ssoLogin
sso_token	单点登录签名值（从ssoSign接口获取的sign字段）	a3a2660f296a4aa28bd39adacdd97131
language	邮箱所使用的语言（0-简体中文，1-英文，2-繁体中文）	0

完整URL示例：

https://entry.qiye.163.com/login/ssoLogin?language=0&sso_token=a3a2660f296a4aa28bd39adacdd97131

配置流程

步骤 1：数犀集成平台应用配置

在数犀集成平台创建应用，配置基本信息、登录方式和单点协议。具体操作请参考自定义集成单点登录配置说明-数犀集成平台配置。

步骤 2：流程编排配置

在应用内配置单点登录流程，包括 Webhook 节点、HTTP 节点和流程变量节点。

步骤 3：网易企业邮箱参数准备

在网易企业邮箱管理后台创建应用授权，获取 appId、authCode、orgOpenId 等参数。

步骤 4：用户关联设置

配置集成平台用户与网易企业邮箱账号的匹配规则。

数犀集成平台配置

提示：本节仅介绍网易企业邮箱的特殊配置，通用配置步骤请参考自定义集成单点登录配置说明文档。

创建应用

在数犀集成平台创建应用，配置基本信息和登录方式。

登录配置

配置应用的基本登录信息和认证方式。

图 1：登录配置界面

单点协议选择

在单点协议选择区域，选择「自定义集成对接」选项。

图 2：单点协议选择界面

配置完成后，系统会显示「访问地址」，该地址即为单点登录的入口地址。

进入流程编排

点击「进入流程编排」按钮，进入链接流编排页面，开始配置单点登录流程。

图 3：流程编排页面

流程编排配置

提示：本节详细介绍网易企业邮箱的流程编排配置，通用流程编排说明请参考自定义集成单点登录配置说明文档。

流程节点说明

网易企业邮箱单点登录流程包含以下节点：

Webhook节点

接收用户认证后的用户信息

HTTP节点1

调用 /api/pub/token/ssoAuthToken 获取单点登录辅助凭证

HTTP节点2

调用 /api/sso/ssoSign 获取单点登录签名和端点地址

流程变量节点

拼接生成最终的单点登录URL并返回

Webhook节点配置

Webhook节点是流程的起始节点，当用户完成身份认证后，会自动触发该节点，输出用户的所有信息。

输出示例：

{
  "hook_url": "https://zhtg.digitalsee.cn/acm/flows/start/v2/1/1968229118909177858/ef4fb7bfcc924049887f6b46cb7cf340",
  "ip_list": null,
  "sync": true,
  "type": "同步",
  "value": {
    "sub": "1967844592178065409",
    "id_card": "236746387234756384",
    "name": "王二喜",
    "phone_number": "+86-18900001002",
    "user_job_number": "g-18900001002",
    "email": "18900001002@163.com",
    "username": "wangerxi"
  }
}

关键字段说明：

字段	说明	用途
value.username	用户名	可用于匹配网易企业邮箱的 accountName
value.email	用户邮箱	可用于提取域名和账号名
value.name	用户姓名	显示用
value.sub	用户唯一标识	内部关联用

HTTP节点1配置：获取ssoAuthToken

节点功能：调用网易企业邮箱的 /api/pub/token/ssoAuthToken 接口，获取单点登录辅助凭证。

请求配置：

配置项	值
请求方式	POST
请求URL	`https://api.qiye.163.com/api/pub/token/ssoAuthToken`
请求头	`Content-Type: application/json`

请求体：

{
  "appId": "客户提供的appId",
  "authCode": "客户提供的authCode",
  "orgOpenId": "客户提供的orgOpenId"
}

参数获取方式：

appId、authCode、orgOpenId 需要客户从网易企业邮箱管理后台获取

这些参数可以在流程编排中配置为固定值，或通过流程变量动态获取

响应处理：

从响应中提取 body.data.ssoAuthToken 字段

将 ssoAuthToken 保存为流程变量，供后续节点使用

提示：这些参数建议在流程编排中配置为固定值，便于后续维护。

HTTP节点2配置：获取ssoSign

节点功能：调用网易企业邮箱的 /api/sso/ssoSign 接口，获取单点登录签名和端点地址。

请求配置：

配置项	值
请求方式	POST
请求URL	`https://api.qiye.163.com/api/sso/ssoSign`
请求头	`Content-Type: application/json`、`qiye-sso-auth-token`、`qiye-app-id`、`qiye-org-open-id`

请求头参数说明：

参数名称	说明
qiye-sso-auth-token	从HTTP节点1获取的ssoAuthToken
qiye-app-id	客户提供的appId
qiye-org-open-id	客户提供的orgOpenId

请求体：

{
  "accountName": "{从Webhook节点获取的用户名，需要与网易邮箱账号匹配}",
  "domain": "客户提供的企业邮箱域名",
  "pass_2fa": 0
}

关键参数说明：

参数名称	说明	填写建议
accountName	必须与网易企业邮箱中的账号名匹配	可通过链接流能力从Webhook节点输出中获取（如 `value.username` 或从 `value.email` 中提取）
domain	企业邮箱域名，由客户提供	如 `abc.com`
pass_2fa	是否跳过二次验证	默认0（不跳过）

重要：accountName 是集成平台与网易邮箱能够匹配上的唯一字段，必须确保与网易企业邮箱中的实际账号名完全匹配。

响应处理：

从响应中提取 body.data.sign 字段（单点登录签名值）

从响应中提取 body.data.endpoint 字段（单点登录端点地址）

将这两个字段保存为流程变量，供后续节点使用

流程变量节点配置：拼接URL

节点功能：将获取到的 endpoint 和 sign 拼接成最终的单点登录 URL。

URL拼接格式：

{endpoint}?sso_token={sign}&language=0

配置示例：

参数	来源	说明
endpoint	HTTP节点2响应 `body.data.endpoint`	单点登录端点地址
sign	HTTP节点2响应 `body.data.sign`	单点登录签名值
language	固定值 `0`	简体中文

返回结果：

流程变量节点需要返回一个包含 url 字段的 JSON 对象：

{
  "url": "https://entry.qiye.163.com/login/ssoLogin?language=0&sso_token=a3a2660f296a4aa28bd39adacdd97131"
}

流程连接

按照以下顺序连接各个节点：

确保每个节点的输出能够正确传递给下一个节点。

网易企业邮箱参数准备

开通集成接口

步骤 1：申请开通

使用网易企业邮箱管理员 admin 邮箱发送邮件至 kf@office.163.com 申请开通集成接口功能

步骤 2：确认开通

等待网易官方客服邮件回复，确认已开通管理后台接口配置界面

步骤 3：登录后台

登录网易企业邮箱管理后台（https://qy.163.com/login/）

新建应用授权

登录管理后台，导航至「应用中心」→「应用接入管理」

点击「新建应用授权」

填写应用信息：

配置项	说明
应用名称	可按需填写
IP白名单	填写数犀集成平台访问网易接口的服务器出口公网IP（如仅开通单点登录访问，可设置为127.0.0.1）
应用状态	启用

获取接口参数

新建应用授权完成后，从管理后台获取以下参数：

参数名称	参数说明	获取路径
appId	应用ID	管理后台 → 应用中心 → 应用接入管理
authCode	应用授权码	管理后台 → 应用中心 → 应用接入管理
orgOpenId	企业OpenId	管理后台 → 企业设置 → 企业信息
domain	企业邮箱域名	企业邮箱域名信息

重要：这些参数需要在流程编排的 HTTP 节点中配置使用。

用户关联配置

提示：通用用户关联配置说明请参考自定义集成单点登录配置说明文档。

账号匹配规则

网易企业邮箱单点登录需要确保集成平台的用户账号与网易企业邮箱的账号能够正确匹配。

匹配字段：

来源	字段	说明
集成平台	username 或 email 前缀	用户信息中的 username 或从 email 中提取的账号前缀
网易企业邮箱	accountName	邮箱格式的前缀（如：zhangsan@abc.com 中的 zhangsan）

匹配要求：

用户信息映射

在流程编排中，需要正确配置用户信息的映射：

如果集成平台用户信息中的 username 字段与网易邮箱的 accountName 一致，可直接使用

如果使用邮箱地址，需要从 email 字段中提取账号前缀部分（@符号前的部分）

确保提取的账号名与网易企业邮箱中的实际账号名完全匹配

验证效果

配置完成后，用户访问应用的单点登录地址，输入账号密码完成身份认证后，系统将自动执行以下流程：

Webhook节点输出用户信息

调用网易企业邮箱接口获取单点登录凭证

拼接生成单点登录 URL

自动跳转到网易企业邮箱，用户无需再次登录

图 12：验证效果-登录界面

用户将直接进入网易企业邮箱的主页，实现无缝的单点登录体验。

图 13：验证效果-跳转成功

常见问题与排障

提示：通用问题排查请参考自定义集成单点登录配置说明文档。

Q：单点登录失败常见原因有哪些？

Q：配置时需要注意什么？

Q：接口错误码如何解读？

附录

接口参数对照表

数犀集成平台	网易企业邮箱	说明
Webhook输出 value.username	accountName	用户账号名，用于匹配
Webhook输出 value.email	-	用户邮箱，可用于提取账号名和域名
HTTP节点1返回 ssoAuthToken	qiye-sso-auth-token	单点登录辅助凭证
HTTP节点2返回 sign	sso_token	单点登录签名值
HTTP节点2返回 endpoint	endpoint	单点登录端点地址

术语解释

术语	说明
ssoAuthToken	单点登录辅助凭证，用于调用单点登录签名接口
accountName	用户账号名，邮箱格式的前缀部分，是集成平台与网易邮箱匹配的唯一字段
endpoint	单点登录跳转URL，由网易企业邮箱接口返回
sign	单点登录签名值，用于验证URL提交方的身份

参考文档

自定义集成单点登录配置说明

网易企业邮箱对外开放平台技术白皮书V1.12

概述#

核心功能#

快速入门#

前置条件#

适用对象#

单点登录场景#

接口调用流程#

整体流程#

接口调用时序图#

关键接口说明#

获取单点登录辅助凭证#

获取单点登录签名#

拼接单点登录URL#

配置流程#

数犀集成平台配置#

创建应用#

登录配置#

单点协议选择#

进入流程编排#

流程编排配置#

流程节点说明#

Webhook节点配置#

HTTP节点1配置：获取ssoAuthToken#

HTTP节点2配置：获取ssoSign#

流程变量节点配置：拼接URL#

流程连接#

网易企业邮箱参数准备#

开通集成接口#

新建应用授权#

获取接口参数#

用户关联配置#

账号匹配规则#

用户信息映射#

验证效果#

常见问题与排障#

附录#

接口参数对照表#

术语解释#

参考文档#

相关文档#

概述

核心功能

快速入门

前置条件

适用对象

单点登录场景

接口调用流程

整体流程

接口调用时序图

关键接口说明

获取单点登录辅助凭证

获取单点登录签名

拼接单点登录URL

配置流程

数犀集成平台配置

创建应用

登录配置

单点协议选择

进入流程编排

流程编排配置

流程节点说明

Webhook节点配置

HTTP节点1配置：获取ssoAuthToken

HTTP节点2配置：获取ssoSign

流程变量节点配置：拼接URL

流程连接

网易企业邮箱参数准备

开通集成接口

新建应用授权

获取接口参数

用户关联配置

账号匹配规则

用户信息映射

验证效果

常见问题与排障

附录

接口参数对照表

术语解释

参考文档

相关文档