UserProvider. For example, you can use an external directory, an existing membership system or a dedicated API as the authentication store.
This is different from creating a new guard. You only supply the implementation that looks up and verifies users for the existing session or token guards. To change how the guard itself authenticates, see Custom Authentication Guards.
This page targets Laravel 13 and references the
13.x branch of the official documentation and the implementation in Framework v13.43.0. Check the contract methods and password rehashing behavior in every Laravel version your package supports.Separate the responsibilities of guards and UserProviders
The guard returned byAuth::guard() reads the authentication state from the session or request. When the guard needs a user, it delegates to the configured provider.
The value a
UserProvider returns must be an object that implements Illuminate\Contracts\Auth\Authenticatable, not the store’s array or an SDK response.
Register Auth::provider from a package
Register in the service provider’s boot method
Laravel calls the callback you register with Auth::provider($name, $callback) according to the value of auth.providers.*.driver. The callback receives the application and the provider configuration.
In your package’s service provider, register it before the authentication services are used.
DirectoryClientManager and DirectoryUserProvider are classes your package registers in the container. $config comes from the consuming application’s auth.php, so you can read the connection name, tenant and any other values needed to build the provider from it.
Auth::provider registers the name of an authentication user provider. It is a separate extension point from the custom guard driver that Auth::extend registers. Even when you use both, keep the guard’s responsibilities and the user store’s responsibilities in separate classes.
Connect the provider and guard in auth.php
Set the registered name as the driver in auth.providers, and reference that provider from a guard.
- The
directory-webguard references thedirectory-usersprovider. - The
driverofdirectory-usersisdirectory, so the callback above is selected. - A
SessionGuardis created and uses the generatedUserProviderto retrieve users.
AuthManager caches a guard the first time it is resolved. There is no API that replaces an already resolved guard after the provider is registered, so pay attention to the boot order of service providers and to using Auth::forgetGuards() in tests. If the auth configuration is cached, resolve connection details into the configuration and pass them to the callback instead of reading environment variables directly.
Implement the UserProvider contract
In Laravel 13, Illuminate\Contracts\Auth\UserProvider requires the following six methods.
null; a missing user is not represented by an exception. Your package contract decides whether store timeouts and network failures become null or a retryable exception. What matters is that you do not hide store failures behind the same “invalid credentials” as an authentication failure.
Return an Authenticatable
This minimal example converts a record from the external store into a GenericUser instead of returning it as is. A real package may provide a dedicated user class so that consumers get typed access to extra attributes.
GenericUser uses the attribute names id, password and remember_token by default. To use other names, override getAuthIdentifierName() and related methods in a dedicated class that implements Authenticatable.
Retrieve by ID and remember token
retrieveById restores the user from the auth identifier stored in the session. If you support remember-token login, compare the identifier and token against the store.
hash_equals to the string retrieved from the store and the token, and never write tokens to logs. If the external store does not support remember tokens, do not leave updateRememberToken empty so that it appears to succeed. State clearly in your package’s authentication configuration that the remember feature is unavailable.
Separate credential lookup from password validation
Do not validate the password in retrieveByCredentials
Auth::attempt() first looks up the user with retrieveByCredentials, then validates the password with validateCredentials. If the lookup method also compares passwords, it breaks the processing order the guard expects and password rehashing.
password but also keys such as password_confirmation from the store’s lookup criteria. Never include passwords or access tokens in lookup API queries, logs or cache keys. Restricting the accepted lookup keys to an allowlist such as email is also an effective way to avoid passing arbitrary fields to an external API.
Compare hashes in validateCredentials
Use the application’s Hasher for validation, and never send plain-text passwords to the store or write them to logs.
false when $credentials['password'] is missing or the user has no password. If you delegate validation to an external authentication API, keep the same contract and handle failures, timeouts and rate limits according to your package’s exception policy.
Keep password rehashing working
After a successful login, Laravel can check whether the password needs rehashing for the configured hashing algorithm. A custom provider implementsrehashPasswordIfRequired and updates the hash in the store only when needed.
Hasher you use matches the password format of the store.
Test the service provider and the authentication flow
In package tests, swap the store client for a fake and verify each responsibility of theUserProvider separately. In particular, check these three points separately.
retrieveByCredentialsdoes not pass the password to the client.- Only a correct hash passes
validateCredentials. - The update API is called only when rehashing is needed.
expects above with the API of the mock library you use. When you use a real HTTP client, check the outgoing request with an HTTP fake and test that the plain-text password never appears in requests or logs.
In integration tests that include the Auth::provider registration, use Testbench or similar to verify the following order.
- Load the package’s service provider.
- Set the custom
driverinauth.providers. - Reference that provider from
auth.guards. - Resolve the guard for the first time and confirm that user retrieval is delegated to the fake client.
- In tests that change configuration or registration, call
Auth::forgetGuards()before moving on to the next case.
Design for compatibility across updates
AUserProvider sits on the authentication boundary, so check the following when you update your package.
- If you change the attribute names of the
AuthenticatableID, password or remember token, decide how to handle existing sessions and remember cookies. - If you change the ID format or password hashing algorithm of the external store, confirm that existing users can still be restored and log in.
- If you narrow the allowed keys of
retrieveByCredentials, check compatibility with the conditions consumers were passing toAuth::attempt. - Distinguish store failures from authentication failures, and decide on a policy that does not make users re-enter a supposedly wrong password on the login screen.
- Before removing the provider name, the
auth.phpconfiguration keys or the connection settings, check the configuration cache and your deployment steps.
Related pages
Custom Authentication Guards
Learn how to extend the guard itself and resolve users from sessions or API tokens.
Service providers
Learn the basics of registering your package’s service provider and applying extensions at boot.
Primary sources
- Laravel official docs: Adding Custom User Providers
- Laravel official docs: User Provider Contract
- AuthManager: provider() and guard resolution
- CreatesUserProviders: creating custom providers
- UserProvider contract
- Authenticatable contract
- EloquentUserProvider: default implementation
- GenericUser: Authenticatable built from attributes