UserProvider。例如可以將外部目錄、既有會員系統或專用 API 作為驗證的儲存位置。
這與新建 Guard 的擴充不同。你只需為既有的 session 或 token Guard 提供搜尋與驗證使用者的實作。若要變更 Guard 本身的驗證方式,請參閱自訂驗證 Guard 的實作。
本頁以 Laravel 13 為對象,參照官方文件的
13.x 分支與 Framework v13.43.0 的實作。請在套件支援的每個 Laravel 版本中確認契約的方法與密碼重新雜湊的行為。分離 Guard 與 UserProvider 的職責
Auth::guard() 回傳的 Guard 會從工作階段或請求中取出驗證狀態。Guard 取得使用者時,會將處理委派給已設定的提供者。
UserProvider 回傳的值必須是實作 Illuminate\Contracts\Auth\Authenticatable 的物件,而不是儲存位置的陣列或 SDK 的回應。
從套件註冊 Auth::provider
在 Service Provider 的 boot 中註冊
Laravel 會依 auth.providers.*.driver 的值,呼叫透過 Auth::provider($name, $callback) 註冊的回呼。回呼會收到應用程式與提供者設定。
在套件的 Service Provider 中,要在驗證服務被使用之前完成註冊。
DirectoryClientManager 與 DirectoryUserProvider 是套件註冊到容器中的類別。$config 來自使用端應用程式的 auth.php,因此可以從中讀取連線名稱、租戶等建立提供者所需的值。
Auth::provider 註冊的是驗證使用者提供者的名稱。它與 Auth::extend 註冊的自訂 Guard 驅動是不同的擴充點。即使兩者都使用,也要將 Guard 的職責與使用者儲存的職責保持在不同的類別中。
在 auth.php 中連接提供者與 Guard
將註冊的名稱指定為 auth.providers 的 driver,並從 Guard 參照該提供者。
directory-webGuard 參照directory-users提供者。directory-users的driver為directory,因此會選用前面的回呼。- 產生
SessionGuard,並使用產生的UserProvider取得使用者。
AuthManager 會在首次解析 Guard 時將其快取。並沒有在註冊提供者後替換已解析 Guard 的 API,因此要留意 Service Provider 的啟動順序,以及在測試中使用 Auth::forgetGuards()。若快取了 auth 設定,也不要直接從環境變數讀取連線資訊,而應先解析到設定中再傳給回呼。
實作 UserProvider 契約
Laravel 13 的 Illuminate\Contracts\Auth\UserProvider 要求以下 6 個方法。
null,不會以例外表示找不到使用者。儲存位置的逾時或通訊故障要轉換為 null,還是作為可重試的例外處理,由套件的契約決定。重要的是不要把驗證失敗與儲存故障都隱藏成相同的「認證資訊不正確」。
回傳 Authenticatable
以下是不直接回傳外部儲存的紀錄,而是將其轉換為 GenericUser 的最小範例。實際的套件也可以提供專用的使用者類別,讓使用者能以型別安全的方式存取額外屬性。
GenericUser 預設使用 id、password、remember_token 這些屬性名稱。若要使用其他名稱,請在實作 Authenticatable 的專用類別中覆寫 getAuthIdentifierName() 等方法。
以 ID 與 remember token 取得
retrieveById 會從儲存在工作階段中的驗證 ID 還原使用者。若支援透過 remember token 登入,則在儲存位置比對識別碼與權杖。
hash_equals 的引數限定為從儲存位置取得的字串與權杖,並避免將權杖輸出到日誌。若外部儲存不支援 remember token,請不要將 updateRememberToken 留空讓它看起來成功,而應在套件的驗證設定中明確說明無法使用 remember 功能。
分離認證資訊的搜尋與密碼驗證
不要在 retrieveByCredentials 中驗證密碼
Auth::attempt() 會先以 retrieveByCredentials 搜尋使用者,之後再以 validateCredentials 驗證密碼。若在搜尋方法中也進行密碼比較,會破壞 Guard 預期的處理順序與密碼重新雜湊。
password,也要將 password_confirmation 等鍵從儲存位置的搜尋條件中排除。請勿將密碼或存取權杖放入搜尋 API 的查詢、日誌或快取鍵中。將可接受的搜尋鍵限制在 email 等允許清單內的設計,也能有效避免將任意欄位傳給外部 API。
在 validateCredentials 中比較雜湊
驗證時使用應用程式的 Hasher,不要將明文密碼傳送到儲存位置或輸出到日誌。
$credentials['password'] 不存在,或使用者沒有密碼時,回傳 false。若將驗證委派給外部驗證 API,在遵守相同契約的同時,依照套件的例外方針處理失敗、逾時與速率限制。
維持密碼重新雜湊
登入成功後,Laravel 可以確認是否需要依設定的雜湊方式重新雜湊。自訂提供者需實作rehashPasswordIfRequired,僅在需要時更新儲存位置的雜湊。
Hasher 與儲存位置的密碼格式一致。
測試 Service Provider 與驗證流程
在套件的測試中,將儲存用戶端替換為 fake,並分別驗證UserProvider 的各項職責。特別要分開確認以下 3 點。
retrieveByCredentials不會將密碼傳給用戶端。- 只有正確的雜湊才能通過
validateCredentials。 - 僅在需要重新雜湊時呼叫更新 API。
expects 換成所用 mock 函式庫的 API。若使用真實的 HTTP 用戶端,請以 HTTP fake 確認傳送內容,並測試明文密碼不會出現在請求或日誌中。
在包含 Auth::provider 註冊的整合測試中,以 Testbench 等驗證以下順序。
- 載入套件的 Service Provider。
- 在
auth.providers中設定自訂driver。 - 從
auth.guards參照該提供者。 - 首次解析 Guard,並確認使用者取得被委派給 fake 用戶端。
- 在會變更設定或註冊的測試中,進入下一個案例前呼叫
Auth::forgetGuards()。
設計更新時的相容性
UserProvider 位於驗證的邊界,因此更新套件時要確認以下事項。
- 變更
Authenticatable的 ID、密碼、remember token 屬性名稱時,決定既有工作階段與 remember cookie 的處理方式。 - 變更外部儲存的 ID 格式或密碼雜湊方式時,確認舊使用者能否被還原並登入。
- 縮小
retrieveByCredentials的允許鍵時,確認與使用者傳給Auth::attempt的條件是否相容。 - 將儲存故障與驗證失敗區分開來,並決定不會讓使用者在登入畫面誤以為密碼錯誤而重新輸入的方針。
- 刪除 provider 名稱、
auth.php的設定鍵或連線設定之前,確認設定快取與部署程序。
相關頁面
自訂驗證 Guard 的實作
了解如何擴充 Guard 本身,並從工作階段或 API 權杖解析使用者。
Service Provider
了解註冊套件的 Service Provider 並在啟動時套用擴充的基礎。