如何為 Captive Portals 設定微信 OAuth 驗證

如何為 CAPTIVE PORTALS 設定微信 OAUTH 驗證 Purple 技術簡報 - 約 10 分鐘 --- 引言與背景（約 1 分鐘） 歡迎。如果您負責為服務中國旅客的飯店、連鎖零售店、體育場館或會議中心提供訪客 WiFi，這篇簡報將對您非常有用。 根據騰訊 2024 年的數據，微信擁有 13.8 億的月活躍用戶。雖然絕大多數用戶在中國，但該平台在國際上也擁有不容忽視的足跡——在美國有 400 萬用戶，在馬來西亞有 1200 萬用戶，且在東南亞、歐洲和中東地區的用戶數量也在持續增長。 當中國訪客連線到您的 WiFi，卻看到一個只提供電子郵件、Facebook 或憑證代碼的登入頁面時，他們會立即面臨阻礙。他們在該裝置上可能沒有設定當地的電子郵件地址。但他們幾乎肯定擁有微信。因此，問題不在於您是否應該提供微信登入，而是在於您如何正確、安全地設定它，並以一種能夠產生您實際可用的第一方數據的方式來進行。 這就是我們今天將要涵蓋的內容。我們將逐步介紹 OAuth 2.0 流程、您需要的兩個平台註冊、決定您收集哪些數據的權限範圍（scope）決策、網路端的強制執行機制，以及在 2026 年至關重要的合規性考量。 --- 技術深度剖析（約 5 分鐘） 讓我們從架構開始。Captive Portal 會攔截來自未經驗證裝置的 HTTP 流量，並將其重導向至登入頁面。該登入頁面託管在 Portal 伺服器上——無論是本地部署還是雲端部署。當您加入微信 OAuth 時，您是在該流程中插入了一個第三方身分識別提供商。 以下是具體步驟。訪客連線到您的 SSID。無線存取點（AP）或無線控制器偵測到該裝置沒有已驗證的會話，並將所有 HTTP 流量重導向至您的 Captive Portal URL。Portal 頁面載入並呈現登入選項——包括微信。訪客點擊微信登入。您的 Portal 伺服器將瀏覽器重導向至微信位於 open.weixin.qq.com 的授權端點，並傳遞您的 AppID、重導向 URI、code 的回應類型以及權限範圍（scope）。 微信完全在自己的伺服器上處理驗證。如果訪客已經在瀏覽器中登入微信，他們會看到一個同意畫面。如果他們使用的是微信內建瀏覽器，則可以使用 snsapi_base 權限範圍來獲得無感體驗——完全不需要同意提示。接著，微信會帶著臨時授權碼重導向回您 Portal 的重導向 URI。您的 Portal 伺服器透過呼叫 api.weixin.qq.com/sns/oauth2/access_token，並傳遞您的 AppID、AppSecret、授權碼以及 authorization_code 的授權類型，來將該授權碼交換為存取權杖（access token）。微信會傳回存取權杖、重新整理權杖（refresh token）、使用者的 OpenID 以及授予的權限範圍。如果您請求了 snsapi_userinfo 權限範圍，您接著可以進行第二次 API 呼叫，以擷取使用者的暱稱、頭像、性別和城市。 現在，來談談這兩個平台的註冊。這正是大多數部署最容易出錯的地方。 微信（WeChat）擁有兩個獨立的開發者平台。微信開放平台（open.weixin.qq.com）負責處理網站應用程式和行動 App。微信公眾平台（mp.weixin.qq.com）則處理公眾帳號——這通常才是大多數場所真正需要的。 若要為在 WeChat 內建瀏覽器中開啟的 Captive Portal 提供服務，您需要在公眾平台上申請一個「服務號」。「訂閱號」是無法運作的，因為它不具備 OAuth 網頁授權權限。服務號則支援，且同時支援 snsapi_base 和 snsapi_userinfo 兩種 scope。 若要為 WeChat 外部的標準行動瀏覽器（例如 Android 上的 Chrome、iOS 上的 Safari）所存取的 Captive Portal 提供服務，您需要在開放平台上註冊一個「網站應用」。這會使用 snsapi_login scope，並向使用者顯示一個 QR code，供其使用 WeChat App 進行掃描。 在實際應用中，大多數場所部署會同時使用這兩者。飯店 WiFi 的房客可能會在 Chrome 中開啟入口網站，看到 QR code，用 WeChat 掃描並完成驗證。或者，他們可能會直接點擊 WeChat 內部的連結，進入內建瀏覽器，並透過 snsapi_base 進行無感驗證。 接下來談談 scope 的選擇，因為這是一個關鍵的決策點。 snsapi_base 僅傳回 OpenID——這是該使用者在您公眾帳號中的唯一識別碼。它不需要使用者同意提示，驗證過程對使用者而言是完全隱形的。這非常適合已建立設定檔的熟客，或希望以零摩擦為代價、不收集新資料的場所。 snsapi_userinfo 則會傳回 OpenID，加上使用者的 WeChat 暱稱、個人頭像、性別、語言設定和城市。這需要一個明確的同意畫面。使用者會看到一個提示，詢問是否允許您的公眾帳號存取其資訊。大多數使用者都會接受，但這會產生操作摩擦。 正確的選擇取決於您的應用場景。對於首次註冊、且您希望建立其設定檔的房客，請使用 snsapi_userinfo，並在您的入口網站頁面上搭配符合 GDPR 規範的同意層。對於已同意過且您已擁有其設定檔的熟客，請使用 snsapi_base 進行無感重新驗證。 最後是網路強制執行端。取得 OAuth token 可以證明身分，但並不會自動開啟網路。您需要一個機制，將成功的驗證轉換為網路存取權限。 兩種標準方法是 RFC 3576 中定義的 RADIUS 授權變更 (CoA) 以及 MAC 位址繞過。使用 RADIUS CoA，您的入口網站伺服器會在 OAuth 成功後向網路控制器發送 CoA 請求，控制器隨即將裝置從未驗證的 VLAN 移至訪客 VLAN。這適用於 Cisco Meraki、HPE Aruba、Ruckus、Juniper Mist 以及大多數企業級控制器。使用 MAC 繞過時，入口網站伺服器會將裝置的 MAC 位址註冊為已授權的用戶端，控制器隨即予以放行。MAC 繞過實作起來較簡單，但安全性較低，因為 MAC 位址可能會被偽造。 Purple 的 Guest WiFi 平台同時支援這兩種機制。在微信 OAuth 完成後，Purple 的雲端重疊網路 (cloud overlay) 會向底層硬體發送相應的訊號——無論是 Cisco Meraki、HPE Aruba、Ruckus、Juniper Mist、Ubiquiti UniFi、Cambium、Extreme 還是 Fortinet。場所營運商無需手動處理該轉換。 --- 實作建議與常見陷阱 (約 2 分鐘) 以下是導致微信 OAuth Captive Portal 實作失敗的五個主要原因。 第一：重新導向 URI 不比對。微信會根據您在平台上註冊的授權網域來驗證重新導向 URI。如果您的入口網站伺服器使用不同的子網域、不同的路徑，或使用 HTTP 而非 HTTPS，OAuth 流程將會失敗並顯示錯誤代碼 40029 - 無效的代碼。請註冊您使用的每個網域變體，包括預備環境 (staging environments)。 第二：用戶端側的 AppSecret。您的 AppSecret 絕不能出現在用戶端 JavaScript 或行動應用程式二進位檔中。它應該保留在您的伺服器上。如果暴露，任何人都可以冒充您的應用程式並代表您呼叫微信的 API。 第三：缺少 CSRF 保護。OAuth 請求中的 state 參數專門用於防止跨站請求偽造。請產生一個加密隨機的 state 值，將其儲存在使用者工作階段中，並在微信重新導向回來時進行驗證。跳過此步驟將會產生真正的安全漏洞。 第四：應用程式內瀏覽器偵測缺口。微信的應用程式內瀏覽器會設定一個包含 "MicroMessenger" 的特定 user agent 字串。如果您的入口網站未偵測到此字串並提供正確的 OAuth 流程（應用程式內瀏覽器使用公眾號流程，標準瀏覽器使用開放平台 QR 流程），使用者將會遇到體驗中斷或錯誤。 第五：GDPR 與 PIPL 合規。如果您服務歐洲訪客，GDPR 適用於您透過微信 OAuth 收集的資料。如果您服務中國訪客，中國的《個人信息保護法》(PIPL) 適用於您處理其資料的方式。兩者都要求具備合法的處理依據、明確的目的限制以及資料最小化。在資料最小化原則下，snsapi_base 比 snsapi_userinfo 更容易證明其合理性。無論您收集什麼，請記錄您的法律依據和保存期限。 --- 快速問答 (約 1 分鐘) 問題：我可以在同時提供電子郵件和簡訊登入的入口網頁上使用微信登入嗎？ 可以。大多數企業級入口網頁平台（包括 Purple）都支援在同一個入口網頁上使用多種驗證方式。微信會作為其中一個選項與其他選項並列顯示。 問題：微信 OAuth 在 iOS 上可以運作嗎？ 可以，但有些微差異。Apple 的「App 追蹤透明度」架構不會影響伺服器端的 OAuth 流程。iOS 上 Safari 中的微信登入是透過 QR code 流程或重新導向流程進行。微信 App 本身會處理該驗證。 問題：如果微信的 API 無法使用會怎麼樣？ 您的入口網頁應該實作備用方案。如果微信 API 呼叫逾時或傳回錯誤，請將使用者重新導向至其他登入方式。請勿讓他們面對空白畫面。 問題：我可以使用 OpenID 作為永久的客戶識別碼嗎？ 在您的官方帳號內是可以的。對於特定的使用者和特定的官方帳號，OpenID 是穩定的。如果您有多個官方帳號，同一個使用者在這些帳號中將擁有不同的 OpenID。若要進行跨帳號的身分識別解析，微信提供了 UnionID，這需要您在開放平台上連結您的帳號。 --- 摘要與後續步驟（約 1 分鐘） 總結來說。針對 Captive Portal 的微信 OAuth 驗證是一項涉及雙平台註冊、權限範圍決策、網路強制執行整合以及合規性審查的工作。做好這四件事，您就能擁有一種為超過十億潛在訪客提供零密碼阻力的登入方式。 具體的後續步驟如下。首先，確定您的訪客是在微信內建瀏覽器中還是在標準行動瀏覽器中遇到入口網頁——這決定了您需要進行哪種平台註冊。第二，決定權限範圍——針對回訪客使用 snsapi_base，針對首次註冊且需同意的情況使用 snsapi_userinfo。第三，確認您的網路硬體支援 RADIUS CoA，或設定 MAC 繞過作為替代方案。第四，根據 GDPR 和《個人信息保護法》(PIPL) 的要求審查您的隱私權聲明和同意流程。第五，在正式上線前測試重新導向 URI、state 參數驗證以及內建瀏覽器偵測。 如果您想了解 Purple 如何在更廣泛的顧客 WiFi 和分析平台中處理微信 OAuth（在 2024 年跨越 80,000 個場域和 4.4 億次登入），請造訪 purple.ai 或聯絡您的客戶團隊。 感謝您的收聽。 --- 腳本結束