授权流程

在网页应用内，授权流程如下图所示：

按照规则拼接授权页面的 URL 链接，并且引导用户跳转至该链接；

用户在授权页面上确认授权后，将跳转到开发者指定的回调页，并且带上 auth_code；

开发者通过 alipay.system.oauth.token（换取授权访问令牌接口），使用 auth_code 换取 access_token 及用户的 user_id；

如果需要除 user_id 以外的其他信息，则使用 access_token 调用 alipay.user.info.share（支付宝会员授权信息查询接口）获得用户信息。

第一步：URL 拼接

URL 拼接规则：https://openauth.alipay.com/oauth2/publicAppAuthorize.htm?app_id=APPID&scope=SCOPE&redirect_uri=ENCODED_URL

沙箱拼接规则详见关于沙箱。

URL 拼接中的参数说明：

参数名	是否必须	描述
app_id	是	开发者应用的 APPID
scope	是	接口权限值，目前只支持 auth_user 和 auth_base 两个值
redirect_uri	是	回调页面，是经过转义的url链接（url 必须以 http 或者 https 开头），比如：`http%3A%2F%2Fexample.com` 在请求之前，开发者需要先到开发者中心对应应用内，配置授权回调地址。
state	否	商户自定义参数，用户授权后，重定向到 redirect_uri 时会原样回传给商户。为防止 CSRF 攻击，建议开发者请求授权时传入 state 参数，该参数要做到既不可预测，又可以证明客户端和当前第三方网站的登录认证状态存在关联，并且不能有中文。说明：参数由用户自定义拼接，拼接完成后将参数进行 base64 转码。最后将参数拼接为 state=XXXXX 即可，最大长度 100 位。

注意：服务商代商家获取会员信息，用户信息实际还是授权给授权商家的，因此 URL 拼接链接需注意 app_id 和 redirect_uri：

app_id：授权商家的 APPID（即第三方应用授权返回 app_auth_token 对应的 auth_app_id）。

redirect_uri：授权商家应用中配置的授权回调地址。

关于 redirect_uri 的说明

redirect_uri 即授权回调地址，服务端接口会校验授权链接中配置的 redirect_uri 与应用中配置的授权回调地址（如下图所示）是否一致。

详细说明：

如果开发者在应用中配置的授权链接是：https://auth.example.com/authCallBack，则 redirect_uri 内容需要 encode 处理，为 https%3A%2F%2Fauth.example.com%2FauthCallBack。

授权回调地址对应的域名（auth.example.com）下的页面 http://auth.example.com/authCallBack、https://auth.example.com/authRedirect、https://auth.example.com/ 都可以进行 OAuth2.0 授权。但与（auth.example.com）关联的二三级域名，如：http://www.example.com/、http://example.com/ 无法进行 OAuth2.0 授权。

关于 scope 的说明

scopes	描述	包含的服务端 API 接口
auth_base	静默授权，不会发起授权浮窗，用户授权并自动跳转到回调页。用户感知为直接进入回调页面（通常是业务页面）。在支付宝客户端获取 auth_code，仅可用于 alipay.system.oauth.token（换取授权访问令牌接口）获取支付宝会员标识（user_id）。	alipay.system.oauth.token
auth_user	主动授权，需要用户手动点击同意，用户同意后可获取用户的基本信息的（比如头像、昵称等），用于网站支付宝登录和获取用户信息。	alipay.system.oauth.token alipay.user.info.share

PC 网页内授权页面示例：

第二步：获取 auth_code

当用户授权成功后，会跳转至开发者定义的回调页面，支付宝会在回调页面请求中加入参数，包括 auth_code、app_id、scope 等，需要注意的是支付宝仅保证 auth_code、app_id 以及 scope 参数的有效性。支付宝请求开发者回调页面示例如下：

http : //example.com/doc/toAuthPage.html?app_id=2014101500013658&source=alipay_wallet&scope=auth_user&auth_code=ca34ea491e7146cc87d25fca24c4cD11

术语解释

auth_code：临时授权码，一次有效，auth_code 有效期为 3 分钟到 24 小时（开放平台规则会根据具体的业务场景动态调整 auth_code 的有效期，但是不会低于 3 分钟，同时也不会超过 24 小时），超过有效期的 auth_code 即使未使用也将无法使用。用户的每次授权动作都会生成一个新的 auth_code。

第三步：换取 access_token 和 userId

得到 auth_code 后，开发者通过 alipay.system.oauth.token（换取授权访问令牌接口），使用 auth_code 换取 access_token 及用户的 user_id。auth_code 作为换取 access_token 的凭证，每次用户授权完成后，返回参数中的 auth_code 将不一样，auth_code 只能使用一次，24 小时内未被使用自动过期。

注意： alipay.system.oauth.token（换取授权访问令牌接口）的返回值 alipay_user_id 已废弃，请勿使用，需要获取的 userId 值为返回值中的 user_id 。

接口请求示例

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipaySystemOauthApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipaySystemOauthApiToken {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipaySystemOauthApi api = new AlipaySystemOauthApi();
        AlipaySystemOauthTokenModel data = new AlipaySystemOauthTokenModel();
        data.setCode("4b203fe6c11548bcabd8da5bb087a83b");
        data.setGrantType("authorization_code");
        data.setRefreshToken("201208134b203fe6c11548bcabd8da5bb087a83b");
        try {
            AlipaySystemOauthTokenResponseModel response = api.token(data);
        } catch (ApiException e) {
            AlipaySystemOauthTokenDefaultResponse errorObject = (AlipaySystemOauthTokenDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

请求参数说明

参数	参数名称	类型（长度范围）	参数说明	是否可为空	样例
grant_type	授权类型	String	值为authorization_code 时，代表用 code 换取；值为 refresh_token 时，代表用 refresh_token 换取	不可空	authorization_code
code	授权码	String	用户对应用授权后得到，即第二步中开发者获取到的 auth_code 值	与 refresh_token 二选一	4b203fe6c11548bcabd8da5bb087a83b
refresh_token	刷新令牌	String	刷新access_token时使用	与 code 二选一	201208134b203fe6c11548bcabd8da5bb087a83b

同步响应结果示例

{
    "access_token":"20120823ac6ffaa4d2d84e7384bf983531473993",
    "refresh_token":"20120823ac6ffdsdf2d84e7384bf983531473993",
    "user_id":"2088102150477652",
    "re_expires_in":"3600",
    "auth_start":"2010-11-11 11:11:11",
    "expires_in":"3600"
}

同步响应参数说明

参数	参数名称	类型（长度范围）	参数说明	是否可为空	样例
access_token	交换令牌	String	用于获取用户信息	不可空	publicpBa869cad0990e4e17a57ecf7c5469a4b2
user_id	用户的 userId	String	支付宝用户的唯一 userId	不可空	2088102104711111
expires_in	令牌有效期	String	交换令牌的有效期，单位秒	不可空	300
re_expires_in	刷新令牌有效期	String	刷新令牌有效期，单位秒	不可空	300
refresh_token	刷新令牌	String	通过该令牌可以刷新 access_token	不可空	publicpB0ff17e364f0743c79b0b0d7f55e20bfc

第四步：获取用户信息

开发者在获取了用户的 user_id 后，如果想获取头像、昵称、省份等其他信息，需要调用 alipay.user.info.share（支付宝会员授权信息查询接口）。

接口请求示例

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayUserInfoApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayUserInfoApiShare {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayUserInfoApi api = new AlipayUserInfoApi();
        String authToken = null;
        try {
            AlipayUserInfoShareResponseModel response = api.share(authToken);
        } catch (ApiException e) {
            AlipayUserInfoShareDefaultResponse errorObject = (AlipayUserInfoShareDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

公共请求参数说明

参数	参数名称	类型（长度范围）	参数说明	是否可为空	样例
auth_token	授权令牌	String	通过auth_code获取的access_token	不可空	publicpB9ea460ff5b5c468c9ccf5e967dc34963

同步响应结果示例

{
    "province":"安徽省",
    "gender":"F",
    "user_id":"2088102104794936",
    "city":"安庆",
    "nick_name":"支付宝小二",
    "avatar":"http://tfsimg.alipay.com/images/partner/T1uIxXXbpXXXXXXXX"
}

同步响应参数说明

参数	参数名称	类型（长度范围）	参数说明	样例
user_id	支付宝用户id	String	支付宝用户的会员 ID，2088 开头的 16 位数字。	2088102104794936
avatar	用户头像	String	如果没有数据（用户未设置）时不会返回该信息，请做好容错。	https://tfsimg.alipay.com/images/partner/T1k0xiXXRnXXXXXXXX
nick_name	用户昵称	String	如果没有数据（用户未设置）时不会返回该信息，请做好容错。	张三

结果码说明

同步返回结果码	含义	说明
10000	业务处理成功
40001～40006	业务处理失败	具体失败原因请参考公共错误码。其它请参考 API 文档。
20000	业务出现未知错误或者系统异常	业务出现未知错误或者系统异常（请一定在确定本次调用结果后，发起重试），可调用查询接口发起查询确定结果。

消息通知

商家/服务商创建、修改及用户领取商家券等场景，支付宝都将通过 From 蚂蚁消息通知向商家应用或第三方应用应用网关推送异步通知消息，同步对应操作结果。

若商家/服务商网络环境比较复杂，如：通过统一网关间连互联网，推荐使用网络兼容性更好的标准 http(s) 协议进行对接。

第一步：订阅消息

当用户取消用户信息授权时，支付宝将通过 alipay.open.auth.userauth.cancelled（用户授权取消消息接口），发送此消息给被授权方。商家/服务商需根据订阅消息指引，为接入的应用订阅如下消息接口。

**注意：**仅完成订阅后才会收到支付宝发送的对应异步通知消息。

第二步：验签

商家/服务商可使用支付宝 SDK 可根据使用生成密钥验签指引，使用应用密钥信息验证异步通知消息来源是否为支付宝。

第三步：反馈消息接收结果

收到异步通知完成验签后，商家/服务商需返回 success 表示消息获取成功，支付宝就会停止发送异步通知。如果返回 fail 或其他值，表示消息获取失败，支付宝会根据投递重试策略重新发送消息到应用网关地址。

**说明：**完成异步通知验签时，如果验签成功返回 success，验签失败返回 fail，重新接收异步进行处理。

响应值	描述	是否重试
fail	消息获取失败	重试
success	消息获取成功	不重试

用户授权取消消息通知

用户取消用户信息授权时，支付宝将通过 alipay.open.auth.userauth.cancelled（用户授权取消消息接口），发送此消息给被授权方。

消息示例

ISV_GATEWAY_URL?charset=GBK&biz_content=
{
"app_id":"2014072300007148","user_id":"2088102104711111","cancel_time":"1514210452731"
}
&msg_method=alipay.open.auth.userauth.cancelled&utc_timestamp=1516797622752&version=1.1&sign_type=RSA2&notify_id=d275fec564e62af6bedbcee73f3f05fi5x&app_id=2013121700999429&sign=I+Y/lvqYUEEc10EPdpntRhFIQ==

接入沙箱

沙箱是开放平台提供给开发者用户调试接口的环境，具体操作步骤见沙箱接入指南。

接入注意点

获取用户信息支持沙箱接入；在沙箱调通接口后，必须在线上进行测试与验收，所有返回码及业务逻辑以线上为准；

沙箱授权 url 链接拼接规则为：

https://openauth-sandbox.dl.alipaydev.com/oauth2/publicAppAuthorize.htm?app_id=APPID&scope=SCOPE&redirect_uri=ENCODED_URL

。

PC 网页内获取用户信息

授权流程#

第一步：URL 拼接#

关于 redirect_uri 的说明#

关于 scope 的说明#

PC 网页内授权页面示例：#

第二步：获取 auth_code#

术语解释#

第三步：换取 access_token 和 userId#

接口请求示例#

请求参数说明#

同步响应结果示例#

同步响应参数说明#

第四步：获取用户信息#

接口请求示例#

公共请求参数说明#

同步响应结果示例#

同步响应参数说明#

结果码说明#

消息通知#

第一步：订阅消息#

第二步：验签#

第三步：反馈消息接收结果#

用户授权取消消息通知#

消息示例#

接入沙箱#

授权流程

第一步：URL 拼接

关于 redirect_uri 的说明

关于 scope 的说明

PC 网页内授权页面示例：

第二步：获取 auth_code

术语解释

第三步：换取 access_token 和 userId

接口请求示例

请求参数说明

同步响应结果示例

同步响应参数说明

第四步：获取用户信息

接口请求示例

公共请求参数说明

同步响应结果示例

同步响应参数说明

结果码说明

消息通知

第一步：订阅消息

第二步：验签

第三步：反馈消息接收结果

用户授权取消消息通知

消息示例

接入沙箱