• 下载
  • 社区

用户授权

产品介绍

概述

所有支付宝开放平台的用户信息的读写均需要经过用户的许可才允许开发者使用,用户授权基于国际标准的 OAuth2.0 授权机制,基于此机制开发者可以获取支付宝用户信息、给用户发会员卡等。


术语解释


概念

说明

备注

scope

授权范围

一个 scope 表示开发者需要请求用户授权的权限范围,一个 scope 包含至少一个 openapi 接口或者 jsApi接口,一次授权可以组合多个 scope 做组合授权

auth_code

授权码

临时的用户授权凭证,获取后应及时换取下面提到的授权令牌

access_token/auth_token

授权令牌,或者叫访问令牌

长时效的授权凭证,用于调用 openapi.alipay.com 网关进行服务端授权接口调用。注意token需要注意权限范围和有效期

refresh_token

刷新令牌

用于在授权令牌过期后刷新重新获取新的授权令牌,刷新令牌也有有效期


关联产品

获取会员基础信息


scopes 列表

scopes

说明

包含的 openapi 接口

auth_base

用户基础授权,仅用于静默获取用户支付宝uid

auth_user

网站支付宝登录;获取用户信息(现已升级为“获取会员基础信息”,且新功能包不再使用 alipay.user.info.share 接口)

alipay.user.info.share

auth_zhima

用户芝麻信息

zhima.credit.score.brief.get

准入条件


用户授权功能个人和企业支付宝用户均可接入。

小程序开发者需充分尊重用户个人隐私,妥善使用用户授权。若发现信息存在超出约定范围使用或者不合理使用等情况,平台有权永久收回该小程序的接口权限。


计费模式


不收费


接入指引

接入流程

以获取用户信息举例,整体的接入流程如下(若需要授权其它信息,只需要在调用 getAuthCode 的时候的 scopes 参数使用不同的 scope 即可)


客户端获取 authcode

通过调用 my.getAuthCode 这个 jsapi 获取用户授权,在 success 回调中可以获取到 authcode,js 代码如下:

 1my.getAuthCode({
 2  scopes: 'auth_user', // 主动授权:auth_user,静默授权:auth_base。或者其它scope
 3  success: (res) => {
 4  
 5    if (res.authCode) {
 6      // 认证成功
 7      // 调用自己的服务端接口,让服务端进行后端的授权认证,并且种session,需要解决跨域问题
 8      my.request({
 9        url: 'https://isv.com/auth', // 该url是您自己的服务地址,实现的功能是服务端拿到authcode去开放平台进行token验证
10        data: {
11          authcode: res.authCrode,
12        },
13        success: () => {
14          // 授权成功并且服务器端登录成功
15        },
16        fail: () => {
17          // 根据自己的业务场景来进行错误处理
18        },
19      });
20    }
21  },
22});


服务端获取 access_token

服务器端调用 alipay.system.oauth.token 接口换取授权访问令牌,开发者可通过获取到的 auth_code 换取access_token 和用户 ID。auth_code 作为换取 access_token 的票据,每次用户授权完成,回调地址中的 auth_code 将不一样,auth_cod 只能使用一次,一天未被使用自动过期。具体可参见文档alipay.system.oauth.token
开放平台服务端SDK 的 java 调用示例如下:


 1AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
 2AlipaySystemOauthTokenRequest request = new AlipaySystemOauthTokenRequest();
 3request.setGrantType("authorization_code");
 4request.setCode("4b203fe6c11548bcabd8da5bb087a83b");
 5request.setRefreshToken("201208134b203fe6c11548bcabd8da5bb087a83b");
 6AlipaySystemOauthTokenResponse response = alipayClient.execute(request);
 7if(response.isSuccess()){
 8System.out.println("调用成功");
 9} else {
10System.out.println("调用失败");
11}
  • 认证成功
    把 uid&token 种到 session 中,在 session 有效期内就不需要每次都走授权平台进行验证

  • 认证失败
    则返回失败原因,需要再重新走授权流程。

  • 注意
    如果仅是为了授权或获取用户 ID,那么到此授权结束。


如果您在调用 API 时出现报错,您可以:

  • 公共错误码 中根据错误码的类型,查找相关错误码及解决方案;
  • 在 小蚂哥 问答页面直接输入您遇到的错误码;
  • 在技术支持 帮助中心 搜索相关错误码,找到解决方案。


调用服务端业务接口

在获取到 access_token 后,即可以继续使用该 token 调用 openapi 的授权类接口(比如 alipay.user.info.sharealipay.marketing.card.open等),请注意 token 的权限范围和时效性。


深入授权机制

用户授权auth_code

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

  • 建议
    基于安全考虑,开发者在获取 auth_code(用户授权码)后应尽快调用 alipay.system.oauth.token 接口换取access_token(访问令牌)。

授权scope

  • 说明
    scope 为公开的资源,其使用不需要签约,但是其包含的接口是否需要签约请看具体的功能包或者接口定义。
    开发者可以在授权请求中包含一个或者多个用户授权范围,每个授权范围称为一个 scope,一个 scope 包含若干个开放平台接口,请求的多个 scope 通过英文逗号分隔。
    授权的流程是通用的,在不同的业务场景需要授权的范围不同,需要根据具体产品接入文档中指定的 scope 替换本文中的scope参数。

  • scope 有效期:
    这里的 scope 有效期和前面的 auth_code 有效期是两个概念。
    scope的有效期会影响开发者最终获取到的access_token和refresh_token的有效期,不同scope的有效期请参考具体的产品文档。

  • 建议:
    为了产品体验考虑请按需请求需要的 scope,过多的授权范围容易导致用户放弃授权。建议在做产品的登录场景中使用 auth_base 或者 auth_user 做用户引流,后续根据需要具体业务需要引导用户请求特定scope的用户授权。


access_token

  • 有效期:
    access_token取决于授权时指定的scope的有效期,如果授权时指定多个scope,最终的access_token的有效期取决于有效期最短的scope。
    access_token截止时间=(授权时间点)+(授权后调用alipay.system.oauth.token返回的expires_in)

  • 令牌存储要求:

    • 确保access_token的安全保存;

    • 根据appId+uid+单个scope为索引保存access_token,否则会因为appid令牌混用和不同scope的令牌相互覆盖导致接口调用报错,若前后多次授权范围相同,仅保存授权截止时间最长的access_token即可。授权截止时间=授权时间点+alipay.system.oauth.token返回的expires_in。

注意:用户可以取消授权,取消后access_token即使在有效期也无法使用

refresh_token

  • 说明:
    用auth_code调用alipay.system.oauth.token接口获取access_token时会返回一个refresh_token(刷新令牌),在refresh_token有效期内可以通过refresh_token同样调用alipay.system.oauth.token刷新一个新的access_token

  • 有效期:

    • refresh_token取决于授权时指定的scope的有效期,如果授权时指定多个scope,最终的refresh_token的有效期取决于有效期最短的scope。

    • refresh_token截止时间=(第一次获得该refresh_token的时间+alipay.system.oauth.token返回的re_expires_in)

  • 使用:

    • 使用refresh_token调用alipay.system.oauth.token

    • 刷新后可以得到一个新的access_token,access_token截止时间重新计算(对应可以看到expires_in不会变),原来的accesss_token会立即失效;同时会得到一个新的refresh_token,原来的refresh_token会失效,新refresh_token截止时间不会重新计算(对应可以看到re_expires_in会减少)

注意:用户可以取消授权,取消后refresh_token即使在有效期也无法使用


API 列表


接口名称

描述

my.getAuthCode

获取用户授权码

alipay.system.oauth.token

换取授权访问令牌


如果您在调用 API 时出现报错,您可以:

  • 公共错误码 中根据错误码的类型,查找相关错误码及解决方案;
  • 在 小蚂哥 问答页面直接输入您遇到的错误码;
  • 在技术支持 帮助中心 搜索相关错误码,找到解决方案。


常见问题


Q:小程序如何实现用户授权?

A:小程序不支持使用拼接授权链接进行授权,建议使用 my.getAuthCode 实现用户授权、用户登录等。


Q: 先调用 my.getAuthCode,再调用 my.getOpenUserInfo 会出现两次授权窗口,是否有方法可以实现只出现一个授权弹框?

A: 正常获取会员基础信息是需要弹窗两次进行授权确认的,一次是 my.getAuthCode 获取用户授权码的授权框, 一次是 my.getOpenUserInfo 中获取用户基础信息的授权框。

my.getAuthCode 使用静默授权方法(令 scopes 为 auth_base)即可实现只出现一个授权弹框。示例代码如下:

1my.getAuthCode({
2  scopes: ['auth_base'],
3  success: (res) => {
4    my.alert({
5      content: res.authCode,
6    });
7  },
8});


Q: 如何打印 my.getAuthCode 获取到的 authCode?

A: 在 IDE 中使用 console.log,在 console 里打印即可。示例代码如下:

1my.getAuthCode({
2  scopes: 'auth_user',
3  success: (res) => {
4    console.log(res.authCode),
5    my.alert({
6      content: res.authCode, 
7    });
8  },
9});


效果如下图所示:

用户授权FAQ IDE.png


Q: 为什么要使用用户授权 my.getAuthCode API?

A: 开发者在支付宝开放平台上读写用户信息,均需经过用户许可。支付宝开放平台的用户授权基于国际标准的 OAuth2.0 授权机制。基于此机制,使用 my.getAuthCode API 得到用户授权后,方可进行获取用户信息、给用户发放会员卡等操作。


Q: 为什么不允许在小程序首屏使用用户授权 API?

A: 为了创造更良好的支付宝小程序用户体验,在小程序的首屏引导用户授权是不被允许的。需要在用户充分了解小程序的业务内容后再引导用户授权,建议将小程序授权环节放在业务流程中。


Q: 用户的 userID 可以通过用户授权 API 获取吗?

A: 不可以,userID 需要在服务器端调用 alipay.system.oauth.token 获取。


Q:商户咨询小程序获取会员基础信息根据 auth_code 获取 access_token 时提示 appid 无效

A:商户要获取auth_code是要关联appid的应用到商户自己的.商户可以点击https://open.alipay.com/platform/home.htm进入支付宝开放平台查找自己的应用 APPID。