支付宝小程序用户信息授权
<h1>用户信息授权</h1>
<p>更新时间：2020-02-06 22:17:46</p>
<p>用户信息授权主要是为了获取支付宝用户ID（USER_ID）、授权令牌（access_token），便于开发者处理自身业务逻辑的时候使用，例如：获取支付宝用户信息、发会员卡、快捷登录等。授权支持多种场景，如：H5（需安装支付宝手机客户端）、PC、APP（可参考APP支付宝登录）。</p>
<p><strong>PC授权页面示例：</strong>
<img src="https://gw.alipayobjects.com/zos/skylark-tools/public/files/02b984be5a51be753396f801a2e7cb64.png" alt="undefined" /></p>
<p><strong>H5授权页面示例：</strong>
<img src="http://img01.taobaocdn.com/top/i1/LB1_EL8KVXXXXX5aXXXXXXXXXXX" alt="image" /></p>
<p><strong>若要实现用户信息授权功能，请按照下面的步骤实现即可。</strong></p>
<h1>一、应用设置</h1>
<ol>
<li>您需要先去支付宝开放平台（<a href="https://open.alipay.com/">open.alipay.com</a>），在开发者中心创建登记您的应用，此时您将获得应用唯一标识（<strong>APPID</strong>）；</li>
<li>请在【功能信息】中点击【添加功能】，选择【获取会员信息】；</li>
<li>设置密钥（如下图）；</li>
<li>设置授权回调地址（如下图），授权回调地址是用户授权结束后回跳的地址，用于接收用户授权的结果，如：授权、拿到auth_code，便于后续换取授权令牌（access_token）等；</li>
<li>提交审核，等待审核通过，该应用正式可以使用。</li>
</ol>
<p>需要详细了解开放平台创建应用步骤请参考《<a href="https://opendocs.alipay.com/open/200/105310">开放平台应用创建指南</a>》。
<img src="http://img01.taobaocdn.com/top/i1/LB19V9BSVXXXXcYXFXXXXXXXXXX" alt="image" /></p>
<p>图1 设置密钥、授权回调地址</p>
<p><img src="http://img01.taobaocdn.com/top/i1/LB1EzSPSVXXXXb1XpXXXXXXXXXX" alt="image" /></p>
<p>添加功能【获取会员信息】</p>
<p><img src="http://img01.taobaocdn.com/top/i1/LB1UMSmSVXXXXbmaXXXXXXXXXXX" alt="image" /></p>
<p>添加功能【获取会员信息】</p>
<h1>二、搭建和配置开发环境</h1>
<p><strong>1. 下载服务端SDK</strong>
为了帮助开发者调用开放接口，我们提供了<a href="https://opendocs.alipay.com/open/54/103419">开放平台服务端SDK</a>，包含JAVA、PHP和.NET三个语言版本，封装了签名&验签、HTTP接口请求等基础功能。请先下载对应语言版本的SDK并引入您的开发工程。
各语言版本服务端SDK详细使用说明，请参考《<a href="https://opendocs.alipay.com/open/54/103419">服务端SDK说明</a>》。
<strong>2. 接口调用配置</strong>
在SDK调用前需要进行初始化，以Java代码为示例如下：</p>
<pre><code class="language-js">AlipayClient alipayClient = new DefaultAlipayClient(URL, APP_ID, APP_PRIVATE_KEY, FORMAT, CHARSET, ALIPAY_PUBLIC_KEY, SIGN_TYPE);</code></pre>
<p>关键参数说明:</p>
<table>
<thead>
<tr>
<th style="text-align: left;">配置参数</th>
<th style="text-align: left;">示例值解释</th>
<th style="text-align: left;">获取方式/示例值</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">URL</td>
<td style="text-align: left;">支付宝网关（固定）</td>
<td style="text-align: left;"><a href="https://openapi.alipay.com/gateway.do">https://openapi.alipay.com/gateway.do</a></td>
</tr>
<tr>
<td style="text-align: left;">APPID</td>
<td style="text-align: left;">APPID 即创建应用后生成</td>
<td style="text-align: left;">获取见上面<a href="https://opendocs.alipay.com/open/#s0">应用设置</a></td>
</tr>
<tr>
<td style="text-align: left;">APP_PRIVATE_KEY</td>
<td style="text-align: left;">开发者私钥，由开发者自己生成</td>
<td style="text-align: left;">获取详见上面<a href="https://opendocs.alipay.com/open/#s0">应用设置</a></td>
</tr>
<tr>
<td style="text-align: left;">FORMAT</td>
<td style="text-align: left;">参数返回格式，只支持json</td>
<td style="text-align: left;">json（固定）</td>
</tr>
<tr>
<td style="text-align: left;">CHARSET</td>
<td style="text-align: left;">编码集，支持GBK/UTF-8</td>
<td style="text-align: left;">开发者根据实际工程编码配置</td>
</tr>
<tr>
<td style="text-align: left;">ALIPAY_PUBLIC_KEY</td>
<td style="text-align: left;">支付宝公钥，由支付宝生成</td>
<td style="text-align: left;">获取详见上面<a href="https://opendocs.alipay.com/open/#s0">应用设置</a></td>
</tr>
<tr>
<td style="text-align: left;">SIGN_TYPE</td>
<td style="text-align: left;">商户生成签名字符串所使用的签名算法类型，目前支持RSA2和RSA，推荐使用RSA2</td>
<td style="text-align: left;">RSA2</td>
</tr>
</tbody>
</table>
<h1>三、开发授权功能</h1>
<p>授权完整流程如下：
<img src="http://img01.taobaocdn.com/top/i1/LB1rV9aRFXXXXcjaXXXXXXXXXXX" alt="image" /></p>
<p>需要开发的关键点是：获取auth_code、auth_code换取access_token与user_id、使用token完成其他业务处理，如token换取用户信息等。</p>
<h2>第一步：URL拼接与scope详解</h2>
<p>商户/开发者通过以下的 URL 拼接规则拼接用户授权的 URL 地址，该地址展示给用户，用户需在支付宝端点开 URL 地址，并点击授权，商户/开发者即可获得用户的授权。
url拼接规则：<a href="https://openauth.alipay.com/oauth2/publicAppAuthorize.htm?app_id=APPID&scope=SCOPE&redirect_uri=ENCODED_URL">https://openauth.alipay.com/oauth2/publicAppAuthorize.htm?app_id=APPID&scope=SCOPE&redirect_uri=ENCODED_URL</a></p>
<blockquote>
<p><strong>TIPS：</strong>沙箱拼接规则详见<a href="https://opendocs.alipay.com/open/#s4">关于沙箱</a>。</p>
</blockquote>
<p>url参数说明</p>
<table>
<thead>
<tr>
<th style="text-align: left;">参数名</th>
<th style="text-align: left;">是否必须</th>
<th style="text-align: left;">长度</th>
<th style="text-align: left;">描述</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">app_id</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">16</td>
<td style="text-align: left;">开发者应用的app_id； 相同支付宝账号下，不同的app_id获取的token切忌混用。</td>
</tr>
<tr>
<td style="text-align: left;">scope</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">不定，取决于请求授权时scope个数</td>
<td style="text-align: left;">接口权限值，目前只支持auth_user（<a href="https://opendocs.alipay.com/open/284/106000">获取用户信息</a>、<a href="https://opendocs.alipay.com/open/263/105808">网站支付宝登录</a>）、auth_base（用户信息授权）、auth_ecard（<a href="https://opendocs.alipay.com/open/251/105663">商户会员卡</a>）、auth_invoice_info（<a href="https://opendocs.alipay.com/open/396/106894">支付宝闪电开票</a>）、auth_puc_charge（<a href="https://opendocs.alipay.com/open/217/105324">生活缴费</a>）五个值;多个scope时用”,”分隔，如scope为”auth_user,auth_ecard”时，此时获取到的access_token，既可以用来获取用户信息，又可以给用户发送会员卡。</td>
</tr>
<tr>
<td style="text-align: left;">redirect_uri</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">100</td>
<td style="text-align: left;">授权回调地址，是经过URLENCODE转义 的url链接（url必须以http或者https开头）； 在请求之前，开发者需要先到开发者中心对应应用内，<a href="https://opendocs.alipay.com/open/#s0">配置授权回调地址</a>。 redirect_uri与应用配置的授权回调地址域名部分必须一致。</td>
</tr>
<tr>
<td style="text-align: left;">state</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">100</td>
<td style="text-align: left;">商户自定义参数，用户授权后，重定向到redirect_uri时会原样回传给商户。 为防止CSRF攻击，建议开发者请求授权时传入state参数，该参数要做到既不可预测，又可以证明客户端和当前第三方网站的登录认证状态存在关联。</td>
</tr>
</tbody>
</table>
<h2>第二步：获取auth_code</h2>
<p>当用户授权成功后，会跳转至开发者定义的回调页面，支付宝会在回调页面请求中加入参数，包括auth_code、app_id、scope等，支付宝请求开发者回调页面示例如下：</p>
<pre><code class="language-js">http或https打头的授权回调地址? app_id=2016032301002387 &scope=auth_user&auth_code=10e20498fe5d42f18427d893fc06WX59</code></pre>
<p>关键返回参数说明：</p>
<table>
<thead>
<tr>
<th style="text-align: left;">参数名</th>
<th style="text-align: left;">是否必须</th>
<th style="text-align: left;">长度</th>
<th style="text-align: left;">描述</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">app_id</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">16</td>
<td style="text-align: left;">开发者应用的app_id；相同支付宝账号下，不同的app_id获取的token切忌混用。</td>
</tr>
<tr>
<td style="text-align: left;">scope</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">不定，取决于请求授权时scope个数</td>
<td style="text-align: left;">成功授权的接口权限值，目前只支持auth_user（<a href="https://opendocs.alipay.com/open/284/106000">获取用户信息</a>、<a href="https://opendocs.alipay.com/open/263/105808">网站支付宝登录</a>）、auth_base（用户信息授权）、auth_ecard（<a href="https://opendocs.alipay.com/open/251/105663">商户会员卡</a>）、auth_invoice_info（<a href="https://opendocs.alipay.com/open/396/106894">支付宝闪电开票</a>）、auth_puc_charge（<a href="https://opendocs.alipay.com/open/217/105324">生活缴费</a>）五个值;多个scope时用“,”分隔，如scope为“auth_user,auth_ecard”时，此时获取到的access_token，既可以用来获取用户信息，又可以给用户发送会员卡</td>
</tr>
<tr>
<td style="text-align: left;">error_scope</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">不定，少于请求授权时scope个数</td>
<td style="text-align: left;">error_scope表示授权是失败的scope列表及对应的错误信息（错误列表之间用“</td>
</tr>
<tr>
<td style="text-align: left;">state</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">100</td>
<td style="text-align: left;">商户自定义参数，用户授权后，重定向到redirect_uri时会原样回传给商户。 为防止CSRF攻击，建议开发者请求授权时传入state参数，该参数要做到既不可预测，又可以证明客户端和当前第三方网站的登录认证状态存在关联。</td>
</tr>
<tr>
<td style="text-align: left;">auth_code</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">目前为32，后期会根据安全策略适当调整，请勿限制该字段长度。</td>
<td style="text-align: left;">临时授权码，一次性有效，同时若超过有效期未使用，则会失效。有效期目前至少为5分钟，最长为24小时。请获取auth_code后尽快通过调用alipay.system.oauth.token接口获取访问令牌</td>
</tr>
</tbody>
</table>
<p><strong>注意：</strong>其余返回字段无需关注。</p>
<h2>第三步：auth_code换取access_token与user_id</h2>
<p>通过接口 <a href="https://opendocs.alipay.com/apis/api_9/alipay.system.oauth.token">alipay.system.oauth.token</a> 获取access_token及userId。
接口调用示例：</p>
<pre><code class="language-js">AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
AlipaySystemOauthTokenRequest request = new AlipaySystemOauthTokenRequest();
request.setCode("2e4248c2f50b4653bf18ecee3466UC18");
request.setGrantType("authorization_code");
try {
AlipaySystemOauthTokenResponse oauthTokenResponse = alipayClient.execute(request);
System.out.println(oauthTokenResponse.getAccessToken());
System.out.println(oauthTokenResponse.getUserId());
} catch (AlipayApiException e) {
//处理异常
e.printStackTrace();
}</code></pre>
<p><strong>至此，用户信息授权流程已结束，如果只想拿到user_id（支付宝用户唯一标识符），则无需看下一步。</strong></p>
<h2>第四步：使用access_token完成其他业务处理</h2>
<p>开放平台的部分接口中需要依赖access_token才能执行的，因此为了拿到这个数据，需要执行以上的两个步骤才能换取到。
另外，不同的scopes的值对应的是不同的access_token，不同的token可调用不同的接口，token的效用也因此不一样，所以这些token切忌混用，具体的接口调用场景可参考：</p>
<p><a href="https://opendocs.alipay.com/open/284/106000">获取会员信息</a>
<a href="https://opendocs.alipay.com/open/263/105808">网站支付宝登录</a>
<a href="https://opendocs.alipay.com/open/251/105663">商户会员卡</a>
<a href="https://opendocs.alipay.com/open/396/106893">支付宝闪电开票</a>
<a href="https://opendocs.alipay.com/open/218/105329">APP支付宝登录</a>
<a href="https://opendocs.alipay.com/open/217/105324">生活缴费</a></p>
<h1>授权接入注意事项【必读】</h1>
<h2>1、用户授权auth_code</h2>
<p><strong>说明：</strong>
auth_code一次有效，auth_code有效期为3分钟到24小时（开放平台规则会根据具体的业务场景动态调整auth_code的有效期，但是不会低于3分钟，同时也不会超过24小时），超过有效期的auth_code即使未使用也将无法使用。
用户的每次授权动作都会生成一个新的auth_code。
<strong>建议：</strong>
基于安全考虑，开发者在获取auth_code（用户授权码）后应尽快调用alipay.system.oauth.token接口换取access_token（访问令牌）。</p>
<h2>2、授权scope</h2>
<p><strong>说明：</strong>
scope为公开的资源，其使用不需要签约。
开发者可以在授权请求中包含一个或者多个用户授权范围，每个授权范围称为一个scope，一个scope包含若干个开放平台接口，请求的多个scope通过英文逗号分隔。
授权的流程是通用的，在不同的业务场景需要授权的范围不同，需要根据具体产品接入文档中指定的scope替换本文中的scope参数。</p>
<p><strong>scope有效期：</strong>
这里的scope有效期和前面的auth_code有效期是两个概念。
scope的有效期会影响开发者最终获取到的access_token和refresh_token的有效期，不同scope的有效期请参考具体的产品文档。</p>
<p><strong>建议：</strong>
为了产品体验考虑请按需请求需要的scope，过多的授权范围容易导致用户放弃授权。建议在做产品的登录场景中使用auth_base或者auth_user做用户引流，后续根据需要具体业务需要引导用户请求特定scope的用户授权。</p>
<h2>3、access_token</h2>
<p><strong>有效期：</strong>
access_token取决于授权时指定的scope的有效期，如果授权时指定多个scope，最终的access_token的有效期取决于有效期最短的scope。
access_token截止时间=（授权时间点）+（授权后调用alipay.system.oauth.token返回的expires_in）</p>
<p><strong>令牌存储要求：</strong></p>
<ul>
<li>确保access_token的安全保存；</li>
<li>根据appId+uid+单个scope为索引保存access_token，否则会因为appid令牌混用和不同scope的令牌相互覆盖导致接口调用报错，若前后多次授权范围相同，仅保存授权截止时间最长的access_token即可。授权截止时间=授权时间点+alipay.system.oauth.token返回的expires_in。</li>
</ul>
<p><strong>注意：</strong>用户可以取消授权，取消后access_token即使在有效期也无法使用</p>
<h2>4、刷新令牌</h2>
<p><strong>说明：</strong>
用auth_code调用alipay.system.oauth.token接口获取access_token时会返回一个refresh_token（刷新令牌），在refresh_token有效期内可以通过refresh_token同样调用alipay.system.oauth.token刷新一个新的access_token</p>
<p><strong>有效期：</strong>
refresh_token取决于授权时指定的scope的有效期，如果授权时指定多个scope，最终的refresh_token的有效期取决于有效期最短的scope。
refresh_token截止时间=（调用alipay.system.oauth.token的时间+alipay.system.oauth.token返回的re_expires_in）</p>
<p><strong>使用：</strong>
使用refresh_token调用alipay.system.oauth.token
刷新后可以得到一个新的access_token，access_token截止时间重新计算（对应可以看到expires_in不会变），原来的accesss_token会立即失效；同时会得到一个新的refresh_token，原来的refresh_token会失效，新refresh_token截止时间<strong>不会</strong>重新计算（对应可以看到re_expires_in会减少）</p>
<p><strong>注意：</strong>用户可以取消授权，取消后refresh_token即使在有效期也无法使用</p>
<h1>授权登录安全建议</h1>
<p>若你希望通过支付宝授权进行平台登录，同时为了让登录服务享受支付宝的安全能力，需要你在接入授权时做一些校验和处理，<strong>强烈建议</strong>做如下处理：</p>
<h2>state防止CSRF</h2>
<p>在 <a href="https://opendocs.alipay.com/open/#url-scope">拼接授权链接做用户授权</a>，在拼接链接中提供state参数（该参数的值需要和用户在开发者网站会话有绑定关系，同时保证一次性有效），在授权后支付宝回跳商户地址时会将该参数原样返回。在以下情况开发者应该拒绝服务：回跳链接中无state参数或者state的值与开发者平台session中记录的state参数不一致。state格式：不超过100长度的base64字符。</p>
<h2>Referer校验</h2>
<p>在浏览器的授权回跳地址的处理逻辑中做Http的Referer校验，目前蚂蚁金服授权产品的域名均在alipay.com下，建议将此配置做成可配置的。</p>
<h2>授权回调地址建议</h2>
<p>1、条件允许的情况下回跳地址强制要求https。推荐使用<a href="https://www.aliyun.com/product/cas?spm=5176.8142029.388261.141.lAF2bj">阿里云证书服务</a>（阿里云提供免费的证书服务，只需要您有自己的域名即可使用）；
2、开放平台授权地址配置时仅使用不带参数的地址，防止字符集问题导致的业务失败。需要的业务参数可以统一通过state参数传递；
3、尽量保证授权回调地址页面本身的安全性，包括但不限于页面所在服务器自身的安全性等。</p>
<h1>关于沙箱</h1>
<h2>如何接入沙箱</h2>
<p>沙箱是开放平台提供给开发者用户调试接口的环境，具体操作步骤见 <a href="https://opendocs.alipay.com/open/200/105311">沙箱接入指南</a>。</p>
<h2>获取用户信息沙箱接入注意点</h2>
<p>1、获取用户信息支持沙箱接入；在沙箱调通接口后，必须在线上进行测试与验收，所有返回码及业务逻辑以线上为准；
2、沙箱授权url链接拼接规则为：<a href="https://openauth.alipaydev.com/oauth2/publicAppAuthorize.htm?app_id=APPID&scope=SCOPE&redirect_uri=ENCODED_URL">https://openauth.alipaydev.com/oauth2/publicAppAuthorize.htm?app_id=APPID&scope=SCOPE&redirect_uri=ENCODED_URL</a></p>