Multiple authentication guard drivers (including API) in Laravel 5.2
(This is part of a series of posts on New Features in Laravel 5.2. Check back soon for more.)
Let's get back to Laravel 5.2 features, shall we? 5.2 introduced a significant boost to the power of the entire authentication system, including making it much simpler to have multiple "guards" running at once.
Why should you care? #
The default authentication guard in Laravel prior to 5.2 (now named the
web guard) is your traditional web-based application authentication layer: username and password post to a controller, which checks the credentials and redirects if they are invalid; if valid, the user information gets saved to the session. Not all of those pieces are absolutely necessary but that's the general mindset.
But what if you want to have an API running in the same app, and it uses JSON web tokens (or some other stateless, non-session authentication mechanism)? In the past you'd have to jump through a lot of hoops to have multiple authentication drivers running at the same time.
Laravel 5.2's default auth guards #
In 5.2, not only is it simple to have multiple auth drivers running, it actually already works that way out of the box.
If you check
config/auth.php, you'll see two guards set out of the box:
web, which is the classic Laravel authentication layer, and
api, which is a stateless (no session memory) token-based driver.
Both, as you can see, connect to the same "provider".
Auth providers are also customizable. They're the definition of how the system should store and retrieve information about your users. Each is defined by an instance of
'guards' => [ 'web' => [ 'driver' => 'session', 'provider' => 'users', ], 'api' => [ 'driver' => 'token', 'provider' => 'users', ], ],
If you look up higher in
config/auth.php, you can see that the default Auth guard will be "web". That means any time you use Auth functions, middleware, or façades inside your application, they will default to the
web guard unless you explicitly specify otherwise.
Introducing the token auth driver #
web uses the classic
session driver, what's this new
token driver we're seeing powering the
Jacob Bennett has written a fantastic post on that already: API Token Authentication in Laravel 5.2.
Check out his post to learn more about how it works, but here's the short of it:
- Add an
api_tokencolumn to your
userstable. 60-character string, unique.
- Instead of using the
authmiddleware in your route definition, use the
- In your API routes, use
Auth::guard('api')->user()to get your user instead of
As you can see, we need to store an
api_token for each user, and every incoming request that's guarded by the
api guard will require a query parameter named
api_token with a valid API token set to authenticate that user. And since it's stateless, every request will need to have this API token set; one successful request won't affect the next request.
If you're not familiar with token-based authentication, the consuming application (e.g. an iOS application) will have gotten, and saved, the token for the authenticating user prior to this request, so it will be creating its API calls using that known token as a part of the URL. For example, an iOS app might want to get a list of its user's friends; when the user first authenticated the application with your web site/API the app received a token and stored it. Now, it will generate requests using URLs like this:
Using non-default drivers #
As you can see in the token example above, there are two primary places we're going to be using drivers other than the default: in the auth guard middleware, and when we're using convenience features like
Auth::user() in our code.
You can choose which guard you're using to protect your routes by adding a colon and the guard name after
auth in the middleware key (e.g.
Route::get('whatever', ['middleware' => 'auth:api'])).
You can choose which guard you're calling manually in your code by making
guard('guardname') the first call of a fluent chain every time you use the Auth façade (e.g.
Creating your own guards and drivers #
Creating your own guard is simple, beause each guard is just a key (
api) that points to a specific configuration of a driver (
token) and a provider (
users). They're configured, as mentioned above, in
'guards' => [ 'web' => [ 'driver' => 'session', 'provider' => 'users', ], 'api' => [ 'driver' => 'token', 'provider' => 'users', ], 'matts-fancy-api-guard' => [ 'driver' => 'token', 'provider' => 'users', ], ],
But as you can tell, that doesn't really do much unless you're changing the driver or the provider.
Creating your own driver is not quite as simple as creating your own guard. The docs have a spot about Creating your own auth driver, and you're essentially going to be creating your own implementation of
Illuminate\Contracts\Auth\Guard and then registering it as a driver in a service provider somewhere.
The docs also cover how to create your own user provider.
That's it. Enjoy.
Comments? I'm @stauffermatt on Twitter