网页授权

准备工作

微哨登录是基于 OAuth 2.0 协议标准构建的第三方网站应用授权登录系统。用户在微哨门户中访问第三方网站时，网站应用可通过网页授权机制，获取用户基本信息，进而实现业务逻辑。

在进行微哨登录接入之前，开发者需要在微哨开放平台注册开发者帐号，并拥有一个已审核通过的网站应用，获得相应的 App Key 和 App Secret ；或者通过学校管理员创建校内应用，并获得相应的 App Key 和 App Secret 。获得上述信息后，即可开始接入流程的开发。

授权流程

微哨登录让用户使用微哨帐号安全登录第三方应用或网站。用户授权登录后，第三方可以获取到用户的接口调用凭证（ Access Token ），通过凭证可以进行微哨开放平台授权关系接口调用，从而实现获取用户的基础信息。

微哨登录基于 OAuth 2.0 Authorization Code 模式，适用于Web应用的授权登录。该模式整体流程为：

1. 第三方发起授权登录请求，用户允许授权第三方应用后，微哨登录会重定向到第三方网站，并且携带授权临时票据（ code 参数）。

2. 使用 code 参数，通过相关API换取 Access Token 。

3. 通过 Access Token 进行接口调用，获取用户基本数据资源或帮助用户实现基本操作。

第一步：请求code

第三方使用网站应用授权登录前请注意已获取相应网页授权作用域（scope=base_api）。通过跳转到如下链接，可发起对 code 票据的请求（使用我们的工具快速生成授权链接）：

https://api.weishao.com.cn/oauth/authorize?client_id=[AppKey]&redirect_uri=[urlEncode(应用回调地址)]&response_type=code&scope=base_api&state=xxx

结果

• 如果用户状态是未登录，转到授权登录页面。

  

  点击登录后，开发者填写的回调地址（ redirect_uri ）可得到如下参数：

  code=[code]&state=xxx

• 如果用户状态是已登录，浏览器会直接跳转到开发者填写的回调地址 redirect_uri ，并附带上述参数。

• 若提示“该链接无法访问”，请检查参数是否填写错误，如 redirect_uri 是否已进行 urlEncode 、其域名是否与管理平台填写的授权域名一致，scope 是否为 base_api 或 all 。

第二步：通过 code 换取网页授权 Access Token

需要注意的是，这里获得的 Access Token 仅能用于网页授权相关接口，与【高级API开发文档】中相关接口所需使用的 Access Token 不同，两者不可混用。此外，应用的 App Secret 和获取到的 Access Token 都具有很高的安全级别，必须只保存在服务器端，建议不要传递给客户端/页面前端。下面的刷新 Access Token 、获取用户信息等步骤也必须从服务器测发起。

• URL： https://api.weishao.com.cn/oauth/token
• 需要授权： 是
• 请求类型： HTTP POST
• 请求数据类型：Form表单（application/x-www-form-urlencoded） 或 JSON（application/json）

请求参数

• Form表单

  grant_type=authorization_code&client_id=[AppKey]&client_secret=[AppSecret]&code=[code]&redirect_uri=[urlEncode(应用回调地址)]
  

• JSON

  {
    "grant_type": "authorization_code",
    "client_id": "【App Key】",
    "client_secret": "【App Secret】",
    "code": "【code】",
    "redirect_uri": "【应用回调地址】" // 这里的地址不需要进行 urlEncode ,必须与第一步填写的“应用回调地址”保持一致
  }
  

• 参数说明

返回结果

• 正常

  {
    "access_token": "fDanz0ydkCqVsgSoze7mrCnwJIsN0dL",
    "expires_in": "1209600",
    "scope": "base_api",
    "refresh_token": "HhbiRKzjVnKdvGfmuGjvh3Clm4AIMqV8",
    "token_type": "Bearer"
  }
  

• 异常

  {
    "errcode": 40029,
    "errmsg": "invalid code"
  }
  

第三步：刷新 Access Token （如果需要）

由于 Access Token 拥有较短的有效期，当 Access Token 超时后，可以使用 Refresh Token 进行刷新。当 Refresh Token 失效之后，需要用户重新授权。

• URL： https://api.weishao.com.cn/oauth/token
• 需要授权： 是
• 请求类型： HTTP POST
• 请求数据类型：Form表单（application/x-www-form-urlencoded） 或 JSON（application/json）

请求参数

• Form表单

  grant_type=refresh_token&client_id=[AppKey]&client_secret=[AppSecret]&refresh_token=[RefreshToken]
  

• JSON

  {
    "grant_type": "refresh_token",
    "client_id": "【App Key】",
    "client_secret": "【App Secret】",
    "refresh_token": "【Refresh Token】"
  }
  

• 参数说明

返回结果

• 正常

  HTTP 200

  {
    "access_token": "xN2836yQAQfDURxVPds0IM9vfUk3IJC5",
    "expires_in": 604800,
    "scope": "demo",
    "refresh_token": "VFlAp82EUWNQJkokRvoELSPhPpO3pSPS",
    "token_type": "Bearer"
  }
  

第四步：获取用户信息

• URL： https://api.weishao.com.cn/profile?access_token=[AccessToken]
• 需要授权： 是
• 请求类型： HTTP GET

返回结果

• 正确

  {
    "name": "张三",
    "schoolcode": "ruijie",
    "student_number": "zhangsan",
    "sex": "boy",
    "photo_live": "http://store.weishao.com.cn///group1/M00/00/00/rBGoWlawRX6IbazWAALtCN376l4AAAAHA5mBBMAAu0g965.jpg",
    "mood_words": "",
    "nick_name": "",
    "organization_id": "234",
    "organization": "微哨大学",
    "uid": "099",
    "identity": "teacher",
    "wx_openid": "xxxxxxxx",
    "openid": "",
    "unionid": "",
    "schoolname": "微哨大学",
    "schoolicon_url": "http://store.weishao.com.cn//group1/M00/00/00/rBGoWlZ5Im2IAIb3AAAoqbZ4SkEAAAAGA4-VAEAACjB386.png"
  }
  

• 错误

  {
    "code": 401,//401/403/500,
    "data": "Unauthorized",
    "errno": "100401"//内部错误代码
  }
  

访问权限限制

访问级别：普通接口 频次限制：无

授权scope

base_api

注销流程

注销登录将会清除OAuth服务对应用的授权状态，用户再次进入应用时，需要重新授权。

• URL： https://api.weishao.com.cn/logout?return_uri=[urlEncode(回调地址)]
• 请求类型： HTTP GET

请求参数

返回结果

• 注销成功

  成功跳转到回调地址 return_uri 。如果未提供上述参数，则跳转到https://api.weishao.com.cn。

• 注销失败

  {
    "errcode": 500,
    "errmsg": "注销失败"
  }