本欄目下相關鏈接 | ||||
Discuz! Passport 接口技術文檔 | ||||
從 Discuz! 4.0.0 RC4 版本開始,Discuz! 內嵌了一個獨特的 Passport(通行證) 接口,利用此接口,用戶將很容易將論壇與其他應用 程序整合,而實現統一登錄與退出、用戶數據共享、積分同步等功能。可以整合的應用程序包括內容管理系統(CMS)、商城系統、遊戲系統等 等,如您對這方面功能有興趣或有需求,請繼續閱讀本文檔。 Discuz! Passport 的優點
Discuz! Passport 系統使用了 Discuz! 獨有的技術,並不等同於以往使用過的一些方法,與傳統的實現方式相比,具備(不限於)以下優勢:
Discuz! Passport 的局限
您在開始利用 Discuz! Passport 進行二次開發時,需要瞭解這個系統的局限性,以對未來的工作進行正確的評估與安排。
| ||||
Discuz! Passport 原理與流程 | ||||
假設已設置如下變量或參數
開啟通行證後的用戶登錄流程
開啟通行證後的用戶退出流程
開啟通行證後的用戶註冊流程
| ||||
Discuz! Passport 參數規格與加密方式 | ||||
私有密匙(passport_key) 由於一些關鍵參數採用了 GET 方式進行傳遞,即便兩次 header 跳轉並不會直接將鏈接顯示在外面,但我們仍然對關鍵的參數進行了加密,私有 密匙共有兩個作用:其一是供下面提到的可逆加密算法(AzDGCrypt)進行數據的加解密。其二是生成不可逆驗證字串(verify),以防止關鍵信息被 偽造。 在啟用 Discuz! Passort 後,您需要在應用程序和 Discuz! 後台配置兩處私有密匙,這兩處的內容必須完全相同,這樣應用程序和論壇之間才能 正常通信。私有密匙決定了加密算法的強度,因此密匙長度請不要小於 10 個字節,並包含字母、數字和符號,以保證系統的安全。 加密算法 Discuz! Passport 採用 Azerbaijan Development Group(AzDG)開發的可逆加密算法 AzDGCrypt 對用戶資料進行加密。如提供正確的私有密匙, 可通過本加密算法對數據進行加密及解密,因此只要保證私有密匙的保密性,即可確保數據傳遞過程中的安全。以下為 Discuz! Passport 中應用到 的可逆加密算法,為了生成可以被 Discuz! Passport 正確解密的 auth 字串,需要將如下函數放置於應用程序中,並可在登錄及註冊時調用。 passport_encrypt()是加密函數,用法為 passport_encrypt($txt, $key),其中 $txt 是待加密的字串,$key 是私有密匙。
passport_encode()是將數組轉換合成為字串形式存儲的函數:變量名和數值之間用等號連接,如果數值包含特殊字符,使用 urlencode() 將其轉碼。 多個變量間使用 & 分割。例如原始數組內容為 array('username' => 'abc', 'email' => 'my+discuz@gmail.com'),經過 passport_encode() 編碼後 結果為 username=abc&email=my%2Bdiscuz%40gmail.com。 信息字串(auth)
應用程序在收到登錄或註冊請求,並讀取到用戶資料後,請按如下的要求將用戶資料及部分其他信息存放於一個數組之中。數組各鍵值的含義為: 以上參數中,以黑體下劃線顯示的 time、username、password、email 是必須傳遞的參數,缺少上述參數 Passport 將無法正常工作。其他的參數是可選的,如果 不傳遞某些參數,則 Passport 會進行識別,自動不更新沒有傳遞的參數所在的字段。所有數值,請提供原始值,而非經過反斜線轉義(addslashes)後 的結果。 把上述信息存放於數組中,假定為如下的形式:
將其經過如下的加密變換,即可得到 auth 的值:
其中,passport_encode() 在前文已做了說明,用於將數組內容存放於特定的格式,$passport_key 是私有密匙。 切記:由於 $auth 中可能含有等號、加號等特殊字符,請將 $auth 經過 rawurlencode() 編碼後再在 URL 中傳遞,否則可能會產生問題。 導向字串(forward) 導向字串用於通知 Discuz! Passport 在完成自身操作後,返回到哪一個 URL 地址,例如 http://www.myforums.com/forumdisplay.php?fid=2。 如果 forward 為空,則默認導向到應用程序的首頁 切記:由於 $forward 中可能含有冒號、問號、等號等特殊字符,請將 $forward 經過 rawurlencode() 編碼後再在 URL 中傳遞,否則可能會 產生問題。 驗證字串(verify) 驗證字串用戶檢驗 auth 和 forward 兩個參數的合法性,避免非法構造參數進行破壞的可能。無論 auth 和 forward 變量是否存在,驗證字串
(verify)的值均為:
其中,$action 是當前執行的 Passport 操作,如 login 等等;$auth 是用戶信息加密後,並經 rawurlencode() 之前的內容。$forward 是經 rawurlencode() 前的導向字串、$passport_key 是私有密匙。如果 verify 的值不匹配,則 Passport 拒絕進行下一步操作。 | ||||
Discuz! Passport 設置與啟用 | ||||
內置關聯 Discuz! 以戰略合作的方式,與業內知名的產品實現了 Passport 關聯,目前內置了 SiteEngine 建站引擎(http://www.siteengine.net)和 Shopex 通用型網上商店系統(http://www.shopex.cn)的相關接口,這樣用戶只須透過在兩套軟件中簡單的設置,即可開啟這些關聯。 其他應用程序 由於 Discuz! Passport 的高可擴展性和平台無關性,使得您可以參照前文的說明,稍稍改動小部分的代碼,便將任何 B/S 模式的應用程序與 Discuz! 進行關聯。 參數設置 您可以在 Discuz! 系統設置中,看到相應的通行證設置功能,在 Discuz! 合作夥伴的軟件中,也可以找到這些設置入口。相關的操作已比較簡單, 在此不再詳細敘述。 特別說明 如果您先運營了論壇,後與其他應用程序啟用了 Passport 關聯,由於之前論壇中的用戶數據沒有同步,您需要先寫一個導入程序,將論壇的用戶 數據導入到應用程序的用戶表中,否則以往在論壇註冊的用戶將無法通過 Passport 登錄。已成功關聯後新註冊的用戶無此問題。 在開啟了 Discuz! 通行證後,您仍然可以通過 logging.php?action=login 這個鏈接來登錄論壇,以備調試之用,但頁面上顯示的鏈接將改為應用程序 的登錄 URL。注意:開啟通行證後,建議您通過 Discuz! 選項關閉論壇本身的註冊功能,以免用戶通過論壇註冊而產生無法同步的問題。 您可以在 Discuz! 的 api/passport.php 找到 Discuz! Passport 的全部源程序,您也許通過他更好的理解 Passport 的原理,更快的完成應用程序與 Discuz! 之間的整合。 | ||||
典型錯誤提示 | ||||
Illegal request 非法請求,當驗證字串 verify 不匹配時會產生此提示。可能是應用程序與 Discuz! 配置的私有密匙不同,或是通過 URL 傳遞前,未將必要的參數
(如 auth、forward 等)進行 URL 編碼,也有可能是使用了經過 URL 編碼的參數值用來計算 verify 的 md5 值造成。以 PHP 語言為例,正確的代碼
應當是類似於的如下的格式:
Lack of required parameters auth 內容解密後,缺少必要的信息 time、username、password、email。 Request expired 請求過期。當前服務器時間與應用程序提交過來的 time 之差大於 Discuz! Passport 中設置的請求有效期。可能是使用以往的代碼非法嘗試,也可能是 由於應用程序和 Discuz! 論壇所在的兩台服務器,時間設置有誤造成。 Invalid action 沒有指定 Passport 所執行的 action。 |