Build a Secure API in PHP Using Laravel Passport

Time to read: 9 minutes

April 20, 2020

Written by

Oluyemi Olususi

Contributor

Reviewed by

Marcus Battle

Twilion

Build a Secure API in PHP Using Laravel Passport

Build a secure Laravel API using Laravel Passport

There is no way to avoid the topic of RESTful APIs when building backend resources for a mobile application or using any of the modern JavaScript frameworks. If by chance you are unaware, an API is an interface or code in this case, that allows two software programs to communicate with each other. Notably, it does not maintain session state between requests, hence, you will need to use tokens to authenticate and authorize users of your application.

Laravel makes building such a resource easy with a predefined provision for you to secure it appropriately. This tutorial will teach you how to build and secure your Laravel back-end API using Laravel passport. When we are finished, you will have learned how to secure your new Laravel API or provide an extra layer of security to existing ones.

Prerequisites

Basic knowledge of building applications with Laravel will be of help in this tutorial. Also, you need to ensure that you have installed Composer globally to manage dependencies. Lastly, Postman will be needed to test our endpoints.

What We’ll Build

To demonstrate how to build a secure Laravel API, we’ll build an API that will be used to create a list of top tech CEOs. This application will list the following about each CEO:

Name
The year they became CEO
Headquarters of their company and
What their company does

To secure this application, we will install Laravel Passport and generate an access token for each user after authentication. This will allow such users to have access to some of the secured endpoints.

Getting Started

To begin, you can either use Composer or Laravel installer to quickly scaffold a new Laravel application on your computer. Follow the instructions here on Laravel's official website to set up the Laravel installer. Once you are done, run the following command:

$ laravel new laravel-backend-api

To install the same application using Composer run the following command:

$ composer create-project --prefer-dist laravel/laravel laravel-backend-api

Depending on your preferred choice, the preceding commands will create a new folder named laravel-backend-api within the development folder, you installed Laravel and its dependencies in.

You can move into the newly created folder and run the application using the in built-in Laravel Artisan command as shown here:

// move into the project
$ cd laravel-backend-api

// run the application
$ php artisan serve

Navigate to http://localhost:8000 from your browser to view the welcome page:

Create a Database and Connect to It

Now that Laravel is installed and running, the next step is to create a connection to your database. First, ensure that you have created a database and then update the values of the following variables within the .env file:

DB_DATABASE
DB_USERNAME
DB_PASSWORD

The database is all set, but before we start building our API, we need to install and configure Laravel Passport.

Install And Configure Laravel Passport

Laravel Passport provides a full 0Auth2 server implementation for Laravel applications. With it, you can easily generate a personal access token to uniquely identify a currently authenticated user. This token will then be attached to every request allowing each user access protected routes. To begin, stop the application from running by hitting CTRL + C on your computer’s keyboard and install Laravel Passport using Composer as shown here:

$ composer require laravel/passport

Once the installation is complete, a new migration file containing the tables needed to store clients and access tokens will have been generated for your application. Run the following command to migrate your database:

$ php artisan migrate

Next, to create the encryption keys needed to generate secured access tokens, run the command below:

$ php artisan passport:install

Immediately after the installation process from the preceding command is finished, add the Laravel\Passport\HasApiTokens trait to your App\User model as shown here:

// app/User.php

<?php

namespace App;

...
use Laravel\Passport\HasApiTokens; // include this

class User extends Authenticatable
{
    use Notifiable, HasApiTokens; // update this line

    ...
}

One of the benefits of this trait is the access to a few helper methods that your model can use to inspect the authenticated user’s token and scopes.

Now, to register the routes necessary to issue and revoke access tokens (personal and client), you will call the Passport::routes method within the boot method of your AuthServiceProvider. To do this, open the app/Providers/AuthServiceProvider file and update its content as shown below:

// app/Providers/AuthServiceProvider.php

<?php

namespace App\Providers;

use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;
use Illuminate\Support\Facades\Gate;
use Laravel\Passport\Passport; // add this 

class AuthServiceProvider extends ServiceProvider
{
    /**
     * The policy mappings for the application.
     *
     * @var array
     */
    protected $policies = [
         'App\Model' => 'App\Policies\ModelPolicy', // uncomment this line
    ];

    /**
     * Register any authentication / authorization services.
     *
     * @return void
     */
    public function boot()
    {
        $this->registerPolicies();

        Passport::routes(); // Add this
    }
}

After registering Passport::routes(), Laravel Passport is almost ready to handle all authentication and authorization processes within your application.

Finally, for your application to be ready to use Passport’s TokenGuard

to authenticate any incoming API requests, open the config/auth configuration file and set the driver option of the api authentication guard to passport:

// config/auth

<?php

return [
    ...

    'guards' => [
        'web' => [
            'driver' => 'session',
            'provider' => 'users',
        ],

        'api' => [
            'driver' => 'passport', // set this to passport
            'provider' => 'users',
            'hash' => false,
        ],
    ],

    ...
];

Create a Migration File for the Company

Every new installation of Laravel comes with a pre-generated User model and migration file. This is useful for maintaining a standard database structure for your database. Open the app/User.php file and ensure that it is similar to this:

// app/User.php

<?php

namespace App;

use Illuminate\Contracts\Auth\MustVerifyEmail;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Passport\HasApiTokens;

class User extends Authenticatable
{
    use Notifiable, HasApiTokens;

    /**
     * The attributes that are mass assignable.
     *
     * @var array
     */
    protected $fillable = [
        'name', 'email', 'password',
    ];

    /**
     * The attributes that should be hidden for arrays.
     *
     * @var array
     */
    protected $hidden = [
        'password', 'remember_token',
    ];

    /**
     * The attributes that should be cast to native types.
     *
     * @var array
     */
    protected $casts = [
        'email_verified_at' => 'datetime',
    ];
}

Also for the user migration file in database/migrations/***_create_users_table.php:

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

class CreateUsersTable extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::create('users', function (Blueprint $table) {
            $table->id();
            $table->string('name');
            $table->string('email')->unique();
            $table->timestamp('email_verified_at')->nullable();
            $table->string('password');
            $table->rememberToken();
            $table->timestamps();
        });
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        Schema::dropIfExists('users');
    }
}

The fields specified in the file above will suffice for the credentials required from the users of our application, hence there will be no need to modify it.

Next, we will use the artisan command to create a model instance and generate a database migration file for the CEO table:

$ php artisan make:model CEO -m

The preceding command will create a model within the app directory and a new migration file in database/migrations folder. The -m option is short for --migration and it tells the artisan command to create a migration file for our model. Next, open the newly created migration file and update its content as shown here:

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

class CreateCEOSTable extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::create('c_e_o_s', function (Blueprint $table) {
            $table->id();
            $table->string('name');
            $table->string('company_name');
            $table->year('year');
            $table->string('company_headquarters');
            $table->string('what_company_does');
            $table->timestamps();
        });
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        Schema::dropIfExists('c_e_o_s');
    }
}

Here, we included name, company_name, year, company_headquarters and what_company_does fields.

Now open the app/CEO.php file and use the following content for it:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class CEO extends Model
{
    protected $fillable = [
        'name', 'company_name', 'year', 'company_headquarters', 'what_company_does'
    ];
}

Here, we specified the attributes that should be mass assignable, as all Eloquent models protect against mass-assignment by default.

Run the migration command again to update the database with the newly created table and fields using the following command:

$ php artisan migrate

Now that the database is updated, we will proceed to create controllers for the application. We will also create a couple of endpoints that will handle registration, login, and creating the details of a CEO as explained earlier.

Create controllers

Controllers accept incoming HTTP requests and redirect them to the appropriate action or methods to process such requests and return the appropriate response. Since we are building an API, most of the responses will be in JSON format. This is mostly considered the standard format for RESTful APIs.

Authentication controller

We will start by using the artisan command to generate an Authentication Controller for our application. This controller will process and handle requests for registration and login for a user into the application.

$ php artisan make:controller API/AuthController

This will create a new API folder within app/Http/Controllers and then creates a new file named AuthController.php within it. Open the newly created controller file and use the following content for it:

<?php

namespace App\Http\Controllers\API;

use App\Http\Controllers\Controller;
use App\User;
use Illuminate\Http\Request;

class AuthController extends Controller
{
    public function register(Request $request)
    {
        $validatedData = $request->validate([
            'name' => 'required|max:55',
            'email' => 'email|required|unique:users',
            'password' => 'required|confirmed'
        ]);

        $validatedData['password'] = bcrypt($request->password);

        $user = User::create($validatedData);

        $accessToken = $user->createToken('authToken')->accessToken;

        return response([ 'user' => $user, 'access_token' => $accessToken]);
    }

    public function login(Request $request)
    {
        $loginData = $request->validate([
            'email' => 'email|required',
            'password' => 'required'
        ]);

        if (!auth()->attempt($loginData)) {
            return response(['message' => 'Invalid Credentials']);
        }

        $accessToken = auth()->user()->createToken('authToken')->accessToken;

        return response(['user' => auth()->user(), 'access_token' => $accessToken]);

    }
}

The register method above handled the registration process for users of our application. To handle validation and ensure that all the required fields for registration are filled, we used Laravel’s validation method. This validator will ensure that the name, email, password and password_confirmation fields are required and return the appropriate feedback.

Lastly, the login method ensures that the appropriate credentials are inputted before authenticating a user. If authenticated successfully, an accessToken is generated to uniquely identify the logged in user and send a JSON response. Any subsequent HTTP requests sent to a secured or protected route will require that the generated accessToken be passed as an Authorization header for the process to be successful. Otherwise, the user will receive an unauthenticated response.

Creating the CEO Controller

Here, you will use the same artisan command to automatically create a new controller. This time around we will create an API resource controller. Laravel resource controllers are controllers that handle all HTTP requests for a particular Model. In this case, we want to create a controller that will handle all requests for the CEO model, which include creating, reading, updating, and deleting. To achieve this, run the following command:

$ php artisan make:controller API/CEOController --api --model=CEO

The command above will generate an API resource controller that does not include the create and edit view since we are only building APIs. Navigate to app/Http/Controllers/API/CEOController.php and update its contents as shown below:

<?php

namespace App\Http\Controllers\API;

use App\CEO;
use App\Http\Controllers\Controller;
use App\Http\Resources\CEOResource;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Validator;

class CEOController extends Controller
{
    /**
     * Display a listing of the resource.
     *
     * @return \Illuminate\Http\Response
     */
    public function index()
    {
        $ceos = CEO::all();
        return response([ 'ceos' => CEOResource::collection($ceos), 'message' => 'Retrieved successfully'], 200);
    }

    /**
     * Store a newly created resource in storage.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return \Illuminate\Http\Response
     */
    public function store(Request $request)
    {
        $data = $request->all();

        $validator = Validator::make($data, [
            'name' => 'required|max:255',
            'year' => 'required|max:255',
            'company_headquarters' => 'required|max:255',
            'what_company_does' => 'required'
        ]);

        if($validator->fails()){
            return response(['error' => $validator->errors(), 'Validation Error']);
        }

        $ceo = CEO::create($data);

        return response([ 'ceo' => new CEOResource($ceo), 'message' => 'Created successfully'], 200);
    }

    /**
     * Display the specified resource.
     *
     * @param  \App\CEO  $ceo
     * @return \Illuminate\Http\Response
     */
    public function show(CEO $ceo)
    {
        return response([ 'ceo' => new CEOResource($ceo), 'message' => 'Retrieved successfully'], 200);

    }

    /**
     * Update the specified resource in storage.
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  \App\CEO  $ceo
     * @return \Illuminate\Http\Response
     */
    public function update(Request $request, CEO $ceo)
    {

        $ceo->update($request->all());

        return response([ 'ceo' => new CEOResource($ceo), 'message' => 'Retrieved successfully'], 200);
    }

    /**
     * Remove the specified resource from storage.
     *
     * @param \App\CEO $ceo
     * @return \Illuminate\Http\Response
     * @throws \Exception
     */
    public function destroy(CEO $ceo)
    {
        $ceo->delete();

        return response(['message' => 'Deleted']);
    }
}

A quick view at the code snippet above shows that we created five different methods; each housing logic to carry out a particular function. Here is an overview of what each method does:

index: This method retrieves the entire list of CEOs from the database and returns it as a resource collection in a JSON structure. More details about the Laravel resource collection will be shared in the next section.
store: This method receives the instance of the HTTP request to create new CEO details via dependency injection using $request to retrieve all the values posted. It also ensures that all the required fields are not submitted as an empty request. Lastly, it returns the information of the newly created CEO details as a JSON response.
show: This method uniquely identifies a particular CEO and returns the details as a JSON response.
update: This receives the HTTP request and the particular item that needs to be edited as a parameter. It runs an update on the instance of the model passed into it and returns the appropriate response.
`destroy: This method receives the instance of a particular item that needs to be deleted and removes it from the database.

Some methods require a specific model ID to uniquely verify an item such as show() , update(), and destroy(). One thing to note here is that we were able to inject the model instances directly. This is due to using implicit route model binding in Laravel.

Once in place, Laravel will help to inject the instance CEO into our methods and return a 404 status code if not found. This makes it very easy to use the instance of the model directly, without necessarily running a query to retrieve the model that corresponds to that ID.

You can read more about implicit route model binding here on the official documentation of Laravel.

Create a Resource

Laravel Eloquent resources allow you to convert your models and collections into JSON format. It works as a data transformation layer between the database and the controllers. This helps provide a uniform interface that can be used wherever you need it within your application. Let’s create one for our CEO model by using the following command:

$ php artisan make:resource CEOResource

This will create a new resource file named CEOResource.php within the app/Http/Resources directory. Go ahead and open the newly created file. The content will look like this:

<?php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\JsonResource;

class CEOResource extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return array
     */
    public function toArray($request)
    {
        return parent::toArray($request);
    }
}

The parent::toArray($request) inside the toArray() method will automatically convert all visible model attributes as part of the JSON response.

Gain a deeper understanding of the benefits offered by Eloquent resources here.

Update Routes File

To complete the set up of the endpoints for the methods created within our controllers, update the routes.api.php file with the following contents:

Route::post('/register', 'Api\AuthController@register');
Route::post('/login', 'Api\AuthController@login');

Route::apiResource('/ceo', 'Api\CEOController')->middleware('auth:api');

To view the entire list of the routes created for this application, run the following command from the terminal:

$ php artisan route:list

You will see similar contents as shown below:

This will give you an idea of all the routes for our application.

NOTE: Please bear in mind that all the routes inside the routes/api.php file will be prefixed with /api/, hence you will need to include that when sending HTTP requests to the endpoints created earlier.

Run the Application

Now, test all the logic implemented so far by running the application with:

$ php artisan serve

We will use Postman for the remainder of this tutorial to test the endpoints. Download it here if you don’t have it installed on your machine.

Register user

To register a user, send a POST HTTP request to this endpoint http://localhost:8000/api/register and input the appropriate details as shown here:

Now, your details might not be similar to this, but here is what the key and value of your requests should look like:

KEY                                       VALUE
name                                     John Doe
email                                    john@me.com
password                                  password
password_confirmation          password

Login

Once the registration is successful, you can proceed to http://localhost:8000/api/login and enter your details to get authenticated:

Now, assuming that you used the same key and value specified in the previous section, your request should be similar to this:

KEY                                       VALUE
email                                    john@me.com
password                                  password

Add Bearer token

After the login, copy the value of the access_token from the response and click on the Authorization tab and select Bearer Token from the dropdown and paste the value of the access_token copied earlier:

Create CEO

Next, create a new CEO with the details similar to the one shown below:

Fetch the list of CEOs

To retrieve the list of CEOs created so far, send a GET HTTP request to this endpoint http://localhost:8000/api/ceo as shown below:

Show CEO

View the details of a particular CEO by sending a GET HTTP request to this URL http://localhost:8000/api/ceo/1:

Please note that 1 is used for the endpoint here to specify the id of a particular record that needs to be retrieved from the database. You can target any record here using the id.

Edit CEO

Delete CEO

Conclusion

In this tutorial, we have learned how to secure any RESTful API built with Laravel using Laravel Passport. The example created in this tutorial covers the basic CRUD (create, read, update and delete) processes required by most applications.

I hope this gives you a solid foundation that can be improved on for your existing project and new ones. Please feel free to explore the codebase of this application by downloading it here on GitHub.

For more information about Laravel and Laravel Passport, don’t hesitate to visit the official documentation.

Olususi Oluyemi is a tech enthusiast, programming freak, and a web development junkie who loves to embrace new technology.

Related Resources

Twilio Docs

From APIs to SDKs to sample apps

API reference documentation, SDKs, helper libraries, quickstarts, and tutorials for your language and platform.

Resource Center

The latest ebooks, industry reports, and webinars

Learn from customer engagement experts to improve your own communication.

Ahoy

Twilio's developer community hub

Best practices, code samples, and inspiration to build communications and digital engagement experiences.

Build a Secure API in PHP Using Laravel Passport

Related Posts

Related Resources

From APIs to SDKs to sample apps

The latest ebooks, industry reports, and webinars

Twilio's developer community hub