==============================
mge-oauth2-授权服务接入指南
==============================
为了方便第三方应用接入 MGEDATA 数据存储平台，我们开发小组在 MGE 平台集成了 OAuth2 授权服务。
相关授权、认证流程完全遵循 OAuth2.0 标准，这里不再赘述原理与运行流程，
不了解的可以看 RFC 6749 对 OAuth2.0 标准的定义，或者看中文版的介绍：阮一峰 - 理解OAuth 2.0。
应用申请
--------
进入 https://www.mgedata.cn/oauth2/applications ，点击“点击此处”添加应用。
已经添加过的直接点击 “new application” 按钮。
.. image:: https://s1.ax1x.com/2018/07/22/PGypuD.png
填写应用名称，client type 选择 confidential，授权类型按需选择。
ridirect uris 填写回调的 uri 地址（仅这些注册过的地址有效）。
.. image:: https://s1.ax1x.com/2018/07/22/PGy9De.png
点击保存应用即可。
相关接口简单说明
----------------
**授权相关**
+----------------+--------------------------------+------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| / | url | 方法 | 参数 | 说明 |
+================+================================+======+===============================================================================================================================================================================================================================+=============================================================================================================================================================================+
| **base url** | https://www.mgedata.cn/oauth2/ | | | 后面的 url 都应该接在他后面 |
+----------------+--------------------------------+------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **申请认证** | /authorize/ | GET | **response\_type:** 授权类型
**client\_id**: 客户端 ID
**redirect\_uri**: 重定向 uri
**scope**: 申请的权限范围，目前有 read, write 两种，默认值也为这两种
**state**: 客户端状态 | 申请认证，用户登录授权成功之后会跳转到重定向uri，
携带 access\_token 和 state（如果有，建议设置，为了安全） 参数。
code 有效期只有 60s。 成功之后再去请求token。 |
+----------------+--------------------------------+------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **请求 token** | /token/ | POST | **grant\_type**: 授权类型，跟申请 client\_id 时候选择的一致
**client\_id**: 客户端 ID
**client\_secret**: 客户端密钥
**code**: 上一步中得到的授权码
**redirect\_uri**: 重定向 uri，跟上一步中应该一致 | 请求 token。 |
+----------------+--------------------------------+------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **刷新 token** | /token/ | POST | **grant\_type**: refresh_token
**token**: 前面获取到的 token | 刷新 token。 |
+----------------+--------------------------------+------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **撤销 token** | /revoke\_token/ | POST | **token**: 前面获取到的 token
**client\_id**: 客户端 ID
**client\_secret**: 客户端密钥（在confidential模式需要） | 撤销 token。 |
+----------------+--------------------------------+------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
获取用户信息
--------------
**描述**：提供模板 id ，填写该模板对应的数据，并上传。
**方法与接口**：
```
https://www.mgedata.cn/api/v1/account/o/user/info
```
**权限**：已登录用户
**参数**：
- HEADER 部分
+---------------+--------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| 字段 | 类型 | 描述 |
+===============+========+===================================================================================================================================================+
| Authorization | String | 认证信息，在通过 oauth 获取了 access\_token 之后，将 access\_token 置于此字段，
Bearer 类型，例如：**Bearer Af8TR1HAmgog19BdmR99vrzEuDEG9a** |
+---------------+--------+---------------------------------------------------------------------------------------------------------------------------------------------------+
- 返回值
+------------------+---------+-----------------------------------------------------------------------------------------------+
| 字段 | 类型 | 描述 |
+==================+=========+===============================================================================================+
| code | umber | 错误码，0为成功 |
+------------------+---------+-----------------------------------------------------------------------------------------------+
| data | Object | 具体用户信息 |
+------------------+---------+-----------------------------------------------------------------------------------------------+
| data.username | String | 用户名，**唯一** |
+------------------+---------+-----------------------------------------------------------------------------------------------+
| data.nickname | String | 昵称 |
+------------------+---------+-----------------------------------------------------------------------------------------------+
| data.email | String | 邮箱，**唯一** |
+------------------+---------+-----------------------------------------------------------------------------------------------+
| data.sex | String | 性别，有 M, F, U 三个枚举值，分别表示 男、女、为设置 |
+------------------+---------+-----------------------------------------------------------------------------------------------+
| data.avatar | String | 头像地址，文件后缀部分除了 lg 之外还可以是 nm 或 sm，大小分别为 200\*200，100\*100，30\*30 |
+------------------+---------+-----------------------------------------------------------------------------------------------+
| data.tel | String | 手机号 |
+------------------+---------+-----------------------------------------------------------------------------------------------+
| data.institution | String | 所属机构 |
+------------------+---------+-----------------------------------------------------------------------------------------------+
| data.is\_active | Boolean | 是否有效（有些垃圾用户可能会系统置为无效或非法用户可能被拉黑，为 false 时不应存储该用户信息） |
+------------------+---------+-----------------------------------------------------------------------------------------------+
*注：data 字段即为返回的用户信息所有字段，其中 username 和 email 两个字段均为唯一标识，第三方可用任意一个标识用户。*
- 示例返回值
::
{
"code": 0,
"data": {
"username": "test",
"nickname": "test",
"email": "test@mge.cn",
"sex": "U",
"avatar": "https://www.mgedata.cn/media/avatars/default_lg.jpg",
"tel": "",
"institution": "",
"is_active": true
}
}