主题
开发指南
准备工作
网站应用登录是基于OAuth2.0协议标准构建的OAuth2.0授权登录系统。 在进行Ksuser OAuth2.0授权登录接入之前，在Ksuser开放平台注册开发者账号，并拥有一个已审核通过的网站应用，并获得相应的AppID和AppSecret，申请Ksuser登录且通过审核后，可开始接入流程。
授权流程说明
Ksuser OAuth2.0授权登录让Ksuser用户使用Ksuser身份安全登录第三方应用或网站，在Ksuser用户授权登录已接入Ksuser OAuth2.0的第三方应用后，第三方可以获取到用户的接口调用凭证（access_token），通过access_token可以进行Ksuser开放平台授权关系接口调用，从而可实现获取Ksuser用户基本开放信息和帮助用户实现基础开放功能等。 Ksuser OAuth2.0授权登录目前支持authorization_code模式，适用于拥有server端的应用授权。该模式整体流程为：
流程
- 第三方发起Ksuser授权登录请求，Ksuser用户允许授权第三方应用后，Ksuser会拉起应用或重定向到第三方网站，并且带上授权临时票据code参数；
- 通过code参数加上AppID和AppSecret等，通过API换取access_token；
- 通过access_token进行接口调用，获取用户基本数据资源或帮助用户实现基本操作。
第一步：请求CODE
第三方使用网站应用授权登录前请注意已获取相应网页授权作用域（scope=snsapi_login），则可以通过在PC端打开以下链接：https://auth.ksuser.cn/oauth2/connect?appid=APPID&redirect_uri=REDIRECT_URI&response_type=code&scope=SCOPE&state=STATE，若提示“该链接无法访问”，请检查参数是否填写错误，如redirect_uri的域名与审核时填写的授权域名不一致或scope不为snsapi_login。
参数说明
| 参数 | 必选 | 说明 |
|---|---|---|
| appid | 是 | 应用唯一标识 |
| redirect_uri | 是 | 授权后重定向的回调链接地址，请使用urlencode对链接进行处理，且需要与审核时填写的授权域名一致 |
| response_type | 是 | 返回类型，请填写code |
| scope | 是 | 应用授权作用域，目前仅填写snsapi_login |
| state | 否 | 重定向后会带上state参数，开发者可以填写a-zA-Z0-9的参数值，最多128字符，重定向后会原样带回给第三方。该参数可用于防止CSRF攻击（跨站请求伪造攻击），建议第三方带上该参数，并进行校验。 |
返回说明
用户允许授权后，将会重定向到redirect_uri的网址上，并且带上code和state参数：redirect_uri?code=CODE&state=STATE 若用户禁止授权，则不会发生重定向。
请求示例
开发你的网站应用登录页：https://test.example.com/ksuser/login（这里仅是示例，非真实可访问的网站） 在此页面中，用户点击登录后，生成state参数，跳转至下方页面（按照上面文档的指引拼接 url 参数） https://auth.ksuser.cn/oauth2/connect?appid=APPID&redirect_uri=REDIRECT_URI&response_type=code&scope=SCOPE&state=STATE Ksuser用户使用Ksuser扫描二维码并且确认登录后，PC端会跳转到上述 redirect_uri 配置的地址 https://test.example.com/ksuser/callback.do?code=CODE&state=STATE
第二步：通过code获取access_token
通过code获取access_token https://api.ksuser.cn/oauth2/access_token?appid=APPID&secret=SECRET&code=CODE&grant_type=authorization_code
参数说明
| 参数 | 必选 | 说明 |
|---|---|---|
| appid | 是 | 应用唯一标识 |
| secret | 是 | 应用密钥，即AppSecret |
| code | 是 | 第一步获取的code参数 |
| grant_type | 是 | 授权类型，请填写authorization_code |
返回说明
正确的返回：
json
{
"access_token":"ACCESS_TOKEN",
"expires_in":7200,
"refresh_token":"REFRESH_TOKEN",
"openid":"OPENID",
"scope":"SCOPE"
}参数说明
| 参数 | 说明 |
|---|---|
| access_token | 接口调用凭证，注意：access_token拥有较短的有效期 |
| expires_in | access_token接口调用凭证超时时间，单位（秒） |
| refresh_token | 用户刷新access_token，获取新的access_token。注意：refresh_token拥有较长的有效期（7天），当access_token超时后，可以使用refresh_token进行刷新，refresh_token每天只能使用一次，重复使用会导致refresh_token失效。 |
| openid | 授权用户唯一标识，注意：在同一应用中，openid唯一标识一个用户。对于不同应用（同一开放平台账号下），同一用户的openid不同。 |
| scope | 用户授权的作用域，使用逗号（,）分隔 |
错误返回示例
json
{
"code":40029,
"msg":"invalid code"
}刷新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后，请求以下链接进行refresh_token：https://api.ksuser.cn/oauth2/refresh_token?appid=APPID&grant_type=refresh_token&refresh_token=REFRESH_TOKEN
参数说明
| 参数 | 必选 | 说明 |
|---|---|---|
| appid | 是 | 应用唯一标识 |
| grant_type | 是 | 授权类型，请填写refresh_token |
| refresh_token | 是 | 通过access_token获取到的refresh_token |
返回说明
正确的返回：
json
{
"access_token":"ACCESS_TOKEN",
"expires_in":7200,
"refresh_token":"REFRESH_TOKEN",
"openid":"OPENID",
"scope":"SCOPE"
}参数说明
| 参数 | 说明 |
|---|---|
| access_token | 接口调用凭证，注意：access_token拥有较短的有效期 |
| expires_in | access_token接口调用凭证超时时间，单位（秒） |
| refresh_token | 用户刷新access_token，获取新的access_token。注意：refresh_token拥有较长的有效期（7天），当access_token超时后，可以使用refresh_token进行刷新，refresh_token每天只能使用一次，重复使用会导致refresh_token失效。 |
| openid | 授权用户唯一标识，注意：在同一应用中，openid唯一标识一个用户。对于不同应用（同一开放平台账号下），同一用户的openid不同。 |
| scope | 用户授权的作用域，使用逗号（,）分隔 |
错误返回示例
json
{
"code": 40030,
"msg": "invalid refresh_token"
}注意
- Appsecret 是应用接口使用密钥，泄漏后将可能导致应用数据泄漏、应用的用户数据泄漏等高风险后果；存储在客户端，极有可能被恶意窃取（如反编译获取Appsecret）；
- access_token 为用户授权第三方应用发起接口调用的凭证（相当于用户登录态），存储在客户端，可能出现恶意获取access_token 后导致的用户数据泄漏、用户微信相关接口功能被恶意发起等行为；
- refresh_token 为用户授权第三方应用的长效凭证，仅用于刷新access_token，但泄漏后相当于access_token 泄漏，风险同上；
- 如无特别业务需求，建议开发者自行管理业务登录态并合理设置过期时间，减少用户重新授权登录次数，优化用户体验。
- 建议将secret、用户数据（如access_token）放在App云端服务器，由云端中转接口调用请求
第三步：通过access_token调用接口
获取access_token后，进行接口调用，有以下前提：
- access_token有效且未超时；
- 用户已授权给第三方应用账号相应接口作用域（scope）。
对于接口作用域（scope），能调用的接口有以下：
| 授权作用域 | 接口 | 接口说明 |
|---|---|---|
| snsapi_base | /oauth2/sns/oauth2/access_token | 通过code换取access_token、refresh_token和已授权scope |
| snsapi_base | /oauth2/sns/oauth2/refresh_token | 刷新或续期access_token使用 |
| snsapi_login | /oauth2/sns/get_openid | 获取用户openid接口 |
| snsapi_userinfo | /oauth2/sns/get_user_info | 获取用户基本信息接口 |
其中snsapi_base属于基础接口，若应用已拥有其它scope权限，则默认拥有snsapi_base的权限。使用snsapi_base可以让移动端网页授权绕过跳转授权登录页请求用户授权的动作，直接跳转第三方网页带上授权临时票据（code），但会使得用户已授权作用域（scope）仅为snsapi_base，从而导致无法获取到需要用户授权才允许获得的数据和基础功能。