网易企业邮箱集成接口技术白皮书v111HZ.docx
- 文档编号:6261508
- 上传时间:2023-01-04
- 格式:DOCX
- 页数:19
- 大小:213.78KB
网易企业邮箱集成接口技术白皮书v111HZ.docx
《网易企业邮箱集成接口技术白皮书v111HZ.docx》由会员分享,可在线阅读,更多相关《网易企业邮箱集成接口技术白皮书v111HZ.docx(19页珍藏版)》请在冰豆网上搜索。
网易企业邮箱集成接口技术白皮书v111HZ
网易企业邮箱
集成接口技术白皮书
稳定可靠,安全无忧
V1.1.HZ
修订历史记录
版本
日期
修订说明
编制
审核
0.1
2012-4-28
文档第一版,完成部门帐号同步接口、单点登录接口、未读邮件数量接口和添加自定义登录框
湛舜研
0.2
2012-5-9
完成文档概述和接口综述,修改各接口介绍中的文字错误
徐亭
湛舜研
1.0
2012-5-14
修改2.6申请流程,修改6.2接口规范,强调域名一致与域名值为客服提供的代码串
徐亭
湛舜研
1.1
修改1.3术语解析:
RSA算法,增加URL
湛舜研
目录
1关于文档1
1.1目标1
1.2读者1
1.3术语定义1
1.4如何获得帮助1
2接口综述2
2.1目标2
2.2功能概述2
2.3总体架构2
2.4前提条件3
2.5应用步骤3
2.6申请流程4
3部门帐号同步接口5
3.1接口说明5
3.2接口规范5
3.2.1技术规范5
3.2.2使用规范5
3.3加密参数说明(enc值)6
3.3.1操作说明(action值)6
3.3.2操作参数说明8
3.3.3URL示例9
3.3.4操作示例10
3.4应用示例11
4单点登录接口12
4.1接口说明12
4.2接口规范12
4.2.1技术规范12
4.2.2使用规范12
4.3应用示例13
5未读邮件数量接口14
5.1接口说明14
5.2接口规范14
5.2.1技术规范14
5.2.2使用规范14
5.3应用示例15
6自定义登录框接口16
6.1接口说明16
6.2接口规范16
6.2.1技术规范16
6.2.2数据规范16
6.2.3注意事项17
6.3应用示例17
关于文档
目标
这份文档帮助客户或经销商详细了解网易企业邮箱接口集成的具体功能和操作方法。
读者
这份文档的预期读者为客户IT相关负责人、经销商客服和技术支持人员。
术语解析
●HTTP协议
超文本传输协议(HTTP)是一种通信协议,它允许将超文本标记语言(HTML)文档从web服务器传送到Web浏览器。
●URL
统一资源定位符(URL,英语UniformResourceLocator的缩写)也被称为网页地址,是因特网上标准的资源的地址。
统一资源定位符URL是对可以从因特网上得到的资源的位置和访问方法的一种简洁的表示。
●RSA加密算法
RSA加密算法是是目前最有影响力的公开密钥密码体制加密算法,它能够抵抗到目前为止已知的所有密码攻击,已被ISO推荐为公钥数据加密标准,从提出到现在的三十多年里,经历了各种攻击的考验,逐渐为人们接受,普遍认为是目前最优秀的公钥方案之一。
如何获得帮助
如对文档有任何疑问,欢迎致电400-6281-163或发邮件kf@进行咨询并作深入的了解。
接口综述
目标
网易企业邮箱拥有多个集成接口供客户使用,并能与其他业务系统进行集成。
功能概述
网易企业邮箱提供多种集成接口与客户应用系统进行无缝集成,可实现与用户应用系统中组织架构同步和未读邮件数同步,并且可以在用户应用系统或者用户网站登录首页实现单点登录或者嵌入自定义登录的入口,解决了网易企业邮箱系统与客户应用系统的集成数据共享问题。
采用公私钥加密技术和服务请求IP地址过滤等方案保障数据交互接口的安全。
总体架构
前提条件
接口类型
前提条件
部门账号同步
系统的可扩展性、有固定的登录IP
单点登录
系统的可扩展性
未读邮件数
系统的可扩展性、有固定的登录IP
自定义登录
从企业域名对应的网站或系统登录
应用步骤
1.引用RSA工具包:
RSA-1.1.1.jar
2.生成密钥:
ease.domainmail.Utils.createKeyPair();执行结果如下:
GeneratingapairofRSAkey...
pubKey:
30819f300d06092a864886f70d010101050003818d003081890281810085802e30d10d33197354c6c2d0785526ff17b4741048745f17e8e91cb38c70dd60e9bce1bf9b73d9215ccb56ad68c5efcf3d7f62677cd685cb1664601b57f1535138ea1e60a……
priKey:
30820276020100300d06092a864886f70d0101010500048202603082025c0201000281810085802e30d10d33197354c6c2d0785526ff17b4741048745f17e8e91cb38c70dd60e9bce1bf9b73d9215ccb56ad68c5efcf3d7f62677cd685cb1664601b57f1535138ea1e60a42e8ccbb813ba8f7c91d27fcfde305cd1edc04a5aa26afba8e04c87c786113c2616f2fb8b6f5b9e0c55fb141eb96ae7426d35fbe9de581fccb621020……
1024-bitRSAkeyGENERATED.
3.把公钥和IP地址告诉接口提供方进行授权。
(注:
单点登录接口不需要限定IP,可以不提供)
4.生成操作参数(原始字符串)。
5.参数加密:
ease.domainmail.Utils.encrypt(StringpriKey,Stringsource);其中,priKey是私钥,source是原始字符串,返回加密后的字符串。
6.组装完整URL请求地址。
7.发送POST请求。
8.返回操作结果。
申请流程
注:
上述流程图中红色字体部分的是客户申请需提供的资料
部门帐号同步接口
接口说明
部门帐号同步接口通过HTTP协议访问接口并提交同步指令,支持创建、更新和删除部门或子部门,创建、禁用、删除和恢复用户,修改帐号密码和属性。
接口规范
技术规范
1.客户按网易企业邮箱提供的算法(标准RSA算法,1024位密钥长度)生成公私钥,将公钥提供给网易企业邮箱,私钥自行妥善保管,通过接口提交URL链接参数必须使用RSA私钥加密,禁止明文传输。
国内银行的网银通讯也是采用此类加密传输方式,可以有效防止数据被盗用或篡改,给予用户数据安全保护的最高级别。
2.客户还需要提供访问接口的服务器IP地址。
网易企业邮箱会对IP地址进行服务授权,进一步增强接口的安全性。
3.接口仅支持HTTP协议,使用POST方法访问。
使用规范
1.POST请求到URL:
2.*:
真实URL中替换为实际操作要填入的参数值。
3.cid:
用于标识企业,由网易企业邮箱分配提供,实际用的是orgid。
4.enc:
加密操作参数。
a)enc的第一个参数固定为action,表示要执行的操作。
b)后面的参数是action操作参数,参数之间用“&”分隔。
5.参数值使用URLEncoder.encode(String,"utf-8")编码,以保证不存在特殊字符干扰参数值的解析。
6.返回值采用code+文字说明的方式。
如:
200\r\n:
操作成功;500\r\n:
操作失败;4**\r\n:
没有权限。
加密参数说明(enc值)
操作说明(action值)
操作名
操作说明
操作参数
参数属性
备注
createOrg
创建部门
ouid
必填录入项
org_unit_name
必填录入项
parent_org_unit_id
选填
匹配项录入项
创建下级部门时使用
updateOrg
更新部门
ouid
必填匹配项
org_unit_name
选填录入项
更新部门名称
u_desc
选填录入项
更新部门描述
deleteOrg
删除部门
ouid
必填匹配项
要求该部门下没有邮箱帐号
createUser
创建帐号
account_name
必填录入项
nickname
必填录入项
password
必填录入项
department
选填
匹配项录入项
job_no
选填录入项
exp_time
选填录入项
address_right
选填录入项
privacy_level
选填录入项
updateUser
更新帐号
account_name
必填匹配项
nickname
选填录入项
更新姓名
department
选填
匹配项录入项
更新所属部门
status
选填录入项
禁用/恢复帐号
job_no
选填录入项
更新工号
exp_time
选填录入项
更新过期时间
address_right
选填录入项
可否使用企业通讯录
privacy_level
选填录入项
是否在企业通讯录显示
delta_quota
选填录入项
分配额外容量
deleteUser
删除帐号
account_name
必填匹配项
禁用帐号7天,7天后彻底删除
recoverUser
恢复帐号
account_name
必填匹配项
删除帐号7天内可以恢复
updateUserPwd
更新帐号密码
account_name
必填匹配项
password
必填录入项
需确保用户记住新改的密码
注意:
●操作名区分大小写!
●参数属性为“匹配项”,参数值必须匹配数据库中已有数据,否则操作失败,POST返回值为500。
参数属性为“录入项”,参数值将存入网易企业邮箱数据库。
操作参数说明
参数名
类型
名称
说明
部门参数
ouid
String
部门ID
部门唯一标识,由企业通过接口创建部门时建立,并要求记录好部门与ouid之间的对应关系
parent_org_unit_id
String
父级部门ID
标识部门在组织架构所处位置
org_unit_name
String
部门名称
同一级的部门名称不允许重复
u_desc
String
部门描述
添加部门文字介绍和简单描述
帐号参数
account_name
String
邮箱帐号
邮箱帐号作为邮箱地址前缀,邮箱用户的唯一标识,企业内同一域内不可重复
nickname
String
姓名
用户的姓名显示于企业通讯录
password
String
密码
帐号的登录密码
department
String
所属部门ID
使用部门参数的ouid
status
int
状态
0表示正常,1表示禁用
job_no
String
工号
用户的工号信息
exp_time
Date
过期时间
格式:
yyyy-MM-dd
address_right
int
能否使用企业通讯录
0不能,1可以(默认)
privacy_level
int
是否在企业通讯录显示
0不显示,2显示(默认)
delta_quota
int
额外的空间
需申请开通容量自主分配功能
URL示例
以创建用户为例:
(公司的cid为abc123)
原始参数:
action=createUser&account_name=zs&nickname=张三&department=dept_1&password=1qaz2wsx
RSA加密后参数:
1da01df7b4486978df8624b0e6c9122c4fdd74ff435b096c5b36df26a0c38947a409cc329bef750a28e5aac5c79d3e8ccdee46d59623ed5d45dc696cf7068741980c4e1c1745af599103af74e796ee5ca158866b9301fcfe06060c3cfdfa0c2ae326352cf5ba1800d1cca881da60dc02c69c897477295dc09b336e561f3b52eb020e5e29f70b58935b3c7cd4eda62c3f602a0de39e35741803bbe5b9b0c2e058c36f403fbd5aec361fcb3feacdef4e03110a3963003a98f7547e224791682bfd82b469968ec895abe3bc6bd02bad57095fc7a29dab097a1f38dd4f9102a9644150fac41d3bdd2ff92f0179fef63ce4b0f9074f53554cc087e52e288585269039
完整的请求地址:
接口解析之后的地址(即原始请求):
dept_1&password=1qaz2wsx
操作示例
1.创建部门
2.更新部门
ABC销售事业部
3.创建子部门
4.删除部门
5.创建用户
dept_1&password=1qaz2wsx
6.修改用户属性
7.删除用户
8.恢复用户
9.修改用户密码
注意:
红色部分需要RSA加密
应用示例
以创建用户为例(假设客户域名为,cid值为abc123):
原始参数:
action=createUser&account_name=zs&nickname=张三&department=dept_1&password=1qaz2wsx
RSA加密后参数:
1da01df7b4486978df8624b0e6c9122c4fdd74ff435b096c5b36df26a0c38947a409cc329bef750a28e5aac5c79d3e8ccdee46d59623ed5d45dc696cf7068741980c4e1c1745af599103af74e796ee5ca158866b9301fcfe06060c3cfdfa0c2ae326352cf5ba1800d1cca881da60dc02c69c897477295dc09b336e561f3b52eb020e5e29f70b58935b3c7cd4eda62c3f602a0de39e35741803bbe5b9b0c2e058c36f403fbd5aec361fcb3feacdef4e03110a3963003a98f7547e224791682bfd82b469968ec895abe3bc6bd02bad57095fc7a29dab097a1f38dd4f9102a9644150fac41d3bdd2ff92f0179fef63ce4b0f9074f53554cc087e52e288585269039
完整的请求地址:
接口解析之后的地址(即原始请求):
dept_1&password=1qaz2wsx
单点登录接口
接口说明
采用RSA加密算法的HTTP协议接口,客户提交邮箱帐号及加密信息,网易企业邮箱解密验证通过后,给予浏览器页面自动跳转登录访问邮箱。
接口规范
技术规范
1.客户按网易企业邮箱提供的算法(标准RSA算法,1024位密钥长度)生成公私钥,将公钥提供给网易企业邮箱,私钥自行妥善保管。
通过接口提交URL参数必须使用RSA私钥进行摘要签名,以确保URL请求能验证通过。
2.接口使用HTTPS协议,每个请求URL只有一次请求有效,每个URL生成后5分钟内有效。
使用规范
1.POST或GET请求到URL:
2.*:
真实URL中替换为实际操作要填入的参数值。
3.domain:
企业邮箱注册域名,用于标识客户。
4.account_name:
需要单点登录的邮箱帐号。
5.time:
生成URL的服务器当前时间(单位ms,至现在所经过的UTC毫秒数)。
6.lang:
单点登录后邮箱页面使用的语言版本,此参数可以不填,默认为中文。
7.enc:
加密串用于验证URL提交方的身份。
Enc的参数原文为account_name、domain、time三个参数值按顺序连起来,中间不要任何符号间隔。
8.参数值使用URLEncoder.encode(String,"utf-8")编码,以保证不存在特殊字符干扰参数值的解析。
9.返回值采用code+文字说明的方式。
如:
200\r\n:
操作成功;500\r\n:
操作失败;4**\r\n:
没有权限。
应用示例
<%@pagecontentType="text/h
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 网易 企业邮箱 集成 接口 技术 白皮书 v111HZ