产品/项目名称Product/Project Name 保密级别Confidentiality Level eYou邮件系统机密产品/项目版本Product/Project Version 最后更新日期Last Update81032014-09-12 eYou邮件系统V8接口文档北京亿中邮信息技术有限公司All Rights Reserved 版权所有侵权必究仅供内部使用Revision Record 修订记录目录1 API接口简介------------------------------------------------------------------------------------------------------- 32 API认证概述------------------------------------------------------------------------------------------------------- 4认证方式的分类 --------------------------------------------------------------------------------------------- 4认证方式的选择 --------------------------------------------------------------------------------------------- 5认证原理 ------------------------------------------------------------------------------------------------------- 5 3 认证方法详解及示例-------------------------------------------------------------------------------------------- 5OAuth ----------------------------------------------------------------------------------------------------------- 5 eYouAuth ------------------------------------------------------------------------------------------------------- 5 SSO API的eYouAuth认证方法：----------------------------------------------------------------- 5Feed API的eYouAuth认证方法： --------------------------------------------------------------- 7申请会话Token：------------------------------------------------------------------------------------- 8 4 API接口调用示例 ---------------------------------------------------------------------------------------------- 10Feed API调用----------------------------------------------------------------------------------------- 10资源概述 ---------------------------------------------------------------------------------------------- 10以用户的增删改查为例，示例各种Feed API调用步骤--------------------------------- 11 5 附表 ---------------------------------------------------------------------------------------------------------------- 131 API接口简介API指eYou邮件系统所提供的接口。
调用接口流程图：为了保证API 调用的安全性等因素，eYouMail API 要求调用方必须持有API KEY。
此API KEY 需要由调用方向eYouMail 方申请此。
eYouMail 方在接受调用方申请后，会颁发API KEY 以及一个与之配对的API SECRET。
调用方必须记录此API KEY 以及API SECTET。
API KEY是API提供方（例如部署了eYou邮件系统的单位）颁发给调用方（例如需要获取eYou邮件系统数据的OA系统）的身份识别串API KEY。
此API KEY事一个邮件地址格式的字符串，例如。
API提供方颁发给调用方身份识别串对应的秘钥。
此API_SECRET是一个32字节的字符串，例如35c51afdb3caa33d1e9b36802c5d79b8。
API接口分为两大类：（1）用户提供SSO（单点登录）的SSO API。
（2）用于邮件资源操作的Feed API。
2 API认证概述为保证API的安全性，防止非法的调用，识别调用者身份的合法性，在调用过程中必须先进行API认证。
认证方式的分类API支持三种认证方式，分别是OAuth、eYouAuth和eYouSimpleAuth方式。
OAuth是符合RFC规范的标准认证方式，而eYouAuth和eYouSimpleAuth是eYou自定义的规范。
认证方式的选择由于OAuth认证方式比较复杂，所以不建议使用OAuth认证方式，除非您的业务必须要求遵循OAuth方式认证。
eYouAuth比eYouSimpleAuth安全性更高，但是也会更复杂一些，需要先申请会话Token。
如果您对API调用的安全性要求较高，那么建议您使用eYouAuth认证方式。
如果您对API调用的安全性要求不是非常高（比如邮件系统部署在内网，只在内网使用），那么可以使用eYouSimpleAuth认证方式。
认证原理API认证的原理是：调用方在调用API的同时需要附加传递认证信息（API_KEY、API_SECRET、签名等），API在接收到调用请求的同时，首先获取认证信息并进行认证，如果认证失败则给出错误提示，如果认证成功则继续处理调用请求，之后返回处理结果。
不同的认证方式传递的认证信息有所不同，有的认证方式还需要先获取一些其他的安全认证数据用来生成认证信息，例如eYouAuth认证方式需要先申请会话Token。
3 认证方法详解及示例OAuth标准的OAuth认证方式。
详见OAuth官方文档以及RFC5849。
eYouAutheyouAuth认证方式对于SSO API和Feed API两种接口稍有不同，SSO API传递认证信息是通过HTTP GET的方式，Feed API则是通过把认证信息参数放到HTTP的Authorization头中传递。
SSO API的eYouAuth认证方法：将如下表格中的参数以GET参数的形式传递给SSO API。
注意：由于是通过HTTP GET方式传递认证信息参数，所以所有的参数的值都必须要进行RawUrlEncode处理。
Feed API的eYouAuth认证方法：将如下表格中的参数放到HTTP的Authorization头中传递给Feed API。
（Feed API的eYouAuth认证中，签名的计算不需要email，此处与SSO API不同）注意：由于是通过HTTP 头方式传递认证信息参数，所以所有的参数的值都必须要进行RawUrlEncode处理。
申请会话Token：在eYouAuth认证方式中，SSO API和Feed API都需要提前申请Token用于传参和计算签名，申请会话Token的请求URL为：申请会话Token需要向上述URL发送一个content-type 为application/x-www-form-urlencoded 的HTTP POST请求，此请求必须包含如下表格中的参数。
注意：由于是通过HTTP 头方式传递认证信息参数，所以所有的参数的值都必须要进行RawUrlEncode处理。
上表中的前三个参数必须传递，除了必须传递的参数之外，还可以附加传递其它附加参数，所有的附加参数都会被记录在eYou邮件系统中，以供下一步的验证使用（例如SSO API 要求必须传递一个email附加参数），但是要注意，附加的参数名不能以auth_开头，以防止和必须传递的参数冲突。
如果申请成功，会话Token 将会被放到HTTP POST请求的应答中输出。
成功或者失败的HTTP 应答及说明详见附表1。
获取Token完整示例假设如下参数的值为：API_KEYAPI_SECRET：35c51afdb3caa33d1e9b36802c5d79b8系统当前的整数时间戳：00计算签名)计算的结果：36b60aa4fcaf56cd761a9bed此时得到HTTP POST所必须的三个参数：auth_key ;auth_timestamp : 00 ;auth_signature : 36b60aa4fcaf56cd761a9bed ;SSO API申请Token时需要附加email参数：email ;对以上参数分别作RawUrlEncode 处理，得到如下结果：auth_key : apitest% ;auth_timestamp : 00 ;auth_signature : 3e7f0e9a79c51f1a67d74ac99fad08a3 ;email : test% ; （SSO API申请Token时需要）那么，Feed API HTTP POST请求数据包为：P OST /api/service/auth/get_tokenHost: application/x-www-form-urlencodedContent-Length: 131auth_key=api%&auth_timestamp=00 &auth_signature=36b60aa4fcaf56cd761a9bedSSO API HTTP POST请求数据包为：P OST /api/service/auth/get_tokenHost: application/x-www-form-urlencodedContent-Length: 131auth_key=api%&auth_timestamp=00 &auth_signature=36b60aa4fcaf56cd761a9bed&email=test% eYouSimpleAutheYouSimpleAuth认证方式与eYouAuth认证方式的区别是认证信息参数auth_type为simple，并且不需要申请会话Token。