获取游云南用户授权

准备工作

游云南开放能力用户授权是基于OAuth2.0 协议标准构建的授权登录系统

在进行游云南开放能力用户授权登录接入之前，需要在游云南开放平台注册开发者帐号，在应用管理新增第三方应用，并获得相应的 AppID 和 AppSecret。在应用信息详情页内的开放能力列表中申请开通能力授权且管理员通过审核后，可开始接入流程。

1. 目前应用仅支持微信小程序类应用的建立；用户需要登录游云南官方小程序后才可以为第三方应用授权
2. 微信小程序类应用的建立需要提供小程序Id（以wx开头）和小程序原始Id（以gh开头）
3. 目前申请开通能力授权仅支持线下与管理员沟通的方式，由管理员进行开通

授权流程说明

游云南开放能力用户授权让已经是游云南的用户使用游云南身份在第三方应用中获取官方提供的开放能力，用户在第三方应用中唤起游云南官方应用并同意开放能力的授权使用后，第三方应用可以获取到临时票据code，进而获取用户的接口调用凭证（access_token），通过 access_token 可以进行游云南开放能力的接口调用。

游云南开放能力用户授权目前支持 authorization_code 模式，适用于拥有 server 端的应用授权。该模式整体流程为：

1. 第三方应用向游云南应用发起授权请求，游云南用户允许授权第三方应用后，游云南应用会拉起第三方应用，并且返回授权临时票据code参数；
2. 通过code参数加上AppID和AppSecret等，通过API换取access_token；
3. 通过access_token进行接口调用，获取游云南开放能力数据。

授权流程时序图：

第一步：获取临时票据code

开发者需要配合使用游云南开放平台提供的 SDK 进行授权请求接入。引入 SDK 并拥有想要接入的能力授权域（scope）权限后，开发者应用会拉起游云南应用进行能力授权域和应用基本信息的校验，校验通过后向用户申请授权，用户确认后游云南应用将拉起开发者应用，并返回授权临时票据（code）。

微信小程序接入代码示例

/* 伪代码 */
import YynOpenSdk from 'path/to/yyn_open_sdk.js'
const sdk = new YynOpenSdk({ appid: '当前应用在开放平台的Appid' })

// 唤起授权，此时会拉起游云南官方小程序原生授权页
sdk.callMpAuth('scope1,scope2,scope3...')

// 监听回调
// 在App.onShow()中监听，也可以用wx.onShow()的api
App({
  onShow(options) {
    if (options.referrerInfo && options.referrerInfo.appId) {
      try {
        const code = await yynOpenSdk.onMpAuthed(referrerInfo)
        if (code) {
          // 传递给后端服务
        }
      } catch(e) {
        console.error(e)
      }
    }
  }
})

游云南小程序内嵌web应用接入代码实例

/* 伪代码 */
import YynOpenSdk from 'path/to/yyn_open_sdk.js'
const sdk = new YynOpenSdk({ appid: '当前应用在开放平台的Appid' })

// 唤起授权，此时会拉起游云南官方小程序原生授权页
sdk.callMpAuthInWeb('scope1,scope2,scope3...', )
// 可以设置官方小程序授权后跳转回的第三方路径
// sdk.callMpAuthInWeb('scope1,scope2,scope3...', 'custom redirectUri')

// 监听回调
window.addEventListener('DOMContentLoaded', () => {
  const code = sdk.onMpAuthedInWeb()
})

第三方小程序、第三方内嵌Web应用(内嵌游云南小程序)接入sdk的具体说明请查看游云南开放平台js-sdk使用指南

第二步：通过code获取access_token

获取access_token

第三方服务获取到第一步的code后，通过GET请求以下链接获取access_token：

https://open-api.ybsjyyn.com/api/oauth2/access_token?appid=APPID&secret=SECRET&code=CODE&grant_type=authorization_code

请求参数：

参数	是否必须	说明
appid	是	应用唯一标识，在游云南开放平台提交应用审核通过后获得
secret	是	应用密钥AppSecret，在游云南开放平台提交应用审核通过后获得
code	是	填写第一步获取的 code 参数
grant_type	是	填 authorization_code 字符串

返回参数：

参数	说明
data.access_token	接口调用凭证
data.expires_in	access_token 接口调用凭证超时时间，单位（秒）
data.refresh_token	用户刷新 access_token
data.openid	授权用户唯一标识
data.scope	用户授权的作用域，使用逗号（,）分隔
data.unionid	当且仅当该应用已获得该用户的 userinfo 授权时，才会出现该字段
errorcode	错误编码
msg	错误信息
ret	0-成功，1-失败

正确的返回

{
  "ret": 0,
  "msg": "success",
  "errorcode": 0,
  "data": {
    "access_token": "ACCESS_TOKEN",
    "expires_in": 7200,
    "refresh_token": "REFRESH_TOKEN",
    "openid": "OPENID",
    "scope": "SCOPE",
    "unionid": "UNIONID"
  },
}

错误的返回

{
  "ret": 1,
  "msg": "错误的scope",
  "errorcode": 51003
}

刷新access_token有效期

access_token 是调用授权关系接口的调用凭证，由于 access_token 有效期（目前为 2 个小时）较短，当 access_token 超时后，可以使用 refresh_token 进行刷新，access_token 刷新结果有两种：

1. 若access_token已超时，那么进行refresh_token会获取一个新的access_token，新的超时时间；
2. 若access_token未超时，那么进行refresh_token不会改变access_token，但超时时间会刷新，相当于续期access_token。

refresh_token 拥有较长的有效期（30 天），当 refresh_token 失效的后，需要用户重新授权。

获取第一步的 code 后，通过GET请求以下链接进行 refresh_token：

https://open-api.ybsjyyn.com/api/oauth2/refresh_token?appid=APPID&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

请求参数：

参数	是否必须	说明
appid	是	应用唯一标识，在游云南开放平台提交应用审核通过后获得
refresh_token	是	填写通过 /access_token接口 获取到的 refresh_token 参数
grant_type	是	填 refresh_token

返回参数：

参数	说明
data.access_token	接口调用凭证
data.expires_in	access_token 接口调用凭证超时时间，单位（秒）
data.refresh_token	用户刷新 access_token
data.openid	授权用户唯一标识
data.scope	用户授权的作用域，使用逗号（,）分隔
data.unionid	当且仅当该应用已获得该用户的 userinfo 授权时，才会出现该字段
errorcode	错误编码
msg	错误信息
ret	0-成功，1-失败

正确的返回

{
  "ret": 0,
  "msg": "success",
  "errorcode": 0,
  "data": {
    "access_token": "ACCESS_TOKEN",
    "expires_in": 7200,
    "refresh_token": "REFRESH_TOKEN",
    "openid": "OPENID",
    "scope": "SCOPE",
  },
}

错误的返回

{
  "ret": 1,
  "msg": "错误的refresh_token",
  "errorcode": 51006
}

注意：

1. Appsecret 是应用接口使用密钥，泄漏后将可能导致应用数据泄漏、应用的用户数据泄漏等高风险后果；存储在客户端，极有可能被恶意窃取（如反编译获取Appsecret）；
2. access_token 为用户授权第三方应用发起接口调用的凭证（相当于用户登录态），存储在客户端，可能出现恶意获取access_token后导致的用户数据泄漏、用户微信相关接口功能被恶意发起等行为；
3. refresh_token 为用户授权第三方应用的长效凭证，仅用于刷新access_token，但泄漏后相当于access_token泄漏，风险同上。

第三步：通过access_token调用接口

使用第三步获取到的access_token和openid请求游云南开放能力业务接口。

获取access_token后，进行接口调用，有以下前提：

1. access_token有效且未超时；
2. 第三方应用想要使用的开发能力已在开放平台被授权；
3. 用户在游云南应用中同意授权给第三方应用相应能力授权域（scope）。

游云南开放能力业务接口出入参的详细内容请查看相应的接口文档。

F.A.Q

1. 什么是授权临时票据（code）？

答：第三方通过code进行获取access_token的时候需要用到，code的超时时间为10分钟，一个code只能成功换取一次access_token即失效。code的临时性和一次保障了微信授权登录的安全性。第三方可通过使用https和state参数，进一步加强自身授权登录的安全性。

2. 什么是能力授权域（scope）？

答：能力授权域（scope）代表用户授权给第三方的接口权限，第三方应用需要向游云南开放平台申请使用相应scope的权限后，使用文档所述方式让用户进行授权，经过用户授权，获取到相应access_token后方可对接口进行调用。

3. 什么是内嵌Web应用？

答：内嵌Web应用