支付寶小程序授權登陸篇

用戶授權

產品介紹 

概述

所有支付寶開放平臺的用戶信息的讀寫均需要經過用戶的許可才允許開發者使用，用戶授權基於國際標準的 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	靜默授權，不會發起授權浮窗；在支付寶客戶端獲取 auth_code，傳入服務端端調用 alipay.system.oauth.token 接口獲取支付寶會員標識（user_id）	無
auth_user	主動授權，需要用戶手動點擊同意，用戶同意後，用於 網站支付寶登錄 和 獲取用戶信息（現已升級爲“獲取會員基礎信息”，且新功能包不再使用 alipay.user.info.share 接口）功能。	alipay.user.info.share
auth_zhima	用戶芝麻信息	zhima.credit.score.brief.get

 

准入條件

 

• 該能力對企業支付寶賬戶和個人支付寶賬戶（含個體工商戶）均開放；

• 小程序開發者需充分尊重用戶個人隱私，妥善使用用戶授權。若發現信息存在超出約定範圍使用或者不合理使用等情況，平臺有權永久收回該小程序的接口權限。

 

計費模式

免費

 

快速示例

 

如下示例僅演示接口調用流程，爲了創造更良好的支付寶小程序用戶體驗，小程序不允許首屏引導用戶授權。需要在用戶充分了解小程序的業務內容後再引導用戶授權，建議將小程序授權環節放在業務流程中。

獲取用戶授權的演示效果請參考以下示例，實際返回的授權碼以真機調試爲準。

 axml.html

<view class="page">
  <view class="page-section">
    <view>請不要一進入小程序就彈框授權，建議先了解小程序的服務內容</view>
    <button type="primary" onTap="getAuthCode">
      獲取授權碼
    </button>
  </view>
</view>

index.js

Page({
  onLoad() {},
  data: {},
  getAuthCode: () => {
    my.getAuthCode({
      scopes: 'auth_user',
      success: ({ authCode }) => {
        my.alert({
          content: authCode,
        });
      },
    });
  },
});

接入指引

接入流程

以獲取用戶信息舉例，整體的接入流程如下（若需要授權其它信息，只需要在調用 getAuthCode 的時候的 scopes 參數使用不同的 scope 即可）。

 

客戶端獲取 authcode

通過調用 my.getAuthCode 這個 jsapi 獲取用戶授權，在 success 回調中可以獲取到 authcode，js 代碼如下：

 

 

 

my.getAuthCode({
  scopes: 'auth_user', // 主動授權：auth_user，靜默授權：auth_base。或者其它scope
  success: (res) => {
  
    if (res.authCode) {
      // 認證成功
      // 調用自己的服務端接口，讓服務端進行後端的授權認證，並且利用session，需要解決跨域問題
      my.request({
        url: 'https://isv.com/auth', // 該url是您自己的服務地址，實現的功能是服務端拿到authcode去開放平臺進行token驗證
        data: {
          authcode: res.authCode,
        },
        success: () => {
          // 授權成功並且服務器端登錄成功
        },
        fail: () => {
          // 根據自己的業務場景來進行錯誤處理
        },
      });
    }
  },
});

 

 

 

 

服務端獲取 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 調用示例如下：

 

 

 

 

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipaySystemOauthTokenRequest request = new AlipaySystemOauthTokenRequest();
request.setGrantType("authorization_code");
request.setCode("4b203fe6c11548bcabd8da5bb087a83b");
request.setRefreshToken("201208134b203fe6c11548bcabd8da5bb087a83b");
AlipaySystemOauthTokenResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("調用成功");
} else {
System.out.println("調用失敗");
}

 

 

 

• 認證成功 把 uid&token 保存到 session 中，在 session 有效期內就不需要每次都走授權平臺進行驗證。

• 認證失敗 則返回失敗原因，需要再重新走授權流程。

• 注意 如果僅是爲了授權或獲取用戶 ID，那麼到此授權結束。

 

調用服務端業務接口

在獲取到 access_token 後，即可以繼續使用該 token 調用 openapi 的授權類接口（比如 alipay.user.info.share、alipay.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 時出現報錯：

 

• 歡迎前往 開放社區 提問、留言；

• 在 公共錯誤碼 中根據錯誤碼的類型，查找相關錯誤碼及解決方案；

• 在 螞蟻問答 問答頁面直接輸入您遇到的錯誤碼；

• 在 雲排查 中排查遇到的問題；

• 您還可以在 文檔中心 直接搜索您要的答案。

 官方文檔：傳送門