## spring-oauth-server V-0.5

说明: 本文档用于描述spring-oauth-server对外开发的接口(API)使用, 所有标记 public 的API都是公开的, 其他的API则需要获取 access_token 后可调用

- 获取access_token (grant_type=password)
- 获取access_token (grant_type=authorization_code)
- 获取access_token (grant_type=client_credentials)
- 获取access_token (Restful API)
- 刷新access_token (grant_type=refresh_token)
- 获取当前用户信息 (ROLE_UNITY)
- 获取当前用户信息 (ROLE_MOBILE)

### 获取access_token (grant_type=password) public

使用grant_type=password方式来获取access_token

- 请求URI: `/oauth/token` POST

  请求参数说明:

  参数名 | 参数值 | 必须? | 备注
  --- | --- | --- | ---
  client_id | {client_id} | 是 |
  client_secret | {client_secret} | 是 |
  grant_type | password | 是 | 固定值
  scope | {scope} | 是 | read or write
  username | {username} | 是 | 用户名
  password | {password} | 是 | 用户密码

  请求示例:

  `http://localhost:8080/spring-oauth-server/oauth/token?client_id=6361b08fdea6400f93b2eccda8936b32&client_secret=i4KXewMI0u6i8CFEZo10mB2rGzQRXrIv&grant_type=password&scope=read&username=mobile&password=mobile`

  响应

  - 正常 [200]
    {"access_token":"1f60abaf-6c3f-45a8-a574-bbbe6f76083f","token_type":"bearer","expires_in":41769,"scope":"read"}

  - 异常 [401]
    <oauth><error_description>Bad client credentials</error_description><error>invalid_client</error></oauth>

### 获取access_token (grant_type=authorization_code) public

使用grant_type=authorization_code 方式来获取access_token, 需要先获取code

- 请求URI: `/oauth/token` POST

  请求参数说明:

  参数名 | 参数值 | 必须? | 备注
  --- | --- | --- | ---
  client_id | {client_id} | 是 |
  client_secret | {client_secret} | 是 |
  grant_type | authorization_code | 是 | 固定值
  code | {code} | 是 |
  redirect_uri | {redirect_uri} | 是 |

  请求示例:

  `http://localhost:8080/spring-oauth-server/oauth/token?client_id=unity-client&client_secret=unity&grant_type=authorization_code&code=[code]&redirect_uri=[redirect_uri]`

  响应

  - 正常 [200]
    {"access_token":"2c612eb7-a22b-45f0-8b2e-cd6f9e366772","token_type":"bearer","refresh_token":"6c984bdc-01c7-486f-93bf-5637990d8a37","expires_in":43199,"scope":"read write"}

  - 异常 [401]
    {"error":"invalid_grant","error_description":"Invalid authorization code: vzmIh1"}

返回

### 获取access_token (grant_type=client_credentials) public

使用grant_type=client_credentials 方式来获取access_token, 不需要username, password

- 请求URI: `/oauth/token` POST

  请求参数说明:

  参数名 | 参数值 | 必须? | 备注
  --- | --- | --- | ---
  client_id | {client_id} | 是 |
  client_secret | {client_secret} | 是 |
  grant_type | client_credentials | 是 | 固定值
  scope | {scope} | 是 | read or write

  请求示例:

  `http://localhost:8080/spring-oauth-server/oauth/token?client_id=test1234&client_secret=test1234&grant_type=client_credentials&scope=read`

  响应

  - 正常 [200]
    {"access_token":"e5ea7620-5459-4d53-a7a0-6888bbb76f62","token_type":"bearer","expires_in":43199,"scope":"read"}

  - 异常 [401]
    <oauth><error_description>Bad client credentials</error_description><error>invalid_client</error></oauth>

### 获取access_token (Restful API) public

Restful API 获取access_token, 适用于grant_type为authorization_code,password,refresh_token,client_credentials

- 请求URI: `/oauth/rest_token` POST REST

  Content-Type: application/json

  请求Body参数说明:

  参数名 | 参数值 | 必须? | 备注
  --- | --- | --- | ---
  grant_type | {grant_type} | 是 | authorization_code,password,refresh_token,client_credentials
  scope | {scope} | 是 | read or write
  client_id | {client_id} | 是 |
  client_secret | {client_secret} | 是 |
  username | {username} | 否 | grant_type=password时必须有
  password | {password} | 否 | grant_type=password时必须有

  请求Body示例:

  `{"client_id":"test1234","client_secret":"test1234","grant_type":"password","scope":"read","username":"mobile","password":"mobile"}`

  或

  `{"client_id":"test1234","client_secret":"test1234","grant_type":"password","scope":"read"}`

  响应

  - 正常 [200]
    {"access_token":"e2996930-8398-44fd-8de5-7d1b1624ced7","token_type":"bearer","refresh_token":"2b2de701-53e7-4b57-8301-e4a06ee49698","expires_in":43008,"scope":"read"}

  - 异常 [401]
    {"error":"invalid_grant","error_description":"Bad credentials"}

返回

### 刷新access_token (grant_type=refresh_token) public

用于在access_token要过期时换取新的access_token (grant_type需要有refresh_token)

- 请求URI: `/oauth/token` POST

  请求参数说明:

  参数名 | 参数值 | 必须? | 备注
  --- | --- | --- | ---
  client_id | {client_id} | 是 |
  client_secret | {client_secret} | 是 |
  grant_type | refresh_token | 是 | 固定值
  refresh_token | {refresh_token} | 是 |

  请求示例:

  `http://localhost:8080/spring-oauth-server/oauth/token?client_id=test1234&client_secret=test1234&grant_type=refresh_token&refresh_token=1156ebfe-e303-4572-9fb5-4459a5d46610`

  响应

  - 正常 [200]
    {"access_token":"b12cace6-7ce4-4fa8-b127-cf537d15b213","token_type":"bearer","refresh_token":"2b2de701-53e7-4b57-8301-e4a06ee49698","expires_in":43199,"scope":"read"}

  - 异常 [401]
    {"error":"invalid_grant","error_description":"Invalid refresh token: 1156ebfe-e303-4572-9fb5-4459a5d46610"}

### 获取当前用户信息 (ROLE_UNITY)

使用access_token获取用户信息, 需要有 ROLE_UNITY 权限

- 请求URI: `/unity/user_info` GET

  请求参数说明:

  参数名 | 参数值 | 必须? | 备注
  --- | --- | --- | ---
  无

  请求示例:

  `http://localhost:8080/spring-oauth-server/unity/user_info?access_token=b12cace6-7ce4-4fa8-b127-cf537d15b213`

  响应

  - 正常 [200]
    {"guid":"55b713df1c6f423e842ad68668523c49","archived":false,"username":"unity","phone":"","email":"unity@wdcy.cc","privileges":["UNITY"]}

  - 异常 [401]
    <oauth><error_description>Invalid access token: 2c612eb7-a22b-45f0-8b2e-cd6f9e3667722</error_description><error>invalid_token</error></oauth>

返回

### 获取当前用户信息 (ROLE_MOBILE)

使用access_token获取用户信息, 需要有 ROLE_MOBILE 权限

- 请求URI: `/m/user_info` GET

  请求参数说明:

  参数名 | 参数值 | 必须? | 备注
  --- | --- | --- | ---
  无

  请求示例:

  `http://localhost:8080/spring-oauth-server/m/user_info?access_token=b12cace6-7ce4-4fa8-b127-cf537d15b213`

  响应

  - 正常 [200]
    {"guid":"612025cb3f964a64a48bbdf77e53c2c1","archived":false,"username":"mobile","phone":"","email":"mobile@wdcy.cc","privileges":["MOBILE"]}

  - 异常 [401]
    <oauth><error_description>Invalid access token: 2c612eb7-a22b-45f0-8b2e-cd6f9e3667722</error_description><error>invalid_token</error></oauth>

© 2013 - 2016 sz@monkeyk.com from spring-oauth-server