目录 1. OAUTH 2.0 概述授权接口说明授权流程说明授权码方式授权流程 Implicit Grant 方式授权流程授权接口说明请求用户授权接口

Size: px

Start display at page:

Download "目录 1. OAUTH 2.0 概述授权接口说明授权流程说明授权码方式授权流程 Implicit Grant 方式授权流程授权接口说明请求用户授权接口"

关其谈
5 years ago
Views:

1 小米帐户 OAuth 2.0 文档版本号 :1.3 更新日期 :

2 目录 1. OAUTH 2.0 概述授权接口说明授权流程说明授权码方式授权流程 Implicit Grant 方式授权流程授权接口说明请求用户授权接口获取访问令牌接口 OAUTH 2.0 错误码 MAC TOKEN 使用说明 MAC TOKEN 说明使用方法标准化字符串 API 请求格式小米账号的开放 API 获取用户名片获取用户的关系列表获取用户 OPENID

3 表格目录表 2-1 请求用户授权参数表... 8 表 2-2 请求用户授权返回值表 (RESPONSE_TYPE 为 CODE)... 9 表 2-3 请求用户授权返回值表 (RESPONSE_TYPE 为 TOKEN)... 9 表 2-4 请求用户授权错误类型表... 9 表 2-5 获取访问令牌参数表表 3-1 OAUTH 2.0 错误码表表 5-1 获取用户名片参数表表 5-2 获取用户关系列表参数表表 5-3 获取用户 OPENID 参数表表 5-4 验证用户密码接口参数表图片目录图 1-1 小米帐号授权流程图... 4 图 2-1 授权码方式授权流程... 6 图 2-3 IMPLICIT GRANT 流程授权流程

1 OAuth 2.0 概述小米账号 API 访问, 如获取用户名片获取米聊好友关系等都需要使用用户身份, 目前小米账号开放平台用户身份鉴权使用 OAuth 2.0 关于 OAuth 2.0 协议授权流程开发者可以先浏览 OAuth 2.0 的接口文档, 熟悉 OAuth 2.0 的接口及参数的含义, 然后我们根据应用场景各自说明如何使用 OAuth 2.0 图错误!

4 1 OAuth 2.0 概述小米账号 API 访问, 如获取用户名片获取米聊好友关系等都需要使用用户身份, 目前小米账号开放平台用户身份鉴权使用 OAuth 2.0 关于 OAuth 2.0 协议授权流程开发者可以先浏览 OAuth 2.0 的接口文档, 熟悉 OAuth 2.0 的接口及参数的含义, 然后我们根据应用场景各自说明如何使用 OAuth 2.0 图错误! 文档中没有指定样式的文字 -1 小米帐号授权流程图相关名词解释 : 服务提供方 (resource server): 用户使用服务提供方来存储受保护的资源, 这里指的是小米公司用户 (user): 存放在服务提供方的受保护的资源的拥有者客户端 (client): 要访问服务提供方资源的第三方应用, 通常是网站在认证过程之前, 客户端要向服务提供者申请客户端标识 4

5 令牌 (token): 分发给客户端的代表访问授权的字符串通常这个字符串对客户端来说是不透明的令牌代表资源拥有者许可的访问作用域和持续时间, 并由资源服务器和授权服务器强制保证这个令牌可以代表一个标识符, 用于检索授权信息, 或以一种可验证的方式自包含授权信息 ( 即一个包含数据和签名的令牌字符串 ) 令牌可能只代表纯粹的访问能力访问令牌 (access token): 客户端用来代表资源拥有者发送验证请求的令牌小米 API 将支持 OAuth 2.0 中 Bearer Token 和 MAC Token 的两种 token 形式刷新令牌 (refresh token): 客户端用来获取新的访问令牌的令牌, 而不用资源拥有者的参与授权码 (code): 一个短期令牌, 代表终端用户的授权授权码用于获取一个访问令牌和一个刷新令牌客户端标识符 (client id): 分发给客户端的唯一标识, 用于客户端向授权服务器标识自己客户端标识符可以有一个对应的密钥 5

6 2 授权接口说明 2.1 授权流程说明授权码方式授权流程授权码方式 (authorization code) 获取访问令牌 (access token) 的授权验证流程又被称为 web server flow, 适用于所有有服务端的应用, 如 Web/Wap 站点有服务端的手机 / 桌面客户端应用等图错误! 文档中没有指定样式的文字 -1 授权码方式授权流程 Implicit Grant 方式授权流程 Implicit Grant 方式获取访问令牌 (access token) 的授权验证流程又被称为 User-Agent Flow, 适用于所有无服务端配合的应用 ( 由于应用往往位于一个 User 6

7 Agent 里, 如浏览器里面, 因此这类应用在某些平台下又被称为 Client-Side Application), 如手机 / 桌面客户端程序浏览器插件等, 以及基于 JavaScript 等脚本客户端脚本语言实现的应用, 他们的一个共同特点是, 应用无法妥善保管其应用密钥 (App Secret Key) 图错误! 文档中没有指定样式的文字 -2 Implicit Grant 流程授权流程 7

8 2.2 授权接口说明请求用户授权接口 URL: HTTP 请求方 : GET 请求参数 : 表 2-1 请求用户授权参数表名称必须范围说明 client_id True Long 申请应用时分配的 App Id redirect_uri response_type scope state skip_confirm True String 授权回调地址, 必须和申请应用是填写的一致 True String 描述获取授权的方式, 目前只支持 code 和 token,code 对应 Authorization Code Flow, token 对应 Implicit Flow False String 申请 scope 权限所需参数, 可一次申请多个 scope 权限, 用空格分隔 False String 用于保持请求和回调的状态, 在回调时, 会在 Query Parameter 中回传该参数开发者可以用这个参数验证请求有效性, 也可以记录用户请求授权页前的位置 False Boolean 当用户处于已经等了状态, 当值为 true 会跳过用户确认登录页面, 默认为 false 接口返回值 8

9 请求授权接口会将结果作为 redirect_uri 的参数返回给第三方调用者, response_type 不同返回的参数也不同, 区别如下 : response_type 为 code(authorization Code Flow) 时接口返回值如表 2-2 所述表 2-2 请求用户授权返回值表 (response_type 为 code) 返回值必须类型说明 code True String 用于调用 access_token, 接口获取授权后的 access token state False String 如果请求时传递参数, 会回传该参数 response_type 为 token(implicit Grant Flow) 接口返回值如表 2-3 所述表 2-3 请求用户授权返回值表 (response_type 为 token) 返回值必须类型说明 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 计算的算法名称错误返回表 2-4 请求用户授权错误类型表返回值必须类型说明 error True Int OAuth 定义的错误码 9

10 error_description False String 对 error 的简单描述示例请求 = = 同意授权后会重定向到 redirect_uri 获取访问令牌接口 URL : HTTP 请求方式 : GET 请求参数表 2-5 获取访问令牌参数表名称必须范围说明 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_type 为 refresh_token 时, 必须 10

11 传该参数, 置为上次下发的 refresh token 值 code False String 当 grant_type 为 authorization_code 时, 必须传该参数, 置为上次下发的 code 值 token_type True String 说明返回的 token 类型, 目前是 mac mac_key True String mac 密钥 mac_algorithm True String mac 计算的算法名称接口返回值接口返回值是一个 Json 格式字符串, 具体说明如下 : 正确的返回结果第三方获取访问令牌验证通过, 该接口返回 Access Token 相关的信息 : { "access_token": "access token value", "expires_in": , "refresh_token": "refresh token value", "scope": "scope value", "token_type ": "mac", "mac_key ": "mac key value", "mac_algorithm": " HmacSha1" 字段说明 : 1) access_token: 获取的 Access Token; 2) expires_in:access Token 的有效期, 以秒为单位 ; 3) refresh_token: 用于刷新 Access Token, 有效时间为 10 年 ; 4) scope:access Token 最终的访问范围, 既用户实际授予的权限列表 ; 11

12 5) token_type: access token 的类型,type 值为 mac; 6) mac_key: MAC 加密算法对请求进行加密时的密钥 ; 7) mac_algorithm:mac 加密的算法, 目前只支持 HmacSha1 错误的返回结果如果应用验证过程中出错, OAuth 2.0 返回错误信息 : { "error": "error_code", "error_ description ": " 错误描述 ", 1) error: 错误码, 是一个 int 类型的数字 ; 2) error_description: 一段人类可读的文字, 用来帮助理解和解决发生的错误 ; 示例 Grant type 为 authorization_code 请求 / RET&code=CODE Grant type 为 refresh token 请求 ET&refresh_token=REFRESHTOKEN 12

13 3 OAuth 2.0 错误码说明 OAuth 2.0 实现中, 授权服务器在接收到验证授权请求时, 会按照 OAuth 2.0 协议对本请求的请求参数进行检验, 若请求不合法或验证未通过, 授权服务器会返回相应的错误信息, 包含以下几个参数 : error: 错误码 error_description: 错误的描述信息错误信息的返回方式有两种 : 1). 当请求授权时出现错误, 返回方式是 : 跳转到 redirect_uri, 并在 uri 的 query parameter 中附带错误的描述信息 2). 当请求时出现错误, 返回方式是 JSON 文本, 例如 : { "error":"errorcode", "error_description":"errorcode 描述 " OAuth 2.0 错误响应中的错误码定义如表 3-1 所示 : 表 3-1 OAuth 2.0 错误码表错误码 OA_CLIENT_NOT_EXISTS(96001) OA_INVALID_REQUEST(96002) OA_INVALID_CLIENT(96003) 错误描述 client 不存在请求缺少某个必需参数, 或者格式不正确 client_id 和 client_secret 不匹配 13

14 OA_INVALID_GRANT(96004) OA_UNAUTHORIZED_CLIENT(96005) OA_UNSUPPORTED_GRANT_TYPE(96006) OA_INVALID_SCOPE(96007) OA_INVALID_TOKEN(96008) OA_INVALID_REFRESHTOKEN(96009) OA_INVALID_REDIRECT_URI(96010) grant 可是无效的客户端没有权限使用该请求 grant 不被授权服务器所支持 scope 是无效的未知的, 或格式不正确的 token 无效或已经过期 refresh token 无效或已经过期重定向 URI 与预先注册的值不匹配或者不是一个合法的 URI OA_UNSUPPORTED_RESPONSE_TYPE(96011) 响应类型不为授权服务器所支持 OA_ACCESS_DENIED(96012) OA_INVALID_CODE(96013) 用户或授权服务器拒绝了请求授权码无效或已经过期 14

15 4 Mac Token 使用说明 4.1 Mac Token 说明 MacToken 是授权小米下发的一种访问令牌类型, 使用 MacToken 调用 API 时, 用 MAC 加密算法对请求进行加密, 并将结果放到 http 请求的 header 中 MAC 算法有 HmacSha1 和 HmacSha256 两种, 小米 API 默认使用 HmacSha1 下面给出 Java 和 PHP 算法示例 : 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); 4.2 使用方法请求内容标准化使用 Mac Token 需要将请求内容按照一定的规则拼接形成符合要求的标准的格式字符串, 标准化字符串用于计算请求 API 的签名值, 小米规定的格式请 15

16 求字符串格式如下 (\n 代表换行 ): 格式化字符串 = Nonce + \n + HTTP 方法 + \n + HOST + \n + URI+ \n + QUERY+\n 属性说明示例 Nonce 由随机数和时间戳组成, 格式 : 随机数 : 当前分钟数 (1970 年 1 月 1 日午夜 : ( 注意冒号分割 ) 点之间的时间差 ) HTTP 方法调用 API 时请求方式 GET/ POST HOST 调用 API 时的域名 open.account.xiaomi.com( 没有 http 或 https) URI 调用 API 时的 path( 必须以 / 开头 ) /user/profile QUERY Key 按照字典序排列的 query 串, 内容为空的去 query 字段不参与签名 clientid=xxx&token=xxx 具体示例 : 请求字符串 = : \nGET\n open.account.xiaomi.com\n/user/profile\n clientid=xxx&token=xxx\n Mac Token 请求格式采用 Mac Token 调用 API, 需要将相关签名信息放入请求的 http 请求的 Header 中第三方在发送 API 请求时, 要对请求进行 MAC 加密计算, 并将结果放到请求 Header 中的 "Authorization" 字段中 Authorization 字段内容如下 : Authorization: MAC access_token="token value",nonce=" 随机码 ",mac=" 签名值 " 字段含义说明 : 16

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

18 5 小米账号的开放 API 5.1 获取用户名片 URL: HTTP 请求方式 :GET 请求参数 : 表 5-1 获取用户名片参数表名称必须范围说明 clientid True Long 申请应用时分配的 App Id token True String 用户授权时 client 得到的 token Header 数据 : 参考第 4 节中方式生成 Header 授权信息返回数据 : 正确返回如果访问令牌验证通过, 会返回用户相关的信息, 返回格式为 Json 文本, 格式如下 : { "result": "ok", "description": " 成功 ", "data": { "miliaonick": " 米聊昵称 ", "userid": 米聊号, "miliaoicon": 头像 URL, "code": 0 18

19 错误返回如果访问令牌验证错误, 会返回错误信息, 返回格式为 Json 文本, 格式如下 : { "result": "error", "description": " 错误描述 ", "code": 错误码 5.2 获取用户的关系列表 URL: HTTP 请求方式 :GET 请求参数 : 表 5-2 获取用户关系列表参数表名称必须范围说明 clientid True Long 申请应用时分配的 App Id token True String 用户授权时 client 得到的 token Heaer 数据 : 参考第 4 节中方式生成 Header 授权信息返回数据 : 正确返回如果访问令牌验证通过, 会返回用户好友列表的信息, 返回格式为 Json 文本, 格式如下 : { "result": "ok", "description": " 成功 ", "data": { 19

20 , "code": 0 "friends": " 好友列表 " 错误返回如果访问令牌验证错误, 会返回错误信息, 返回格式为 Json 文本, 格式如下 : { "result": "error", "description": " 错误描述 ", "code": 错误码 5.3 获取用户 OpenId URL: HTTP 请求方式 :GET 请求参数 : 表 5-3 获取用户 OpenId 参数表名称必须范围说明 clientid True Long 申请应用时分配的 App Id token True String 用户授权时 client 得到的 token Heaer 数据 : 无需签名信息返回数据 : 正确返回如果访问令牌验证通过, 会返回用户 OpenID 相关的信息, 返回格式为 Json 文本, 格式如下 : { "result": "ok", 20

21 "description": " 成功 ", "data": { "openid": "openid", "code": 0 错误返回如果访问令牌验证错误, 会返回错误信息, 返回格式为 Json 文本, 格式如下 : { "result": "error", "description": " 错误描述 ", "code": 错误码 5.4 验证用户密码接口 URL: HTTP 请求方式 :GET 请求参数 : 表 5-4 验证用户密码接口参数表名称必须范围说明 clientid True Long 申请应用时分配的 App Id xmuserid True Long 通过 5.1 接口获取到的 userid callback True String 完整的 url, 以 http 或 https 开头 ( 和 redirect url 在同一域名下面 ), 用于通知密码检测结果, 必须以 GET 方式访问 21

22 返回数据 : 返回数据是通过 callback 返回, callback url 中返回参数如下 : 名称必须范围说明 xmresult True Boolean xmresult:true 验证成功, false 或者没有改参数表示验证错误 _xmnonce _xmsign code xmuserid True String 由随机数和时间戳组成, 格式 : 随机数 : 当前分钟数 (1970 年 1 月 1 日午夜 0 点之间的时间差 ) True String 对返回结果的签名, 为了验证返回结果没有被窜改 True String 一个新的授权码, 第三方可以使用 code 换取新的 access token( 在安全性要求较高的地方可以再次用 access token 换取 userid, 以验证用户身份的合法性 ) True Long 小米验证的实际账号 ( 不一定是第三方传上来的账号 ), 可能会被人恶意窜改第三方必须在 callback 中验证 _ xmsign, 否则造成的损失由第三方负责如何验证签名 : Callback 格式参见请求内容标准化, 签名参数不包括 _xmnonce 和 _xmsign 签名签名算法使用 HmacSha1, AppSecret 是申请 app 的时候系统分配的可以, 可以登录获取, 每个用户不同,_xmSign = HmacSha1(Callback 字符串, AppSecret) 签名验证示例 : 第三方提供 Callback: 小米验证成功之后调用 callback: A6663C F68281E654D5526&_xmNonce= %3A23 22

23 226207&_xmSign=I3tMeKJcR25wg1re%2FiQ%2FZ5hYwyk%3D 其中 _xmnonce= : ,_xmsign= O044CQ9pBNgV3qgcVw760h3naNI=, 下面是部分代码示例 : String url = ""; URIBuilder followupbuilder = new URIBuilder(url); List<NameValuePair> resultparalist = new ArrayList<NameValuePair>(); Map<String, String> parameterthird = new HashMap<String, String>(); for (NameValuePair pair : followupbuilder.getqueryparams()) { if(!pair.getname().startswith("_")) { resultparalist.add(new BasicNameValuePair(pair.getName(), pair.getvalue())); parameterthird.put(pair.getname(), pair.getvalue()); Assert.assertEquals("true", parameterthird.get("xmresult")); Assert.assertNotNull(parameterThird.get("code")); String qs = URLEncodedUtils.format(resultParaList, Constants.UTF_8_CHARSET); String nonce = parameterthird.get("_xmnonce"); // 第三方需要 check 一下 nonce 防止重放 String sign =getmacaccesstokensignaturestring(nonce, "GET", followupbuilder.gethost(), followupbuilder.getpath(), qs, clientkey, "HmacSHA1"); Assert.assertEquals(sign, parameterthird.get("_xmsign")); 23

24 5.5 获取用户绑定的手机号码 URL: HTTP 请求方式 :GET 请求参数 : 表 5-5 获取用户名片参数表名称必须范围说明 clientid True Long 申请应用时分配的 App Id token True String 用户授权时 client 得到的 token Header 数据 : 参考第 4 节中方式生成 Header 授权信息返回数据 : 正确返回如果访问令牌验证通过, 会返回用户相关的信息, 返回格式为 Json 文本, 格式如下 : { "result": "ok", "description": " 成功 ", "data": { "phone": " 用户手机号, 无国家码默认为中国大陆 ",, "code": 0 如果用户没有绑定手机,phone 字段为空错误返回如果访问令牌验证错误, 会返回错误信息, 返回格式为 Json 文本, 格式如下 : { 24

25 "result": "error", "description": " 错误描述 ", "code": 错误码 25

目录 1. OAUTH 2.0 概述... 4 2. 授权接口说明... 6 2.1 授权流程说明... 6 2.1.1 授权码方式授权流程... 6 2.1.2 Implicit Grant 方式授权流程... 6 2.2 授权接口说明.

目录 1. OAUTH 2.0 概述... 4 2. 授权接口说明... 6 2.1 授权流程说明... 6 2.1.1 授权码方式授权流程... 6 2.1.2 Implicit Grant 方式授权流程... 6 2.2 授权接口说明. 小米帐户 OAuth 2.0 文档版本号 :1.3 更新日期 :2013-12-15 目录 1. OAUTH 2.0 概述... 4 2. 授权接口说明... 6 2.1 授权流程说明... 6 2.1.1 授权码方式授权流程... 6 2.1.2 Implicit Grant 方式授权流程... 6 2.2 授权接口说

目录 1. OAUTH 2.0 概述 授权接口说明 授权流程说明 授权码方式授权流程 Implicit Grant 方式授权流程 授权接口说明 请求用户授权接口

目录 1. OAUTH 2.0 概述授权接口说明授权流程说明授权码方式授权流程 Implicit Grant 方式授权流程授权接口说明请求用户授权接口