「用微信掃碼登入」是微信開放平台網站應用的一項功能,本質上是基於 OAuth2.0 協ICAL 建的授權登入系統。本文完整梳理整個流程,從準備工作、授權模式,到取得 code、access_token 與呼叫介面,並附上常見問題解答。
微信開放平台網址:https://open.weixin.qq.com
準備工作
在接入微信 OAuth2.0 授權登入前,需先在微信開放平台註冊開發者帳號,擁有並通過審核的網站應用,取得 AppID 與 AppSecret,並申請微信登入且通過審核,才能開始接入流程。
授權流程說明
微信 OAuth2.0 授權登入讓用戶以微信身分安全登入第三方應用或網站。第三方取得 access_token 後,即可呼叫授權關係介面,進而取得用戶基本開放資訊並實作基礎開放功能。
目前支援 authorization_code 模式,適用於具備 server 端的應用。整體流程為:
1. 第三方發起微信授權登入請求,用戶同意後,微信會拉起應用或重定向到第三方網站,並帶上授權臨時票據 code 參數;
2. 透過 code 加上 AppID 與 AppSecret 等,呼叫 API 換取 access_token;
3. 透過 access_token 呼叫介面,取得用戶基本資料或執行基本操作。
取得 access_token 的時序圖:
第一步:請求 code
在 PC 端開啟以下連結(scope 需為 snsapi_login):https://open.weixin.qq.com/connect/qrconnect?appid=APPID&redirect_uri=REDIRECT_URI&response_type=code&scope=SCOPE&state=STATE#wechat_redirect
若提示「該連結無法訪問」,請檢查參數是否填寫正確,例如 redirect_uri 的網域是否與審核時填寫的授權網域一致、scope 是否為 snsapi_login。
參數說明
appid(必要)為應用唯一標識;redirect_uri(必要)為重定向位址,需 UrlEncode;response_type(必要)填 code;scope(必要)為授權範圍,網頁應用填 snsapi_login 即可;state(選填)用於維持請求與回呼狀態,可防止 csrf 攻擊,建議帶上並設為隨機數加 session 校驗。
回傳說明
用戶同意授權後,會重定向到 redirect_uri 並帶上 code 與 state:redirect_uri?code=CODE&state=STATE。若用戶拒絕,則只帶 state:redirect_uri?state=STATE。
請求示例
以登入一號店網站應用為例:https://passport.yhd.com/wechat/login.do 打開後會生成 state 並跳轉到微信 qrconnect 連結,用戶掃碼確認後,PC 端跳回 https://passport.yhd.com/wechat/callback.do?code=CODE&state=3d6be0a4035d839573b04816624a415e。
為滿足更客製化的需求,微信另提供第二種取得 code 的方式:把登入二維碼內嵌到自家頁面,用戶掃碼授權後透過 JS 把 code 回傳給網站,提升登入的流暢度與成功率。
步驟一:引入 JS 檔(支援 https)
<script src="https://res.wx.qq.com/connect/zh_CN/htmledition/js/wxLogin.js"></script>
步驟二:在需要微信登入處實例化 JS 物件
var obj = new WxLogin({ id:"login_container", appid: "", scope: "", redirect_uri: "", state: "", style: "", href: "" });
其中 id(必要)為顯示二維碼的容器 id;appid(必要)為應用唯一標識;scope(必要)填 snsapi_login;redirect_uri(必要)為重定向位址需 UrlEncode;state(選填)用於維持狀態與防 csrf;style(選填)可選 black 或 white,預設黑色文字;href(選填)可自訂樣式連結覆蓋預設樣式。
第二步:透過 code 取得 access_token
https://api.weixin.qq.com/sns/oauth2/access_token?appid=APPID&secret=SECRET&code=CODE&grant_type=authorization_code
參數中 appid、secret、code、grant_type 皆為必要,grant_type 填 authorization_code。正確回傳如下:
{ "access_token":"ACCESS_TOKEN", "expires_in":7200, "refresh_token":"REFRESH_TOKEN", "openid":"OPENID", "scope":"SCOPE" }
其中 access_token 為介面呼叫憑證、expires_in 為其 timeout(秒)、refresh_token 供刷新使用、openid 為授權用戶唯一標識、scope 為授權範圍。錯誤範例:{"errcode":40029,"errmsg":"invalid code"}。
刷新 access_token 有效期
access_token 目前有效期約 2 小時,超時後可用 refresh_token 刷新:若 access_token 已超時,會取得新的 access_token 與新的超時時間;若未超時,則不變更 access_token,但會刷新超時時間(相當於續期)。refresh_token 有效期約 30 天,失效後需用戶重新授權。
請求方式:https://api.weixin.qq.com/sns/oauth2/refresh_token?appid=APPID&grant_type=refresh_token&refresh_token=REFRESH_TOKEN,參數 appid、grant_type(填 refresh_token)、refresh_token 皆為必要,回傳格式同上。錯誤範例:{"errcode":40030,"errmsg":"invalid refresh_token"}。
第三步:透過 access_token 呼叫介面
呼叫介面前提是 access_token 有效未超時,且用戶已授權相應 scope。可呼叫的介面依 scope 而定:snsapi_base 可換取 access_token、refresh_token 與檢查 token 有效性;snsapi_userinfo 則可取得用戶個人資訊。其中 snsapi_base 屬基礎介面,若應用已擁有其他 scope 權限則預設擁有它;使用 snsapi_base 可讓移動端網頁授權略過跳轉授權頁,但會使得 scope 僅為 snsapi_base,因而無法取得需要用戶授權的資料與功能。
常見問題
1. 什麼是授權臨時票據(code)?
用於換取 access_token,超時時間為 10 分鐘,且一個 code 只能成功換取一次即失效。code 的臨時性與一次性保障了授權登入的安全性,第三方也可搭配 https 與 state 參數進一步加強。
2. 什麼是授權作用域(scope)?
代表用戶授權給第三方的介面權限,第三方需先向微信開放平台申請,再引導用戶授權、取得 access_token 後方可呼叫介面。
3. 內嵌 JS 中的 style 欄位作用?
淺色背景頁面應提供 black(或留空,為預設值),對應黑色文字;若提供 white 則文字為白色,適合深色背景。



4. 內嵌 JS 中的 href 欄位作用?
若預設樣式與自家頁面不符,可自行提供樣式檔覆蓋,例如覺得二維碼過大時,可透過 href 載入自訂 CSS:
相關效果如下:
