小米帐号OAuth 2.0互通接口应用学习

最近，在做一个和小米账号互通的第三方登陆接口，详细的学习了小米开发者文档，下面对接口文档的学习进行总结和汇总。

1.相关名词的解释

• 服务提供方(resource server): 用户使用服务提供方来存储受保护的资源，这里指的是小米公司。
• 用户(user):存放在服务提供方的受保护的资源的拥有者。
• 客户端(client):要访问服务提供方资源的第三方应用，通常是网站在认证过程之前，客户端要向服务提供者申请客户端标识。
• 令牌(token):分发给客户端的代表访问授权的字符串。通常这个字符串对客户端来说是不透明的。令牌代表资源拥有者许可的访问作用域和持续时间，并由资源服务器和授权服务器强制保证。这个令牌可以代表一个标识符，用于检索授权信息，或以一种可验证的方式自包含授权信息（即一个包含数据和签名的令牌字符串）。令牌可能只代表纯粹的访问能力。
• 访问令牌(access token):客户端用来代表资源拥有者发送验证请求的令牌。 小米API将支持OAuth 2.0中Bearer Token和MAC Token的两种token形式。
• 刷新令牌(refresh token):客户端用来获取新的访问令牌的令牌，而不用资源拥有者的参与。
• 授权码(code):一个短期令牌，代表终端用户的授权。授权码用于获取一个访问令牌和一个刷新令牌。
• 客户端标识符(client id):分发给客户端的唯一标识，用于客户端向授权服务器标识自己。客户端标识符可以有一个对应的密钥。

2.授权接口说明

授权码方式(authorization code)获取访问令牌(access token)的授权验证流程又被称为web server flow，适用于所有有服务端的应用，如Web/Wap站点、有服务端的手机/桌面客户端应用等。

2.1请求用户授权接口

• URL: https://account.xiaomi.com/oauth2/authorize
• HTTP请求方: GET
  请求用户授权参数表

名称 必须 范围 说明 client_id true Long 申请应用时分配的App Id。 redirect_uri true String 授权回调地址,必须和申请应用是填写的一致。 response_type true String 描述获取授权的方式，目前只支持code 和 token，Code 对应 Authorization Code true String Flow， token对应Implicit Flow。 scope false String 申请scope权限所需参数，可一次申请多个scope权限，用空格分隔。 state false String 用于保持请求和回调的状态，在回调时，会在Query Parameter中回传该参数。 skip_confirm false Boolean 是否跳过帐号确认过程，黄页接入请设置为true（skip_confirm=true）

接口返回值
response_type为code（Authorization Code Flow）时接口返回值:

名称 必须 范围 说明 code True String 用于调用access_token，接口获取授权后的access token。 state False String 如果请求时传递参数，会回传该参数。

2.2 获取访问令牌接口

• URL : http://account.xiaomi.com/oauth2/token
• HTTP请求方式: GET
  获取访问令牌参数表

名称 必须 范围 说明 client_id True Long 申请应用时分配的App Id。 redirect_uri True String 授权回调地址,必须和申请应用是填写的一致。 client_secret True String 申请应用时分配的App Secret grant_type True String 此值为authorization_code 或者 refresh_token refresh_token False String 当grant_type为refresh_token时，必须传该参数，置为上次下发的 code False String 当grant_type为authorization_code时，必须传该参数，置为上次下发的code值 token_type True String 说明返回的token类型,目前是mac

接口返回值
接口返回值是一个Json格式字符串，具体说明如下：
第三方获取访问令牌验证通过，该接口返回Access Token相关的信息：
{
“access_token”: “access token value”,
“expires_in”: 360000,
“refresh_token”: “refresh token value”,
“scope”: “scope value”,
“token_type “: “mac”,
“mac_key “: “mac key value”,
“mac_algorithm”: ” HmacSha1”
“openId”=”2.0XXXXXXXXX”
}
字段说明：
1. access_token：获取的Access Token；
2. expires_in：Access Token的有效期，以秒为单位；
3. refresh_token：用于刷新Access Token ,有效时间为10年；
4. scope：Access Token最终的访问范围，既用户实际授予的权限列表；
5. token_type: access token的类型，type值为mac；
6. mac_key: MAC加密算法对请求进行加密时的密钥；
7. mac_algorithm:MAC加密的算法，目前只支持HmacSha1
8. openId: 是v2版本所提供的一种唯一标识

2.3获取用户名片

• URL： https://open.account.xiaomi.com/user/profile
• HTTP请求方式：GET
  获取用户名片参数表

名称 必须 范围 说明 clientId True Long 申请应用时分配的App Id。 token True String 用户授权时client得到的token Header数据 True 详见下文 按照小米提供的算法生成Header授权信息。

返回数据

• 正确返回:
  如果访问令牌验证通过，会返回用户相关的信息， 返回格式为Json文本， 格式如下：
  {
  “result”: “ok”,
  “description”: “成功”,
  “data”: {
  “miliaoNick”: “米聊昵称”,
  “userId”: 米聊号,
  “miliaoIcon”: 头像URL
  },
  “code”: 0
  }
• 错误返回
  如果访问令牌验证错误，会返回错误信息， 返回格式为Json文本， 格式如下：
  {
  “result”: “error”,
  “description”: “错误描述”,
  “code”: 错误码
  }

3.Mac Token详细说明

MacToken是授权小米下发的一种访问令牌类型，使用MacToken调用API时，用MAC加密算法对请求进行加密，并将结果放到http请求的header中。MAC算法有HmacSha1和HmacSha256两种，小米API默认使用HmacSha1。
Java算法示例

public static byte[] encryptHMACSha1(byte[] data, byte[] key) {  SecretKeySpec signingKey = new SecretKeySpec(key, HMAC_SHA1);  Mac mac = Mac.getInstance(HMAC_SHA1);  mac.init(signingKey);  mac.update(data);  return mac.doFinal();}

PHP算法示例

static public function buildSignature($signString, $secret) {  $sign = base64_encode(hash_hmac('sha1', $signString, $secret, True));  return urlencode($sign);}

3.1请求内容标准化
使用Mac Token需要将请求内容按照一定的规则拼接形成符合要求的标准的格式字符串，标准化字符串用于计算请求API的签名值，小米规定的格式请求字符串格式如下（\n代表换行）：
格式化字符串 = Nonce + \n + HTTP方法 + \n + HOST + \n + URI+ \n + QUERY+\n

属性 说明 示例 Nonce 由随机数和时间戳组成,格式:随机数:当前分钟数 HTTP方法 调用API时请求方式 GET/ POST HOST 调用API时的域名 open.account.xiaomi.com URI 调用API时的path(必须以/开头) /user/profile QUERY Key 按照字典序排列的query串,内容为空的去query字段不参与签名 clientId=xxx&token=xxx

具体示例：
请求字符串=54897465748976549:21459478\nGET\n open.account.xiaomi.com\n/user/profile\n
clientId=xxx&token=xxx\n

3.2MacToken请求格式
采用Mac Token调用API，需要将相关签名信息放入请求的http请求的Header中。第三方在发送API请求时，要对请求进行MAC加密计算，并将结果放到请求Header中的”Authorization”字段中。
Authorization字段内容如下：
Authorization: MAC access_token=”token value”,nonce=”随机码” ,mac=”签名值”
字段含义说明：
1. access_token : 授权时下发的access_token。
2. nonce：随机串，由客户端按照2中规则产生的随机字符串包括当前分钟数值。
3. mac：签名值，根据mac算法计算生成的。Mac = HmacSha1（格式化字符串, mac_key）。

相关方法的源代码

static long localTimeDiff = dateDiff(DateTime.Now, getServerTime());static private Random ran = new Random(Dns.GetHostName().GetHashCode()+ (int)DateTime.Now.Ticks);//根据主机名的hashcode和现在时间得到随即种子;/**  * 获取时间差（注意时区）  * @param DateTimeStart时间开始  * @param DateTimeEnd时间结束  * @return 得到时差  */static long dateDiff(DateTime DateTimeStart, DateTime DateTimeEnd){    long dateDiff = 0;    TimeSpan end = new TimeSpan(DateTimeEnd.Ticks);    TimeSpan start = new TimeSpan(DateTimeStart.Ticks);    TimeSpan diff = end.Subtract(start).Duration();    dateDiff = (diff.Days * 24 + diff.Hours);    dateDiff = dateDiff * 60 + diff.Minutes;    Console.WriteLine("get the timediff " + dateDiff);    return dateDiff;}/** * 得到header的值 * @param  nonce为随机数 * @param  mac为mac加密的值 * @param  accessToken为访问令牌 * @return 得到header的值 */static public String createHeader(string nonce, string mac, string accessToken){    string header = string.Format("MAC access_token=\"{0}\",nonce=\"{1}\",mac=\"{2}\"", Uri.EscapeDataString(accessToken), Uri.EscapeDataString(nonce), Uri.EscapeDataString(mac));    return header;}/** * 得到HMACSHA1加密的密文(密文格式为nonce + \n + method(POST\GET) + \n + host + \n + uriPaht + \n + req(queryparam按照key的字典序)+\n(最后也需要添加一个\n)) * @param  nonce为随机数 * @param  query为请求 * @param  method http方法，填“GET”或“POST” * @param  localPath使用参数详情看sdk文档 * @param  macKey，hmacsha1的密钥 * @return 得到HMACSHA1加密的密文 */static public String createCiphertext(string nonce, string query, string method, string localPath, string macKey){    method = method.ToUpperInvariant();    string ciphertext = nonce + "\n" + method + "\n" + XiaoMiHttpClientConst.hostURI + "\n" + localPath + "\n" + query + "\n";    HMACSHA1 hmacsha1 = new HMACSHA1();    hmacsha1.Key = Encoding.UTF8.GetBytes(macKey);    byte[] dataBuffer = Encoding.UTF8.GetBytes(ciphertext);    byte[] hashBytes = hmacsha1.ComputeHash(dataBuffer);    ciphertext = Convert.ToBase64String(hashBytes);    return ciphertext;}/*** 得到服务器现在的时间* @param  * @return 得到服务器现在的时间*/static public DateTime getServerTime(){    HttpWebRequest request = (HttpWebRequest)WebRequest.Create(XiaoMiHttpClientConst.apiURI);    request.Method = "GET";    HttpWebResponse response;    Console.WriteLine("waiting for getting the server time");    try    {        response = (HttpWebResponse)request.GetResponse();    }    catch (WebException ex)    {        response = (HttpWebResponse)ex.Response;    }    if (response == null) Console.WriteLine("error： can not get the server time ,please check the network connections");    return response.LastModified;}/* * 得到Nonce用  随机数：时间分钟差 为格式 * @param   * @return Nonce */static public string getNonce(){    //产生随机数过程    int randKey = ran.Next();    string nonce = randKey + ":" + (dateDiff(new DateTime(1970, 1, 1, 8, 0, 0), DateTime.Now) + localTimeDiff);    return nonce;}