- Introduction
- Installation
- Configuration
- Issuing Access Tokens
- Password Grant Tokens
- Personal Access Tokens
- Protecting Routes
- Token Scopes
- Consuming Your API With JavaScript
Laravel already makes it easy to perform authentication via traditional login forms, but what about APIs? APIs typically use tokens to authenticate users and do not maintain session state between requests. Laravel makes API authentication a breeze using Laravel Passport, which provides a full OAuth2 server implementation for your Laravel application in a matter of minutes. Passport is built on top of the League OAuth2 server that is maintained by Alex Bilbie.
{note} This documentation assumes you are already familiar with OAuth2. If you do not know anything about OAuth2, consider familiarizing yourself with the general terminology and features of OAuth2 before continuing.
To get started, install Passport via the Composer package manager:
composer require laravel/passport
Next, register the Passport service provider in the providers
array of your config/app.php
configuration file:
Laravel\Passport\PassportServiceProvider::class,
The Passport service provider registers its own database migration directory with the framework, so you should migrate your database after registering the provider. The Passport migrations will create the tables your application needs to store clients and access tokens:
php artisan migrate
Next, you should run the passport:install
command. This command will create the encryption keys needed to generate secure access tokens. In addition, the command will create "personal access" and "password grant" clients which will be used to generate access tokens:
php artisan passport:install
After running this command, add the Laravel\Passport\HasApiTokens
trait to your App\User
model. This trait will provide a few helper methods to your model which allow you to inspect the authenticated user's token and scopes:
<?php
namespace App;
use Laravel\Passport\HasApiTokens;
use Illuminate\Notifications\Notifiable;
use Illuminate\Foundation\Auth\User as Authenticatable;
class User extends Authenticatable
{
use HasApiTokens, Notifiable;
}
Next, you should call the Passport::routes
method within the boot
method of your AuthServiceProvider
. This method will register the routes necessary to issue access tokens and revoke access tokens, clients, and personal access tokens:
<?php
namespace App\Providers;
use Laravel\Passport\Passport;
use Illuminate\Support\Facades\Gate;
use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;
class AuthServiceProvider extends ServiceProvider
{
/**
* The policy mappings for the application.
*
* @var array
*/
protected $policies = [
'App\Model' => 'App\Policies\ModelPolicy',
];
/**
* Register any authentication / authorization services.
*
* @return void
*/
public function boot()
{
$this->registerPolicies();
Passport::routes();
}
}
Finally, in your config/auth.php
configuration file, you should set the driver
option of the api
authentication guard to passport
. This will instruct your application to use Passport's TokenGuard
when authenticating incoming API requests:
'guards' => [
'web' => [
'driver' => 'session',
'provider' => 'users',
],
'api' => [
'driver' => 'passport',
'provider' => 'users',
],
],
{note} In order to use the Passport Vue components, you must be using the Vue JavaScript framework. These components also use the Bootstrap CSS framework. However, even if you are not using these tools, the components serve as a valuable reference for your own frontend implementation.
Passport ships with a JSON API that you may use to allow your users to create clients and personal access tokens. However, it can be time consuming to code a frontend to interact with these APIs. So, Passport also includes pre-built Vue components you may use as an example implementation or starting point for your own implementation.
To publish the Passport Vue components, use the vendor:publish
Artisan command:
php artisan vendor:publish --tag=passport-components
The published components will be placed in your resources/assets/js/components
directory. Once the components have been published, you should register them in your resources/assets/js/app.js
file:
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')
);
Once the components have been registered, you may drop them into one of your application's templates to get started creating clients and personal access tokens:
<passport-clients></passport-clients>
<passport-authorized-clients></passport-authorized-clients>
<passport-personal-access-tokens></passport-personal-access-tokens>
By default, Passport issues long-lived access tokens that never need to be refreshed. If you would like to configure a shorter token lifetime, you may use the tokensExpireIn
and refreshTokensExpireIn
methods. These methods should be called from the boot
method of your AuthServiceProvider
:
/**
* Register any authentication / authorization services.
*
* @return void
*/
public function boot()
{
$this->registerPolicies();
Passport::routes();
Passport::tokensExpireIn(Carbon::now()->addDays(15));
Passport::refreshTokensExpireIn(Carbon::now()->addDays(30));
}
By default, Passport does not delete your revoked access tokens from the database. Over time, a large number of these tokens can accumulate in your database. If you would like Passport to automatically delete your revoked tokens, you should call the pruneRevokedTokens
method from the boot
method of your AuthServiceProvider
:
use Laravel\Passport\Passport;
Passport::pruneRevokedTokens();
This method will not delete all revoked tokens immediately. Instead, revoked tokens will be deleted when a user requests a new access token or refreshes an existing token.
Using OAuth2 with authorization codes is how most developers are familiar with OAuth2. When using authorization codes, a client application will redirect a user to your server where they will either approve or deny the request to issue an access token to the client.
First, developers building applications that need to interact with your application's API will need to register their application with yours by creating a "client". Typically, this consists of providing the name of their application and a URL that your application can redirect to after users approve their request for authorization.
The simplest way to create a client is using the passport:client
Artisan command. This command may be used to create your own clients for testing your OAuth2 functionality. When you run the client
command, Passport will prompt you for more information about your client and will provide you with a client ID and secret:
php artisan passport:client
Since your users will not be able to utilize the client
command, Passport provides a JSON API that you may use to create clients. This saves you the trouble of having to manually code controllers for creating, updating, and deleting clients.
However, you will need to pair Passport's JSON API with your own frontend to provide a dashboard for your users to manage their clients. Below, we'll review all of the API endpoints for managing clients. For convenience, we'll use Vue to demonstrate making HTTP requests to the endpoints.
{tip} If you don't want to implement the entire client management frontend yourself, you can use the frontend quickstart to have a fully functional frontend in a matter of minutes.
This route returns all of the clients for the authenticated user. This is primarily useful for listing all of the user's clients so that they may edit or delete them:
this.$http.get('/oauth/clients')
.then(response => {
console.log(response.data);
});
This route is used to create new clients. It requires two pieces of data: the client's name
and a redirect
URL. The redirect
URL is where the user will be redirected after approving or denying a request for authorization.
When a client is created, it will be issued a client ID and client secret. These values will be used when requesting access tokens from your application. The client creation route will return the new client instance:
const data = {
name: 'Client Name',
redirect: 'http://example.com/callback'
};
this.$http.post('/oauth/clients', data)
.then(response => {
console.log(response.data);
})
.catch (response => {
// List errors on response...
});
This route is used to update clients. It requires two pieces of data: the client's name
and a redirect
URL. The redirect
URL is where the user will be redirected after approving or denying a request for authorization. The route will return the updated client instance:
const data = {
name: 'New Client Name',
redirect: 'http://example.com/callback'
};
this.$http.put('/oauth/clients/' + clientId, data)
.then(response => {
console.log(response.data);
})
.catch (response => {
// List errors on response...
});
This route is used to delete clients:
this.$http.delete('/oauth/clients/' + clientId)
.then(response => {
//
});
Once a client has been created, developer's may use their client ID and secret to request an authorization code and access token from your application. First, the consuming application should make a redirect request to your application's /oauth/authorize
route like so:
Route::get('/redirect', function () {
$query = http_build_query([
'client_id' => 'client-id',
'redirect_uri' => 'http://example.com/callback',
'response_type' => 'code',
'scope' => '',
]);
return redirect('http://your-app.com/oauth/authorize?'.$query);
});
{tip} Remember, the
/oauth/authorize
route is already defined by thePassport::routes
method. You do not need to manually define this route.
When receiving authorization requests, Passport will automatically display a template to the user allowing them to approve or deny the authorization request. If they approve the request, they will be redirected back to the redirect_uri
that was specified by the consuming application. The redirect_uri
must match the redirect
URL that was specified when the client was created.
If you would like to customize the authorization approval screen, you may publish Passport's views using the vendor:publish
Artisan command. The published views will be placed in resources/views/vendor/passport
:
php artisan vendor:publish --tag=passport-views
If the user approves the authorization request, they will be redirected back to the consuming application. The consumer should then issue a POST
request to your application to request an access token. The request should include the authorization code that was issued by when the user approved the authorization request. In this example, we'll use the Guzzle HTTP library to make the POST
request:
Route::get('/callback', function (Request $request) {
$http = new GuzzleHttp\Client;
$response = $http->post('http://your-app.com/oauth/token', [
'form_params' => [
'grant_type' => 'authorization_code',
'client_id' => 'client-id',
'client_secret' => 'client-secret',
'redirect_uri' => 'http://example.com/callback',
'code' => $request->code,
],
]);
return json_decode((string) $response->getBody(), true);
});
This /oauth/token
route will return a JSON response containing access_token
, refresh_token
, and expires_in
attributes. The expires_in
attribute contains the number of seconds until the access token expires.
{tip} Like the
/oauth/authorize
route, the/oauth/token
route is defined for you by thePassport::routes
method. There is no need to manually define this route.
If your application issues short-lived access tokens, users will need to refresh their access tokens via the refresh token that was provided to them when the access token was issued. In this example, we'll use the Guzzle HTTP library to refresh the token:
$http = new GuzzleHttp\Client;
$response = $http->post('http://your-app.com/oauth/token', [
'form_params' => [
'grant_type' => 'refresh_token',
'refresh_token' => 'the-refresh-token',
'client_id' => 'client-id',
'client_secret' => 'client-secret',
'scope' => '',
],
]);
return json_decode((string) $response->getBody(), true);
This /oauth/token
route will return a JSON response containing access_token
, refresh_token
, and expires_in
attributes. The expires_in
attribute contains the number of seconds until the access token expires.
The OAuth2 password grant allows your other first-party clients, such as a mobile application, to obtain an access token using an e-mail address / username and password. This allows you to issue access tokens securely to your first-party clients without requiring your users to go through the entire OAuth2 authorization code redirect flow.
Before your application can issue tokens via the password grant, you will need to create a password grant client. You may do this using the passport:client
command with the --password
option. If you have already run the passport:install
command, you do not need to run this command:
php artisan passport:client --password
Once you have created a password grant client, you may request an access token by issuing a POST
request to the /oauth/token
route with the user's email address and password. Remember, this route is already registered by the Passport::routes
method so there is no need to define it manually. If the request is successful, you will receive an access_token
and refresh_token
in the JSON response from the server:
$http = new GuzzleHttp\Client;
$response = $http->post('http://your-app.com/oauth/token', [
'form_params' => [
'grant_type' => 'password',
'client_id' => 'client-id',
'client_secret' => 'client-secret',
'username' => 'taylor@laravel.com',
'password' => 'my-password',
'scope' => '',
],
]);
return json_decode((string) $response->getBody(), true);
{tip} Remember, access tokens are long-lived by default. However, you are free to configure your maximum access token lifetime if needed.
When using the password grant, you may wish to authorize the token for all of the scopes supported by your application. You can do this by requesting the *
scope. If you request the *
scope, the can
method on the token instance will always return true
. This scope may only be assigned to a token that is issued using the password
grant:
$response = $http->post('http://your-app.com/oauth/token', [
'form_params' => [
'grant_type' => 'password',
'client_id' => 'client-id',
'username' => 'taylor@laravel.com',
'password' => 'my-password',
'scope' => '*',
],
]);
Sometimes, your users may want to issue access tokens to themselves without going through the typical authorization code redirect flow. Allowing users to issue tokens to themselves via your application's UI can be useful for allowing users to experiment with your API or may serve as a simpler approach to issuing access tokens in general.
{note} Personal access tokens are always long-lived. Their lifetime is not modified when using the
tokensExpireIn
orrefreshTokensExpireIn
methods.
Before your application can issue personal access tokens, you will need to create a personal access client. You may do this using the passport:client
command with the --personal
option. If you have already run the passport:install
command, you do not need to run this command:
php artisan passport:client --personal
Once you have created a personal access client, you may issue tokens for a given user using the createToken
method on the User
model instance. The createToken
method accepts the name of the token as its first argument and an optional array of scopes as its second argument:
$user = App\User::find(1);
// Creating a token without scopes...
$token = $user->createToken('Token Name')->accessToken;
// Creating a token with scopes...
$token = $user->createToken('My Token', ['place-orders'])->accessToken;
Passport also includes a JSON API for managing personal access tokens. You may pair this with your own frontend to offer your users a dashboard for managing personal access tokens. Below, we'll review all of the API endpoints for managing personal access tokens. For convenience, we'll use Vue to demonstrate making HTTP requests to the endpoints.
{tip} If you don't want to implement the personal access token frontend yourself, you can use the frontend quickstart to have a fully functional frontend in a matter of minutes.
This route returns all of the scopes defined for your application. You may use this route to list the scopes a user may assign to a personal access token:
this.$http.get('/oauth/scopes')
.then(response => {
console.log(response.data);
});
This route returns all of the personal access tokens that the authenticated user has created. This is primarily useful for listing all of the user's token so that they may edit or delete them:
this.$http.get('/oauth/personal-access-tokens')
.then(response => {
console.log(response.data);
});
This route creates new personal access tokens. It requires two pieces of data: the token's name
and the scopes
that should be assigned to the token:
const data = {
name: 'Token Name',
scopes: []
};
this.$http.post('/oauth/personal-access-tokens', data)
.then(response => {
console.log(response.data.accessToken);
})
.catch (response => {
// List errors on response...
});
This route may be used to delete personal access tokens:
this.$http.delete('/oauth/personal-access-tokens/' + tokenId);
Passport includes an authentication guard that will validate access tokens on incoming requests. Once you have configured the api
guard to use the passport
driver, you only need to specify the auth:api
middleware on any routes that require a valid access token:
Route::get('/user', function () {
//
})->middleware('auth:api');
When calling routes that are protected by Passport, your application's API consumers should specify their access token as a Bearer
token in the Authorization
header of their request. For example, when using the Guzzle HTTP library:
$response = $client->request('GET', '/api/user', [
'headers' => [
'Accept' => 'application/json',
'Authorization' => 'Bearer '.$accessToken,
],
]);
Scopes allow your API clients to request a specific set of permissions when requesting authorization to access an account. For example, if you are building an e-commerce application, not all API consumers will need the ability to place orders. Instead, you may allow the consumers to only request authorization to access order shipment statuses. In other words, scopes allow your application's users to limit the actions a third-party application can perform on their behalf.
You may define your API's scopes using the Passport::tokensCan
method in the boot
method of your AuthServiceProvider
. The tokensCan
method accepts an array of scope names and scope descriptions. The scope description may be anything you wish and will be displayed to users on the authorization approval screen:
use Laravel\Passport\Passport;
Passport::tokensCan([
'place-orders' => 'Place orders',
'check-status' => 'Check order status',
]);
When requesting an access token using the authorization code grant, consumers should specify their desired scopes as the scope
query string parameter. The scope
parameter should be a space-delimited list of scopes:
Route::get('/redirect', function () {
$query = http_build_query([
'client_id' => 'client-id',
'redirect_uri' => 'http://example.com/callback',
'response_type' => 'code',
'scope' => 'place-orders check-status',
]);
return redirect('http://your-app.com/oauth/authorize?'.$query);
});
If you are issuing personal access tokens using the User
model's createToken
method, you may pass the array of desired scopes as the second argument to the method:
$token = $user->createToken('My Token', ['place-orders'])->accessToken;
Passport includes two middleware that may be used to verify that an incoming request is authenticated with a token that has been granted a given scope. To get started, add the following middleware to the $routeMiddleware
property of your app/Http/Kernel.php
file:
'scopes' => \Laravel\Passport\Http\Middleware\CheckScopes::class,
'scope' => \Laravel\Passport\Http\Middleware\CheckForAnyScope::class,
The scopes
middleware may be assigned to a route to verify that the incoming request's access token has all of the listed scopes:
Route::get('/orders', function () {
// Access token has both "check-status" and "place-orders" scopes...
})->middleware('scopes:check-status,place-orders');
The scope
middleware may be assigned to a route to verify that the incoming request's access token has at least one of the listed scopes:
Route::get('/orders', function () {
// Access token has either "check-status" or "place-orders" scope...
})->middleware('scope:check-status,place-orders');
Once an access token authenticated request has entered your application, you may still check if the token has a given scope using the tokenCan
method on the authenticated User
instance:
use Illuminate\Http\Request;
Route::get('/orders', function (Request $request) {
if ($request->user()->tokenCan('place-orders')) {
//
}
});
When building an API, it can be extremely useful to be able to consume your own API from your JavaScript application. This approach to API development allows your own application to consume the same API that you are sharing with the world. The same API may be consumed by your web application, mobile applications, third-party applications, and any SDKs that you may publish on various package managers.
Typically, if you want to consume your API from your JavaScript application, you would need to manually send an access token to the application and pass it with each request to your application. However, Passport includes a middleware that can handle this for you. All you need to do is add the CreateFreshApiToken
middleware to your web
middleware group:
'web' => [
// Other middleware...
\Laravel\Passport\Http\Middleware\CreateFreshApiToken::class,
],
This Passport middleware will attach a laravel_token
cookie to your outgoing responses. This cookie contains an encrypted JWT that Passport will use to authenticate API requests from your JavaScript application. Now, you may make requests to your application's API without explicitly passing an access token:
this.$http.get('/user')
.then(response => {
console.log(response.data);
});
When using this method of authentication, you will need to send the CSRF token with every request via the X-CSRF-TOKEN
header. Laravel will automatically send this header if you are using the default Vue configuration that is included with the framework:
Vue.http.interceptors.push((request, next) => {
request.headers['X-CSRF-TOKEN'] = Laravel.csrfToken;
next();
});
{note} If you are using a different JavaScript framework, you should make sure it is configured to send this header with every outgoing request.