网易企业邮箱集成接口技术白皮书v1[1].1.HZ.doc

集成接口技术白皮书网易企业邮箱集成接口技术白皮书稳定可靠，安全无忧V1.1.HZ网址：/ 热线：400-6281-163 第11页修订历史记录版本日期修订说明编制审核0.12012-4-28文档第一版，完成部门帐号同步接口、单点登录接口、未读邮件数量接口和添加自定义登录框湛舜研0.22012-5-9完成文档概述和接口综述，修改各接口介绍中的文字错误徐亭湛舜研1.02012-5-14修改2.6申请流程，修改6.2 接口规范，强调域名一致与域名值为客服提供的代码串徐亭湛舜研1.1修改1.3术语解析：RSA算法，增加URL湛舜研目 录1关于文档11.1目标11.2读者11.3术语定义11.4如何获得帮助12接口综述22.1目标22.2功能概述22.3总体架构22.4前提条件32.5应用步骤32.6申请流程43部门帐号同步接口53.1接口说明53.2接口规范53.2.1技术规范53.2.2使用规范53.3加密参数说明（enc值）63.3.1操作说明（action值）63.3.2操作参数说明83.3.3URL示例93.3.4操作示例103.4应用示例114单点登录接口124.1接口说明124.2接口规范124.2.1技术规范124.2.2使用规范124.3应用示例135未读邮件数量接口145.1接口说明145.2接口规范145.2.1技术规范145.2.2使用规范145.3应用示例156自定义登录框接口166.1接口说明166.2接口规范166.2.1技术规范166.2.2数据规范166.2.3注意事项176.3应用示例171 关于文档1.1 目标这份文档帮助客户或经销商详细了解网易企业邮箱接口集成的具体功能和操作方法。1.2 读者这份文档的预期读者为客户IT相关负责人、经销商客服和技术支持人员。1.3 术语解析l HTTP协议超文本传输协议(HTTP)是一种通信协议，它允许将超文本标记语言(HTML)文档从web服务器传送到Web浏览器。l URL统一资源定位符（URL，英语UniformResourceLocator的缩写）也被称为网页地址，是因特网上标准的资源的地址。统一资源定位符 URL 是对可以从因特网上得到的资源的位置和访问方法的一种简洁的表示。l RSA加密算法RSA加密算法是是目前最有影响力的公开密钥密码体制加密算法，它能够抵抗到目前为止已知的所有密码攻击，已被ISO推荐为公钥数据加密标准，从提出到现在的三十多年里，经历了各种攻击的考验，逐渐为人们接受，普遍认为是目前最优秀的公钥方案之一。1.4 如何获得帮助如对文档有任何疑问，欢迎致电 400-6281-163 或发邮件 进行咨询并作深入的了解。2 接口综述2.1 目标网易企业邮箱拥有多个集成接口供客户使用，并能与其他业务系统进行集成。2.2 功能概述网易企业邮箱提供多种集成接口与客户应用系统进行无缝集成，可实现与用户应用系统中组织架构同步和未读邮件数同步，并且可以在用户应用系统或者用户网站登录首页实现单点登录或者嵌入自定义登录的入口，解决了网易企业邮箱系统与客户应用系统的集成数据共享问题。采用公私钥加密技术和服务请求IP地址过滤等方案保障数据交互接口的安全。2.3 总体架构2.4 前提条件接口类型前提条件部门账号同步系统的可扩展性、有固定的登录IP单点登录系统的可扩展性未读邮件数系统的可扩展性、有固定的登录IP自定义登录从企业域名对应的网站或系统登录2.5 应用步骤1. 引用RSA工具包：RSA-1.1.1.jar2. 生成密钥：ease.domainmail.Utils.createKeyPair(); 执行结果如下：Generating a pair of RSA key . pubKey:30819f300d06092a864886f70d010101050003818d003081890281810085802e30d10d33197354c6c2d0785526ff17b4741048745f17e8e91cb38c70dd60e9bce1bf9b73d9215ccb56ad68c5efcf3d7f62677cd685cb1664601b57f1535138ea1e60apriKey:30820276020100300d06092a864886f70d0101010500048202603082025c0201000281810085802e30d10d33197354c6c2d0785526ff17b4741048745f17e8e91cb38c70dd60e9bce1bf9b73d9215ccb56ad68c5efcf3d7f62677cd685cb1664601b57f1535138ea1e60a42e8ccbb813ba8f7c91d27fcfde305cd1edc04a5aa26afba8e04c87c786113c2616f2fb8b6f5b9e0c55fb141eb96ae7426d35fbe9de581fccb6210201024-bit RSA key GENERATED.3. 把公钥和IP地址告诉接口提供方进行授权。(注：单点登录接口不需要限定IP，可以不提供)4. 生成操作参数（原始字符串）。5. 参数加密：ease.domainmail.Utils.encrypt(String priKey, String source);其中，priKey是私钥，source是原始字符串，返回加密后的字符串。6. 组装完整URL请求地址。7. 发送POST请求。8. 返回操作结果。2.6 申请流程注：上述流程图中红色字体部分的是客户申请需提供的资料 3 部门帐号同步接口3.1 接口说明部门帐号同步接口通过HTTP协议访问接口并提交同步指令，支持创建、更新和删除部门或子部门，创建、禁用、删除和恢复用户，修改帐号密码和属性。3.2 接口规范3.2.1 技术规范1. 客户按网易企业邮箱提供的算法（标准RSA算法，1024位密钥长度）生成公私钥，将公钥提供给网易企业邮箱，私钥自行妥善保管，通过接口提交URL链接参数必须使用RSA私钥加密，禁止明文传输。国内银行的网银通讯也是采用此类加密传输方式，可以有效防止数据被盗用或篡改，给予用户数据安全保护的最高级别。2. 客户还需要提供访问接口的服务器IP地址。网易企业邮箱会对IP地址进行服务授权，进一步增强接口的安全性。3. 接口仅支持HTTP协议，使用POST方法访问。3.2.2 使用规范1. POST请求到URL： /domain/services/externalApi?cid=*&enc=*2. *： 真实URL中替换为实际操作要填入的参数值。3. cid：用于标识企业，由网易企业邮箱分配提供，实际用的是orgid。4. enc：加密操作参数。a) enc的第一个参数固定为action，表示要执行的操作。b) 后面的参数是action操作参数，参数之间用“&”分隔。5. 参数值使用URLEncoder.encode(String,utf-8)编码，以保证不存在特殊字符干扰参数值的解析。6. 返回值采用code+文字说明的方式。如：200rn：操作成功；500rn：操作失败；4*rn：没有权限。3.3 加密参数说明（enc值）3.3.1 操作说明（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必填 录入项需确保用户记住新改的密码注意：l 操作名区分大小写！l 参数属性为“匹配项”，参数值必须匹配数据库中已有数据，否则操作失败，POST返回值为500。参数属性为“录入项”，参数值将存入网易企业邮箱数据库。3.3.2 操作参数说明参数名类型名称说明部门参数ouidString部门ID部门唯一标识，由企业通过接口创建部门时建立，并要求记录好部门与ouid之间的对应关系parent_org_unit_idString父级部门ID标识部门在组织架构所处位置org_unit_nameString部门名称同一级的部门名称不允许重复u_descString部门描述添加部门文字介绍和简单描述帐号参数account_nameString邮箱帐号邮箱帐号作为邮箱地址前缀，邮箱用户的唯一标识，企业内同一域内不可重复nicknameString姓名用户的姓名显示于企业通讯录passwordString密码帐号的登录密码departmentString所属部门ID使用部门参数的ouidstatusint状态0表示正常，1表示禁用job_noString工号用户的工号信息exp_timeDate过期时间格式：yyyy-MM-dd address_rightint能否使用企业通讯录0不能，1可以（默认）privacy_levelint是否在企业通讯录显示0不显示，2显示（默认）delta_quotaint额外的空间需申请开通容量自主分配功能3.3.3 URL示例以创建用户为例：（公司的cid为abc123）原始参数：action=createUser&account_name=zs&nickname=张三&department= dept_1&password=1qaz2wsxRSA加密后参数：1da01df7b4486978df8624b0e6c9122c4fdd74ff435b096c5b36df26a0c38947a409cc329bef750a28e5aac5c79d3e8ccdee46d59623ed5d45dc696cf7068741980c4e1c1745af599103af74e796ee5ca158866b9301fcfe06060c3cfdfa0c2ae326352cf5ba1800d1cca881da60dc02c69c897477295dc09b336e561f3b52eb020e5e29f70b58935b3c7cd4eda62c3f602a0de39e35741803bbe5b9b0c2e058c36f403fbd5aec361fcb3feacdef4e03110a3963003a98f7547e224791682bfd82b469968ec895abe3bc6bd02bad57095fc7a29dab097a1f38dd4f9102a9644150fac41d3bdd2ff92f0179fef63ce4b0f9074f53554cc087e52e288585269039完整的请求地址： /domain/services/externalApi?cid=abc123&enc=1da01df7b4486978df8624b0e6c9122c4fdd74ff435b096c5b36df26a0c38947a409cc329bef750a28e5aac5c79d3e8ccdee46d59623ed5d45dc696cf7068741980c4e1c1745af599103af74e796ee5ca158866b9301fcfe06060c3cfdfa0c2ae326352cf5ba1800d1cca881da60dc02c69c897477295dc09b336e561f3b52eb020e5e29f70b58935b3c7cd4eda62c3f602a0de39e35741803bbe5b9b0c2e058c36f403fbd5aec361fcb3feacdef4e03110a3963003a98f7547e224791682bfd82b469968ec895abe3bc6bd02bad57095fc7a29dab097a1f38dd4f9102a9644150fac41d3bdd2ff92f0179fef63ce4b0f9074f53554cc087e52e288585269039接口解析之后的地址（即原始请求）：/domain/services/internalApi?cid=abc123&enc=action=createUser&account_name=zs&nickname=张三&department= dept_1&password=1qaz2wsx3.3.4 操作示例1. 创建部门/domain/services/internalApi?cid=abc123&enc=action=createOrg&ouid=dept_1&org_unit_name=ABC销售部&u_desc=ABC销售部的描述2. 更新部门/domain/services/internalApi?cid=abc123&enc=action=updateOrg&ouid=dept_1&org_unit_name= ABC销售事业部3. 创建子部门/domain/services/internalApi?cid=abc123&enc=action=createOrg&ouid=dept_1_1&parent_org_unit_id=dept_1&org_unit_name=ABCSales&u_desc=Sales的部门描述4. 删除部门/domain/services/internalApi?cid=abc123&enc=action=deleteOrg&ouid=dept_1_15. 创建用户/domain/services/internalApi?cid=abc123&enc=action=createUser&account_name=zs&nickname=张三&department= dept_1&password=1qaz2wsx6. 修改用户属性/domain/services/internalApi?cid=abc123&enc=action=updateUser&account_name=zs&nickname=张三三&job_no=2137. 删除用户/domain/services/internalApi?cid=abc123&enc=action=deleteUser&account_name=zs8. 恢复用户/domain/services/internalApi?cid=abc123&enc=action=recoverUser&account_name=zs9. 修改用户密码/domain/services/internalApi?cid=abc123&enc=action=updateUserPwd&account_name=zs&password=2wsx1qaz注意：红色部分需要RSA加密3.4 应用示例以创建用户为例（假设客户域名为，cid值为abc123）： 原始参数：action=createUser&account_name=zs&nickname=张三&department= dept_1&password=1qaz2wsxRSA加密后参数：1da01df7b4486978df8624b0e6c9122c4fdd74ff435b096c5b36df26a0c38947a409cc329bef750a28e5aac5c79d3e8ccdee46d59623ed5d45dc696cf7068741980c4e1c1745af599103af74e796ee5ca158866b9301fcfe06060c3cfdfa0c2ae326352cf5ba1800d1cca881da60dc02c69c897477295dc09b336e561f3b52eb020e5e29f70b58935b3c7cd4eda62c3f602a0de39e35741803bbe5b9b0c2e058c36f403fbd5aec361fcb3feacdef4e03110a3963003a98f7547e224791682bfd82b469968ec895abe3bc6bd02bad57095fc7a29dab097a1f38dd4f9102a9644150fac41d3bdd2ff92f0179fef63ce4b0f9074f53554cc087e52e288585269039完整的请求地址： /domain/services/internalApi?cid=abc123&enc=1da01df7b4486978df8624b0e6c9122c4fdd74ff435b096c5b36df26a0c38947a409cc329bef750a28e5aac5c79d3e8ccdee46d59623ed5d45dc696cf7068741980c4e1c1745af599103af74e796ee5ca158866b9301fcfe06060c3cfdfa0c2ae326352cf5ba1800d1cca881da60dc02c69c897477295dc09b336e561f3b52eb020e5e29f70b58935b3c7cd4eda62c3f602a0de39e35741803bbe5b9b0c2e058c36f403fbd5aec361fcb3feacdef4e03110a3963003a98f7547e224791682bfd82b469968ec895abe3bc6bd02bad57095fc7a29dab097a1f38dd4f9102a9644150fac41d3bdd2ff92f0179fef63ce4b0f9074f53554cc087e52e288585269039接口解析之后的地址（即原始请求）：/domain/services/internalApi?cid=abc123&enc=action=createUser&account_name=zs&nickname=张三&department= dept_1&password=1qaz2wsx4 单点登录接口4.1 接口说明采用RSA加密算法的HTTP协议接口，客户提交邮箱帐号及加密信息，网易企业邮箱解密验证通过后，给予浏览器页面自动跳转登录访问邮箱。4.2 接口规范4.2.1 技术规范1. 客户按网易企业邮箱提供的算法（标准RSA算法，1024位密钥长度）生成公私钥，将公钥提供给网易企业邮箱，私钥自行妥善保管。通过接口提交URL参数必须使用RSA私钥进行摘要签名，以确保URL请求能验证通过。2. 接口使用HTTPS协议，每个请求URL只有一次请求有效，每个URL生成后5分钟内有效。4.2.2 使用规范1. POST或GET请求到URL：/domain/oa/Entry?domain=*&account_name=*&time=*&lang=*&enc=*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+文字说明的方式。如：200rn：操作成功；500rn：操作失败；4*rn：没有权限。4.3 应用示例网址：/ 热线：400-6281-163 第 13 页5 未读邮件数量接口5.1 接口说明采用RSA加密算法的HTTP协议接口，客户提交加密的邮箱帐号和服务器时间信息，网易企业邮箱验证并解密参数后，返回对应邮箱帐号所有未读邮件的数量。5.2 接口规范5.2.1 技术规范1. 客户按网易企业邮箱提供的算法（标准RSA算法，1024位密钥长度）生成公私钥，将公钥提供给网易企业邮箱，私钥自行妥善保管，通过接口提交URL链接参数必须使用RSA私钥加密，禁止明文传输。2. 客户还需要提供访问接口的服务器IP地址。网易企业邮箱会对IP地址进行服务授权，进一步增强接口的安全性，确保用户数据传输的绝对保密性3. 接口使用HTTPS协议，每个请求URL只有一次请求有效，每个URL生成后5分钟之内有效。5.2.2 使用规范1. 用GET或者POST请求到URL：/oaserver/server?domain=*¶m=*2. *：真实URL中替换为实际操作要填入的参数值。3. domain：企业邮箱注册域名，用于标识客户。4. param：RSA加密内容。param的明文内容为：user=*&time=*。a) user：需要返回未读邮件数量的邮箱帐号。b) time：生成URL的服务器当前时间(单位ms，至现在所经过的 UTC 毫秒数形式)。5. 返回数据采用JSON编码方式。参数描述：status（成功1，失败0）,msg（结果描述），count（未读邮件数）。示例如下所述：成功：status:1,msg: information,count:5失败：status:0,msg: informaition,count:05.3 应用示例1. GET方式提交的URL为：/oaserver/server?domain=¶m=4a18187336d98e9c7a416f86feaeb5ae560725cf607c8b6343e42773a0d98ac1186fa5b8ceb338757c3ce7368d691d2f24d483a66ed342492984563e5b01334c3fc8fb86617793e597addb533caa02f3f6b3ae026a822265111b2799c81f957a0d367ec80ebfe8c73a800f44c490d6946da7c0cb17786cad6250adb878143611a) 企业域名是abc，所以domain=b) 要求查询admin帐号的未读邮件，所以param的明文是：user=admin&time=13079456