Introducing Laravel Passport

API authentication can be tricky. OAuth 2 is the reigning ruler of the various standards that you might consider, but it’s complex and difficult to implement—even with the great packages available (League and Luca among them).

We’re talking many routes, dozens of migrations, complicated configuration, and much more—even with amazing packages trying to simplify the situation as much as possible.

Laravel Passport is native OAuth 2 server for Laravel apps. Like Cashier and Scout, you’ll bring it into your app with Composer. It uses the League OAuth2 Server package as a dependency but provides a simple, easy-to-learn and easy-to-implement syntax.

Laying the groundwork in Laravel 5.2

In Laravel 5.2, we got a new structure in our authentication system: multiple auth drivers. This means that, instead of there being a single auth system that is responsible for one app at a time, you can apply different auth systems to different routes (or in different environments). Out of the box, we got the same auth system we’ve always had and a new token-based auth system for APIs.

Laravel 5.2’s token system was fine enough—but it wasn’t really any more secure than normal password login. It was there, most importantly, to lay the groundwork for packages like Passport, which essentially adds a new “passport” driver you can use in your app to make certain routes OAuth2 authed.

Installing Passport

Follow these steps on any Laravel 5.3 app and you’ll be on your way to the easiest OAuth 2 server possible:

Install Passport via Composer.
bash composer require laravel/passport
Go to config/app.php, and add Laravel\Passport\PassportServiceProvider to your providers list.
Run the new migrations; because of 5.3’s multiple migrations paths, the new Passport migrations will be included in your normal migration path.
bash php artisan migrate
Run php artisan passport:install, which will create encryption keys (local files) and personal/password grant tokens (inserted into your database)
Go to your User class and import the trait Laravel\Passport\HasApiTokens
Add the OAuth2 routes: go to AuthServiceProvider and use Laravel\Passport\Passport, then in the boot() method run Passport::routes() // AuthServiceProvider public function boot() { $this->registerPolicies(); Passport::routes(); }
[Optional] Define at least one scope in the boot() method of AuthServiceProvider, after Passport::routes() using Passport::tokensCan // AuthServiceProvider public function boot() { $this->registerPolicies(); Passport::routes(); Passport::tokensCan([ 'conference' => 'Access your conference information' ]); }
In config/auth.php, guards.api.driver; change the api guard to use passport driver instead of token
php // config/auth.php return [ ... 'guards' => [ ... 'api' => [ 'driver' => 'passport', // was previously 'token' 'provider' => 'users' ] ] ];
Build the Laravel auth scaffold; we’ll need our users to be able to log in before we can authenticate them with Passport bash php artisan make:auth
Publish the Vue components, if you want to use them bash php artisan vendor:publish --tag=passport-components

This is a lot, but basically we’re importing that package, registering it with Laravel, setting our User up to authenticate using it, adding a few routes for authentication and callbacks, and defining our first scope for users to have access via.

At this point, you’re theoretically done. The server is installed and it works. That was fast! Your routes work, and you can create your clients and tokens either via Passport’s Artisan commands or by building your own administrative tool on top of Passport’s API. But before you make your decision, take a look at that API and the Vue components Passport provides out of the box.

Passport’s management API

Passport exposes a JSON API for your frontend to consume to let you manage your clients and tokens.

Out of the box, Passport comes with Vue components that show how you might want to interact with this API in your app. You could use these components and call it done, or you could write your own tool to interact with the API.

Passport’s default Vue frontend

Out of the box, Passport comes with three Vue components: passport-clients, which shows all of the clients you’ve registered; passport-authorized-clients, which shows all of the clients you’ve given access to your account; and passport-personal-access-tokens, which shows all of the “personal” tokens you’ve created for testing the API. We can register them in app.js:

Vue.component(
    'passport-clients',
    require('./components/passport/Clients.vue')
);

Vue.component(
    'passport-authorized-clients',
    require('./components/passport/AuthorizedClients.vue')
);

Vue.component(
    'passport-personal-access-tokens',
    require('./components/passport/PersonalAccessTokens.vue')
);

const app = new Vue({
    el: 'body'
});

And then use them in our HTML:

<!-- let people make clients -->
<passport-clients></passport-clients>

<!-- list of clients people have authorized to access our account -->
<passport-authorized-clients></passport-authorized-clients>

<!-- make it simple to generate a token right in the UI to play with -->
<passport-personal-access-tokens></passport-personal-access-tokens>

Let’s walk through how they work and what they do.

We’ll follow the example Taylor set in his talk at Laracon: We’ll have a Passport-enabled server app at passport.dev and a consumer app at consumer.dev.