网易企业邮箱集成接口技术白皮书v111HZ.docx

资源描述

网易企业邮箱集成接口技术白皮书v111HZ.docx

《网易企业邮箱集成接口技术白皮书v111HZ.docx》由会员分享，可在线阅读，更多相关《网易企业邮箱集成接口技术白皮书v111HZ.docx（19页珍藏版）》请在冰豆网上搜索。

网易企业邮箱集成接口技术白皮书v111HZ.docx

网易企业邮箱集成接口技术白皮书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加密后参数：

完整的请求地址：

接口解析之后的地址（即原始请求）：

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

展开阅读全文