## 一、开通服务 需先从平台获得接口交互的appId和appSecret； api服务地址：[http://ip](http://ip/):port/api/rayoauth； ## 二、技术要求 1.所有接口的请求，采用httpPost方式提交，发出http请求的时候，请求content-type需设定为：`application/x-www-form-urlencoded;charset=UTF-8` ，参数按照普通表单参数传值，不必包裹成一个json字符串； 2.所有接口的响应，采用json格式，编码为UTF-8，响应的content-type为：`application/json;charset=UTF-8`； 3.提供ip白名单功能，仅供授权的ip调用； 4.每个对外提供服务的api，都必须在请求头部包含参数`rayOauthServerAppId`（值是您拿到的appId）及`rayOauthServerTimeStamp`（值是时间戳，参考时间戳格式取值），为了确保不被外部不法分子恶意篡改请求，请求参数中绝对不能包含appSecret； 5.每个对外提供服务的api，都必须在请求头部包含一个`rayOauthServerSignature`参数，该参数是通过算法计算出来的值，具体算法参考后续签名算法章节； 6.考虑服务器承载量，目前限制每个ip访问接口频率不得超过1秒10次（可配置），超过这个次数，该请求将会被过滤，程序中不得做高频率轮询； 7.接口服务自身的设计与开发是基于BASE理论。因此，也强烈建议代码编写者遵循该理论；程序开发者必需考虑接口服务器因机房网络故障、域名解析故障、例行检修、程序升级、依赖服务中断等因素导致当前服务不可用。因此，业务逻辑的编写必须严格的核对响应码，并且必须编写消费接口服务的异常分支逻辑； ## 三、时间戳格式 1.获取从1970, 00:00:00开始到当前的毫秒数(13位，如java版本的：new Date().getTime()即可) ； 2.每个api请求的有效时间为3分钟（可配置），所以需确保当前服务请求发起端的时间有效； ## 四、签名算法 假设：paramstrings = 当前api的所有参数(除rayOauthServerSignature外)，根据参数名升序排序，以“参数名=值&”的方式连接起来； 结果：rayOauthServerSignature= md5(md5(paramstrings)+appSecret) >[danger] 注意： > 1、是双层md5（32位小写）加密，中间那个"+"仅表示两段字符相连,并不包括该符号本身； > 2、参数包括了请求头和请求体里面的所有参数； ## 五、接口限流 支持接口限流算法，在参数配置中，可配置每客户端每秒最大请求数，超过部分将被过滤限制掉；  ## 六、安全机制 除常规的安全机制（IP白名单、限流、api授权、时间戳校验、参数签名验证）等之外，平台还提供可选的防重放攻击等高级安全机制，但考虑实际必要性和性能，酌情启用； ``` rayframework.oauthserver.advanced-security-enabled=false ``` ## 七、资源优化 考虑到有些用户，对自身调用程序未做任何控制，导致大量无效请求占用服务器资源，故提供策略间歇性封锁ip的功能； ## 八、实例代码 ``` public class ClientSample { public static void main(String[] args) { Log4jV2Util.initLog4jV2TestEnv(); String hostUrl = "http://yourapidomain:8080/rayiot/api/rayoauth"; String apiUrl = "/sample/asyn"; String appId = "ray40c9903c6"; String appSecret = "46bacebf-f63c-41cc-b29c-5812994a5e83"; Map<String, String> paramap = new HashMap(); paramap.put("testParamInt", "1"); paramap.put("testParamString", "2"); String result = OauthCaller.call(hostUrl, apiUrl, appId, appSecret, paramap); Logger logger = LoggerFactory.getLogger(ClientSample.class); logger.debug(result); } } ```