MIUI论坛 下载APP

社区版主

鸭梨山大

Rank: 7Rank: 7Rank: 7

积分
30214
机型
MOTO XT910
签到次数
21
MIUI版本
V7.1.5.0.KXGCNCK
私信

万圣节勋章MIUI 3000万MIUI 2000万1000万用户纪念勋章MIUI 7MIUI五周年MIUI三周年百万壁纸关注微信极客勋章疾风测评勋章关注腾讯微博关注新浪微博MIUI 100周发烧友俱乐部MIUI六周年

[活动通知] 小米应用开发者文档:小米帐户OAuth2.0接口文档

[复制链接]
12556 6 |
2013-11-14 21:39 | 来自PC
| |
|
跳转
本帖最后由 Yeatshuai 于 2013-11-14 21:40 编辑

1. OAuth2.0概述                    Oauth2.0 SDK点击下载

小米的API的访问如获取米聊名片、获取米聊好友关系都需要使用用户身份,目前小米开发平台用身份授权使用OAuth2.0。

关于OAuth2.0协议授权流程开发者可以先浏览OAuth2.0的接口文档,熟悉OAuth2的接口及参数的含义,然后我们根据应用场景各自说明如何使用OAuth2.0。

相关名词解释:




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


2 . 接口文口


接口
说明
Oauth2/authorize
请求用户授权Code
Oauth2/token
获取授权过的Access Token 和 refresh token

流程说明

1. Authorization Code 流程


图片1.png


2. Implicit Flow流程


图片2.png


2.1 oauth2/authorize

  • oauth2/authorize
    OAuth2的authorize接口
  • URL
    https://account.xiaomi.com/oauth2/authorize
  • HTTP请求方
    GET
  • 请求参数
    名称
    必须
    范围
    说明
    client_id
    true
    Long
    申请应用时分配的App Id。
    client_secret
    false
    String
    申请应用时分配的App key, response_type为token时是必须的
    redirect_uri
    true
    String
    授权回调地址,必须和申请应用是填写的一致。
    response_type
    true
    String
    描述获取授权的方式,目前只支持code 和 token,Code 对应 Authorization Code Flow, token对应Implicit Flow。
    scope
    false
    String
    申请scope权限所需参数,可一次申请多个scope权限,用空格分隔。
    state
    false
    String
    用于保持请求和回调的状态,在回调时,会在   Query Parameter中回传该参数。开发者可以用这个参数  验证请求有效性,也可以记录用户请求授权页前的位置。
  • 返回数值
  • 1.response_type为code(Authorization Code Flow)
    返回值
    必须
    类型
    说明
    Code
    true
    String
    用于调用access_token,接口获取授权后的access token。
    state
    false
    String
    如果请求时传递参数,会回传该参数。
    2.response_type为token(Implicit Flow)
    返回值
    必须
    类型
    说明
    access_token
    true
    String
    取授权后的access token。
    expires_in
    true
    Int
    Access Token的有效期,以秒为单位
    scope
    true
    String
    Access Token最终的访问范围
    state
    false
    String
    如果请求时传递参数,会回传该参数。
    token_type
    true
    String
    说明返回的token类型,目前是mac
    mac_key
    true
    String
    mac密钥
    mac_algorithm
    true
    String
    mac计算的算法名称
    3.错误返回
    返回值
    必须
    类型
    说明
    error
    true
    Int
    Oauth定义的错误码。
    error_description
    false
    String
    对error的简单描述。
  • 示例
    1.请求
    https://account.xiaomi.com/oauth2/authorize?client_id=ID&redirect_uri=http://www.example.com&response_type=code

    2.同意授权后会重定向
    https://www.example.com?code=exapmleCode

2.2 oauth2/token
  • oauth2/token
    OAuth2的token接口, 该接口必须由client来调用。
  • URL
    https://account.xiaomi.com/oauth2/token
  • HTTP请求方式
    GET
  • 请求参数
    名称
    必须
    范围
    说明
    client_id
    true
    Long
    申请应用时分配的App Id
    redirect_uri
    true
    String
    授权回调地址,必须和申请应用是填写的一致。
    client_secret
    True
    String
    申请应用时分配的App key
    grant_type
    true
    String
    此值为authorization_code 或者 refresh_token
    refresh_token
    false
    String
    当grant_typerefresh_token时,必须传该参数,置为上次下发的refresh token
    code
    false
    String
    当grant_typeauthorization_code时,必须传该参数,置为上次下发的code
    token_type
    true
    String
    说明返回的token类型,目前是mac
    mac_key
    true
    String
    mac密钥
    mac_algorithm
    true
    String
    mac计算的算法名称
  • 返回数据
    如果应用验证通过(client_id与client_secret匹配,redirect_uri与获取Authorization Code时传递的redirect_uri保持一致),并且从用户获取的Authorization Code也正确人OAuth 2.0会返回Access Token相关的信息:
    1. {
    2. “access_token”: ”access token value”,
    3. “expires_in”: 360000,
    4. “refresh_token”: ”refresh token value”,
    5. “scope”: ”scope value”,
    6. “token_type ”: ”mac”,
    7. “mac_key ”: ”mac key value”,
    8. “mac_algorithm”: ” HmacSha1″
    9. }
    复制代码
    (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
    如果应用验证过程中出错, OAuth 2.0返回错误信息:
    1. {
    2. “error”: ”error_code”,
    3. “error_ description ”: ”错误描述 ”,
    4. }
    复制代码
    (1) error:错误码;
    (2) error_description:一段人类可读的文字,用来帮助理解和解决发生的错误;
  • 示例
    1.请求
    https://account.xiaomi.com/oauth2/token?client_id=ID&redirect_uri=http://www.example.com&grant_type=authorization_code&client_secret=SECRET&code=CODE


3 . OAuth2.0 错误码

OAuth2.0实现中,授权服务器在接收到验证授权请求时,会按照OAuth2.0协议对本请求的请求参数进行检验,若请求不合法或验证未通过,授权服务器会返回相应的错误信息,包含以下几个参数:
  • error: 错误码
  • error_description: 错误的描述信息

错误信息的返回方式有两种:
1. 当请求授权https://account.xiaomi.com/oauth2/authorize 时出现错误,返回方式是:跳转到redirect_uri,并在uri 的query parameter中附带错误的描述信息。
2. 当请求access token https://account.xiaomi.com/oauth2/token 时出现错误,返回方式:返回JSON文本。例如:

  1. <table width="0" class="t_table"><tbody><tr><td width="536"><div align="left"><font size="3">{
  2. “error”:”errorcode”,
  3. “error_description”:”errorCode<font face="宋体">描述</font>”
  4. }</font></div></td></tr></tbody></table>
复制代码


OAuth2.0错误响应中的错误码定义如下表所示:

错误码
错误描述
OA_CLIENT_NOT_EXISTS(96001)
client不存在
OA_INVALID_REQUEST(96002)
请求缺少某个必需参数,或者格式不正确
OA_INVALID_CLIENT(96003)
client_id 和client_secret不匹配
OA_INVALID_GRANT(96004)
grant可是无效的
OA_UNAUTHORIZED_CLIENT(96005)
客户端没有权限使用该请求
OA_UNSUPPORTED_GRANT_TYPE(96006)
grant不被授权服务器所支持
OA_INVALID_SCOPE(96007)
scope是无效的、未知的,或格式不正确的
OA_INVALID_TOKEN(96008)
token无效或已经过期
OA_INVALID_REFRESHTOKEN(96009)
refresh token无效或已经过期
OA_INVALID_REDIRECT_URI(96010)
重定向URI与预先注册的值不匹配或者不是一个合法的URI
OA_UNSUPPORTED_RESPONSE_TYPE(96011)
响应类型不为授权服务器所支持
OA_ACCESS_DENIED(96012)
用户或授权服务器拒绝了请求
OA_INVALID_CODE(96013)
授权码无效或已经过期
4 . API使用mac type access token说明4.1 MAC加密算法

客户端使用MAC算法 + MAC KEY来对“格式化的请求内容(下节说明)“进行加密,计算出消息认证码。MAC算法有HmacSha1。
Java算法示例

  1. <table width="0" class="t_table"><tbody><tr><td width="568"><div align="left"><font size="3">public static byte[] encryptHMACSha1(byte[] data, byte[] key) {
  2. SecretKeySpec signingKey = new SecretKeySpec(key, HMAC_SHA1);
  3. Mac mac = Mac.getInstance(HMAC_SHA1);
  4. mac.init(signingKey);mac.update(data);
  5. return mac.doFinal();
  6. }</font></div></td></tr></tbody></table>
复制代码


Php算法示例

  1. <table width="0" class="t_table"><tbody><tr><td width="568"><div align="left"><font size="3">static public function buildSignature($signString, $secret) {
  2. $sign = base64_encode(hash_hmac(‘sha1′, $signString, $secret, true));
  3. return urlencode($sign);
  4. }</font></div></td></tr></tbody></table>
复制代码


4.2 格式化的请求内容

格式化的请求字符串,就是用指定的请求属性按照某个规则拼接而成的字符串。
格式化的请求字符串 = 随机串 + \n + HTTP方法 + \n + HOST + \n + URI+ \n + QUERY+\n

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

示例:
formate_content = 54897465748976549:214579478\nGET\n open.account.xiaomi.com\n/user/profile\n clientId=xxx&token=xxx\n


4.3 API请求格式

采用MAC  Type access token调用API,需要将相关放入请求的Authorization Header。


设置Authorization Header

第三方在发送API请求时,要对请求进行MAC加密计算,并将结果放到请求header中的”Authorization”字段中。Authorization字段:

Authorization: MAC access_token=”token value”,nonce=”随机码” ,mac=”签名值”

access_token : 授权时下发的access_token
nonce:随机串,由客户端按照2中规则产生的随机字符串。
mac:签名值,根据mac算法计算生成的。
Mac = HmacSha1(formate_content, mac_key)


5 小米账号的开放API5.1 获取用户名片
  • User/profile
    获取用户信息接口。
  • URL:
    https://open.account.xiaomi.com/user/profile
  • HTTP请求方式:
    GET
  • 请求参数:
    名称
    必须
    范围
    说明
    clientId
    true
    Long
    申请应用时分配的App Id
    token
    true
    String
    用户授权时client得到的token
  • Heaer数据:参考第4节中方式生成Header授权信息。
  • 返回数据:
    如果应用验证通过,会返回用户相关的信息:
    1. <table width="0" class="t_table"><tbody><tr><td width="536"><div align="left"><font size="3">{
    2. “result”: ”ok”,
    3. “description”: ”成功”,
    4. “data”: {“miliaoNick”: ”米聊昵称”,”userId”: 米聊号,”miliaoIcon”: 头像URL},
    5. “code”: 0
    6. }</font></div></td></tr></tbody></table><div align="left"></div>
    复制代码
    如果应用验证过程中出错, API返回错误信息:
    1. {
    2. “result”: ”error”,
    3. “description”: ”错误描述”,
    4. “code”: 错误码
    5. }
    复制代码



5.2 获取用户的关系列表
  • User/relation
    获取用户信息接口。
  • URL:
    https://open.account.xiaomi.com/user/relation
  • HTTP请求方式
    GET
  • 请求参数:
    名称
    必须
    范围
    说明
    clientId
    true
    Long
    申请应用时分配的App Id
    token
    true
    String
    用户授权时client得到的token
    Heaer数据:参考第4节中方式生成Header授权信息。
  • 返回数据:
    如果应用验证通过,会返回用户相关的信息:
    1. <table width="0" class="t_table"><tbody><tr><td width="536"><div align="left"><font size="3">{
    2. “result”: ”ok”,
    3. “description”: ”成功”,
    4. “data”: {“friends”: ”好友列表”},
    5. “code”: 0
    6. }</font></div></td></tr></tbody></table>
    复制代码
    如果应用验证过程中出错, API返回错误信息:
    1. <table width="0" class="t_table"><tbody><tr><td width="536"><div align="left"><font size="3">{
    2. “result”: ”error”,
    3. “description”: ”错误描述”,
    4. “code”: 错误码
    5. }</font></div></td></tr></tbody></table>
    复制代码


其他参考


1. OAuth是一种国际通用的授权方式, OAuth2.0的官方技术说明可参看 http://oauth.net/2/

2. 可以参考新浪微博等国内标准oauth授权流程。


收藏2 分享  

主题酷玩组

>>忽略这头衔吧<<

Rank: 6Rank: 6

积分
35999
机型
小米Max-高配全网通版
签到次数
183
MIUI版本
9.6.27
私信

国庆勋章MIUI 3000万MIUI 2000万1000万用户纪念勋章MIUI三周年关注微信关注腾讯微博关注新浪微博

2013-11-14 21:39 | 来自PC
|
check it down~

玩机大师

Rank: 4

积分
1095
机型
小米手机2/2S
签到次数
0
MIUI版本
0
私信
2013-12-28 21:05 | 来自PC
|
技术贴啊

玩机大师

Rank: 4

积分
1095
机型
小米手机2/2S
签到次数
0
MIUI版本
0
私信
2013-12-28 21:06 | 来自PC
|
OAuth2.0 是么么东东啊,支持了

MIUI开发组

Rank: 8Rank: 8

积分
423
机型
未知设备
签到次数
39
MIUI版本
V6.7.1.0.KXECNCH
私信
2014-10-11 17:27 | 来自PC
|
不错,很详细,收藏了

玩机小白

Rank: 1

积分
32
机型
未知设备
签到次数
0
MIUI版本
V8.2.22.0.MCFCNDL
私信
2018-5-16 10:43 | 来自PC
|
为什么认证的页面显示的是英文的?怎么改能改成中文?

玩机大师

Rank: 4

积分
1531
机型
未知设备
签到次数
19
MIUI版本
8.9.20
私信
2018-7-3 10:30 | 来自PC
|
MIUI 因你更精彩!
快速回复 返回顶部 返回列表