2 第一步：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 位。

详细说明：

如果开发者在应用中配置的授权链接是： 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 授权。

2.2 关于 scope 的说明

scopes

描述

包含的服务端 API 接口

auth_base

静默授权，不会发起授权浮窗，用户授权并自动跳转到回调页。用户感知为直接进入回调页面（通常是业务页面）。

在支付宝客户端获取 auth_code，仅可用于 alipay.system.oauth.token （换取授权访问令牌接口）获取支付宝会员标识（user_id）。

alipay.system.oauth.token

auth_user

主动授权，需要用户手动点击同意，用户同意后可获取用户的基本信息（比如头像、昵称等），用于 网站支付宝登录 和 获取用户信息 。

3 第二步：获取 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

3.1 术语解释

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

4 第三步：换取 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 。

4.1 接口请求示例

接口调用示例，以 JAVA 语言为例：

package com.java.sdk.demo;
import com.alipay.api.AlipayApiException;
import com.alipay.api.AlipayClient;
import com.alipay.api.DefaultAlipayClient;
import com.alipay.api.AlipayConfig;
import com.alipay.api.response.AlipaySystemOauthTokenResponse;
import com.alipay.api.request.AlipaySystemOauthTokenRequest;
import com.alipay.api.FileItem;
import java.util.Base64;
import java.util.ArrayList;
import java.util.List;
public class AlipaySystemOauthToken {
    public static void main(String[] args) throws AlipayApiException {
        // 初始化SDK
        AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig());
        // 构造请求参数以调用接口
        AlipaySystemOauthTokenRequest request = new AlipaySystemOauthTokenRequest();
        // 设置刷新令牌
        request.setRefreshToken("201208134b203fe6c11548bcabd8da5bb087a83b");
        // 设置授权码
        request.setCode("4b203fe6c11548bcabd8da5bb087a83b");
        // 设置授权方式
        request.setGrantType("authorization_code");
        AlipaySystemOauthTokenResponse response = alipayClient.execute(request);
        System.out.println(response.getBody());
        if (response.isSuccess()) {
            System.out.println("调用成功");
        } else {
            System.out.println("调用失败");
            // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接
            // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response);
            // System.out.println(diagnosisUrl);
    private static AlipayConfig getAlipayConfig() {
        String privateKey  = "<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->";
        String alipayPublicKey = "<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->";
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey(privateKey);
        alipayConfig.setFormat("json");
        alipayConfig.setAlipayPublicKey(alipayPublicKey);
        alipayConfig.setCharset("UTF-8");
        alipayConfig.setSignType("RSA2");
        return alipayConfig;
    REQUEST   URL :  https : //openapi.alipay.com/gateway.do 
 REQUEST   METHOD :  POST 
 CONTENT :
      app_id = 2014070100171525 
      method = alipay . system . oauth . token 
      charset = GBK 
      sign_type = RSA2 
      timestamp = 2014 - 01 - 01   08 : 08 : 08 
      sign = rXaTEfJ7WTDsP1DWRPHARW3uOr19 + fzlngMCJBvbhP1XPEa9qZwGGng9oMDloABpJMT2SGeOj46 + BUkqCGRO9fH90Vci3hOH01BfYnbhJz3ADK2h7gpjlponx4 / sxELN6f2GXi51XKiHKnxMA9XpLLo68q + roY0M / ZFQ1UdnqeM = 
      version = 1.0 
      grant_type = authorization_code 
      code = 4 b203fe6c11548bcabd8da5bb087a83b //如开发者选择传入refresh_code，则无需传入code 
      refresh_token = 201208134 b203fe6c11548bcabd8da5bb087a83b //刷新access_token时使用，传入code后无需传入

4.2 请求参数说明

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

"alipay_system_oauth_token_response" :{ "access_token" : "20120823ac6ffaa4d2d84e7384bf983531473993" , "refresh_token" : "20120823ac6ffdsdf2d84e7384bf983531473993" , "user_id" : "2088102150477652" , "open_id" : "074a1CcTG1LelxKe4xQC0zgNdId0nxi95b5lsNpazWYoCo5" , "re_expires_in" : "3600" , "auth_start" : "2010-11-11 11:11:11" , "expires_in" : "3600" "sign" : "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"

4.4 同步响应参数说明

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

5 第四步：获取用户信息

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

5.1 接口请求示例

接口调用示例，以 JAVA 语言为例

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayUserInfoShareRequest request = new AlipayUserInfoShareRequest();
AlipayUserInfoShareResponse response = alipayClient.execute(request,accessToken);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
    REQUEST   URL :  https : //openapi.alipay.com/gateway.do 
 REQUEST   METHOD :  POST 
 CONTENT :
      app_id = 2014070100171525 
      method = alipay . user . info . share 
      charset = GBK 
      sign_type = RSA2 
      timestamp = 2014 - 01 - 01   08 : 08 : 08 
      sign = rXaTEfJ7WTDsP1DWRPHARW3uOr19 + fzlngMCJBvbhP1XPEa9qZwGGng9oMDloABpJMT2SGeOj46 + BUkqCGRO9fH90Vci3hOH01BfYnbhJz3ADK2h7gpjlponx4 / sxELN6f2GXi51XKiHKnxMA9XpLLo68q + roY0M / ZFQ1UdnqeM = 
      version = 1.0
      auth_token = 201208134 b203fe6c11548bcabd8da5bb087a83b
        "city":"安庆",
        "nick_name":"支付宝小二",
        "avatar":"http://tfsimg.alipay.com/images/partner/T1uIxXXbpXXXXXXXX"
    "sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"

6 消息通知

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

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

6.1 第一步：订阅消息

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

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

6.2 第二步：验签

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

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

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

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

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

6.4 用户授权取消消息通知

用户取消用户信息授权时，支付宝将通过 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==

7 接入沙箱

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

接入注意点

获取用户信息支持沙箱接入；在沙箱调通接口后，必须在线上进行测试与验收，所有返回码及业务逻辑以线上为准；
沙箱授权 url 链接拼接规则为： https://openauth-sandbox.dl.alipaydev.com/oauth2/publicAppAuthorize.htm?app_id=APPID&scope=SCOPE&redirect_uri=ENCODED_URL