How to Create a Custom Authentication Guard in Laravel

In this article, we’re going to cover the authentication system in the Laravel framework. The main aim of this article is to create a custom authentication guard by extending the core authentication system.

Laravel provides a very solid authentication system in the core that makes the implementation of basic authentication a breeze. In fact, you just need to run a couple of artisan commands to set up the scaffolding of an authentication system.

Moreover, the system itself is designed in such a way that you could extend it and plug in your custom authentication adapters as well. That’s what we'll discuss in detail throughout this article. Before we go ahead and dive into the implementation of the custom authentication guard, we’ll start with a discussion of the basic elements in the Laravel authentication system—guards and providers.

The Core Elements: Guards and Providers

The Laravel authentication system is made up of two elements at its core—guards and providers.

Guards

You could think of a guard as a way of supplying the logic that’s used to identify the authenticated users. In the core, Laravel provides different guards like session and token. The session guard maintains the state of the user in each request by cookies, and on the other hand the token guard authenticates the user by checking a valid token in every request.

So, as you can see, the guard defines the logic of authentication, and it’s not necessary that it always deals with that by retrieving valid credentials from the back end. You may implement a guard that simply checks the presence of a specific thing in request headers and authenticates users based on that.

Later in this article, we’ll implement a guard that checks certain JSON parameters in request headers and retrieves the valid user from the MongoDB back end.

Providers

If the guard defines the logic of authentication, the authentication provider is responsible for retrieving the user from the back-end storage. If the guard requires that the user must be validated against the back-end storage then the implementation of retrieving the user goes into the authentication provider.

Laravel ships with two default authentication providers—Database and Eloquent. The Database authentication provider deals with the straightforward retrieval of the user credentials from the back-end storage, while Eloquent provides an abstraction layer that does the needful.

In our example, we’ll implement a MongoDB authentication provider that fetches the user credentials from the MongoDB back end.

So that was a basic introduction to guards and providers in the Laravel authentication system. From the next section onwards, we’ll focus on the development of the custom authentication guard and provider!

A Quick Glance at the File Setup

Let's have a quick look at the list of files that we'll implement throughout the course of this article.

• 
  config/auth.php: It's the authentication configuration file in which we'll add an entry of our custom guard.


• 
  config/mongo.php: It's the file that holds the MongoDB configuration.


• 
  app/Services/Contracts/NosqlServiceInterface.php: It's an interface that our custom Mongo database class implements.


• 
  app/Database/MongoDatabase.php: It's a main database class that interacts with MongoDB.


• 
  app/Models/Auth/User.php: It's the User model class that implements the Authenticable contract.


• 
  app/Extensions/MongoUserProvider.php: It's an implementation of the authentication provider.


• 
  app/Services/Auth/JsonGuard.php: It's an implementation of the authentication guard driver.


• 
  app/Providers/AuthServiceProvider.php: This is an existing file that we'll use to add our service container bindings.


• 
  app/Http/Controllers/MongoController.php: It's a demo controller file that we'll implement to test our custom guard.

Don't worry if the list of the files doesn't make much sense yet as we'll discuss everything in detail as we go through it.

Deep Dive Into the Implementation

In this section, we'll go through the implementation of the required files.

The first thing that we need to do is to inform Laravel about our custom guard. Go ahead and enter the custom guard details in the config/auth.php file as shown.

...
...
'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],
 
    'api' => [
        'driver' => 'token',
        'provider' => 'users',
        'hash' => false,
    ],
     
    'custom' => [
      'driver' => 'json',
      'provider' => 'mongo',
    ],
],
...
...

As you can see, we've added our custom guard under the custom key.

Next, we need to add an associated provider entry in the providers section.

...
...
'providers' => [
    'users' => [
        'driver' => 'eloquent',
        'model' => App\User::class,
    ],
    'mongo' => [
        'driver' => 'mongo'
    ],
 
    // 'users' => [
    //     'driver' => 'database',
    //     'table' => 'users',
    // ],
],
...
...

We've added our provider entry under the mongo key.

Finally, let's change the default authentication guard from web to custom.

...
...
'defaults' => [
    'guard' => 'custom',
    'passwords' => 'users',
],
...
...

Of course, it won't work yet, as we've not implemented the necessary files yet. And that's what we'll discuss in the next couple of sections.

Set Up the MongoDB Driver

In this section, we'll implement the necessary files that talk to the underlying MongoDB instance.

Let's first create the config/mongo.php configuration file, which holds the default MongoDB connection settings.

<?php
return [
  'defaults' => [
    'host' => '{HOST_IP}',
    'port' => '{HOST_PORT}',
    'database' => '{DB_NAME}'
  ]
];

Of course, you need to change the placeholder values as per your settings.

Instead of directly creating a class that interacts with MongoDB, we'll create an interface in the first place.

The benefit of creating an interface is that it provides a contract that a developer must adhere to while implementing it. Also, our implementation of MongoDB could be easily swapped with another NoSQL implementation if needed.

Go ahead and create the app/Services/Contracts/NosqlServiceInterface.php interface file with the following contents.

<?php
// app/Services/Contracts/NosqlServiceInterface.php
namespace App\Services\Contracts;
 
Interface NosqlServiceInterface
{
  /**
   * Create a Document
   *
   * @param string $collection Collection/Table Name
   * @param array  $document   Document
   * @return boolean
   */
  public function create($collection, Array $document);
  
  /**
   * Update a Document
   *
   * @param string $collection Collection/Table Name
   * @param mix    $id         Primary Id
   * @param array  $document   Document
   * @return boolean
   */
  public function update($collection, $id, Array $document);
 
  /**
   * Delete a Document
   *
   * @param string $collection Collection/Table Name
   * @param mix    $id         Primary Id
   * @return boolean
   */
  public function delete($collection, $id);
  
  /**
   * Search Document(s)
   *
   * @param string $collection Collection/Table Name
   * @param array  $criteria   Key-value criteria
   * @return array
   */
  public function find($collection, Array $criteria);
}

It's a pretty simple interface which declares the basic CRUD methods that a class must define that implements this interface.

Now, let's define the app/Database/MongoDatabase.php class with the following contents.

<?php
// app/Database/MongoDatabase.php
namespace App\Database;
 
use App\Services\Contracts\NosqlServiceInterface;
 
class MongoDatabase implements NosqlServiceInterface
{
  private $manager;
  private $database;
     
  public function __construct($host, $port, $database)
  {
    $this->database = $database;
    $this->manager = new \MongoDB\Driver\Manager( "mongodb://".$host.":".$port."/".$database );
  }

  /**
   * @see \App\Services\Contracts\NosqlServiceInterface::find()
   */
  public function find($collection, Array $criteria)
  {
    $query = new \MongoDB\Driver\Query($criteria);
    $result = $this->manager->executeQuery($this->database.".".$collection, $query);

    $user = array();
    foreach ($result as $row) {
        $user['username'] = $row->username;
        $user['password'] = $row->password;
    }

    return $user;
  }
 
  public function create($collection, Array $document) {}
  public function update($collection, $id, Array $document) {}
  public function delete($collection, $id) {}
}

Of course, I assume that you've installed MongoDB and the corresponding MongoDB PHP extension.

The __construct method instantiates the MongoClient class with the necessary parameters. The other important method we're interested in is the find method, which retrieves the record based on the criteria provided as method arguments.

So that was the implementation of the MongoDB driver, and I tried to keep it as simple as possible.

Set Up the User Model

Adhering to the standards of the authentication system, we need to implement the User model, which must implement the Illuminate\Contracts\Auth\Authenticatable contract.

Go ahead and create a file app/Models/Auth/User.php with the following contents.

<?php
// app/Models/Auth/User.php
namespace App\Models\Auth;
 
use Illuminate\Contracts\Auth\Authenticatable as AuthenticatableContract;
use App\Services\Contracts\NosqlServiceInterface;
 
class User implements AuthenticatableContract
{
  private $conn;
  
  private $username;
  private $password;
  protected $rememberTokenName = 'remember_token';
 
  public function __construct(NosqlServiceInterface $conn)
  {
    $this->conn = $conn;
  }
 
  /**
   * Fetch user by Credentials
   *
   * @param array $credentials
   * @return Illuminate\Contracts\Auth\Authenticatable
   */
  public function fetchUserByCredentials(Array $credentials)
  {
    $arr_user = $this->conn->find('users', ['username' => $credentials['username']]);
     
    if (! is_null($arr_user)) {
      $this->username = $arr_user['username'];
      $this->password = $arr_user['password'];
    }
 
    return $this;
  }
 
  /**
   * {@inheritDoc}
   * @see \Illuminate\Contracts\Auth\Authenticatable::getAuthIdentifierName()
   */
  public function getAuthIdentifierName()
  {
    return "username";
  }
  
  /**
   * {@inheritDoc}
   * @see \Illuminate\Contracts\Auth\Authenticatable::getAuthIdentifier()
   */
  public function getAuthIdentifier()
  {
    return $this->{$this->getAuthIdentifierName()};
  }
 
  /**
   * {@inheritDoc}
   * @see \Illuminate\Contracts\Auth\Authenticatable::getAuthPassword()
   */
  public function getAuthPassword()
  {
    return $this->password;
  }
 
  /**
   * {@inheritDoc}
   * @see \Illuminate\Contracts\Auth\Authenticatable::getRememberToken()
   */
  public function getRememberToken()
  {
    if (! empty($this->getRememberTokenName())) {
      return $this->{$this->getRememberTokenName()};
    }
  }
 
  /**
   * {@inheritDoc}
   * @see \Illuminate\Contracts\Auth\Authenticatable::setRememberToken()
   */
  public function setRememberToken($value)
  {
    if (! empty($this->getRememberTokenName())) {
      $this->{$this->getRememberTokenName()} = $value;
    }
  }
 
  /**
   * {@inheritDoc}
   * @see \Illuminate\Contracts\Auth\Authenticatable::getRememberTokenName()
   */
  public function getRememberTokenName()
  {
    return $this->rememberTokenName;
  }
}

You should have already noticed that App\Models\Auth\User implements the Illuminate\Contracts\Auth\Authenticatable contract.

Most of the methods implemented in our class are self-explanatory. Having said that, we've defined the fetchUserByCredentials method, which retrieves the user from the available back end. In our case, it'll be a MongoDatabase class which will be called to retrieve the necessary information.

So that's the implementation of the User model.

Set Up the Authentication Provider

As we discussed earlier, the Laravel authentication system consists of two elements—guards and providers.

In this section, we'll create an authentication provider, which deals with the user retrieval from the back end.

Go ahead and create a file app/Extensions/MongoUserProvider.php as shown below.

<?php
// app/Extensions/MongoUserProvider.php
namespace App\Extensions;
 
use Illuminate\Support\Str;
use Illuminate\Contracts\Auth\UserProvider;
use Illuminate\Contracts\Auth\Authenticatable;
 
class MongoUserProvider implements UserProvider
{
  /**
   * The Mongo User Model
   */
  private $model;
 
  /**
   * Create a new mongo user provider.
   *
   * @return \Illuminate\Contracts\Auth\Authenticatable|null
   * @return void
   */
  public function __construct(\App\Models\Auth\User $userModel)
  {
    $this->model = $userModel;
  }
 
  /**
   * Retrieve a user by the given credentials.
   *
   * @param  array  $credentials
   * @return \Illuminate\Contracts\Auth\Authenticatable|null
   */
  public function retrieveByCredentials(array $credentials)
  {
      if (empty($credentials)) {
          return;
      }
 
    $user = $this->model->fetchUserByCredentials(['username' => $credentials['username']]);
 
      return $user;
  }
  
  /**
   * Validate a user against the given credentials.
   *
   * @param  \Illuminate\Contracts\Auth\Authenticatable  $user
   * @param  array  $credentials  Request credentials
   * @return bool
   */
  public function validateCredentials(Authenticatable $user, Array $credentials)
  {
      return ($credentials['username'] == $user->getAuthIdentifier() &&
    md5($credentials['password']) == $user->getAuthPassword());
  }
 
  public function retrieveById($identifier) {}
 
  public function retrieveByToken($identifier, $token) {}
 
  public function updateRememberToken(Authenticatable $user, $token) {}
}

Again, you need to make sure that the custom provider must implement the Illuminate\Contracts\Auth\UserProvider contract.

Moving ahead, it defines two important methods—retrieveByCredentials and validateCredentials.

The retrieveByCredentials method is used to retrieve the user credentials using the User model class which was discussed in the earlier section. On the other hand, the validateCredentials method is used to validate a user against the given set of credentials.

And that was the implementation of our custom authentication provider. In the next section, we'll go ahead and create a guard which interacts with the MongoUserProvider authentication provider.

Set Up the Authentication Guard

As we discussed earlier, the guard in the Laravel authentication system provisions how a user is authenticated. In our case, we'll check the presence of the jsondata request parameter which should contain the JSON-encoded string of the credentials.

In this section, we'll create a guard which interacts with the authentication provider which was just created in the last section.

Go ahead and create a file app/Services/Auth/JsonGuard.php with the following contents.

<?php
// app/Services/Auth/JsonGuard.php
namespace App\Services\Auth;
 
use Illuminate\Http\Request;
use Illuminate\Contracts\Auth\Guard;
use Illuminate\Contracts\Auth\UserProvider;
use GuzzleHttp\json_decode;
use phpDocumentor\Reflection\Types\Array_;
use Illuminate\Contracts\Auth\Authenticatable;
 
class JsonGuard implements Guard
{
  protected $request;
  protected $provider;
  protected $user;
 
  /**
   * Create a new authentication guard.
   *
   * @param  \Illuminate\Contracts\Auth\UserProvider  $provider
   * @param  \Illuminate\Http\Request  $request
   * @return void
   */
  public function __construct(UserProvider $provider, Request $request)
  {
    $this->request = $request;
    $this->provider = $provider;
    $this->user = NULL;
  }
 
  /**
   * Determine if the current user is authenticated.
   *
   * @return bool
   */
  public function check()
  {
    return ! is_null($this->user());
  }
 
  /**
   * Determine if the current user is a guest.
   *
   * @return bool
   */
  public function guest()
  {
    return ! $this->check();
  }
 
  /**
   * Get the currently authenticated user.
   *
   * @return \Illuminate\Contracts\Auth\Authenticatable|null
   */
  public function user()
  {
    if (! is_null($this->user)) {
      return $this->user;
    }
  }
     
  /**
   * Get the JSON params from the current request
   *
   * @return string
   */
  public function getJsonParams()
  {
    $jsondata = $this->request->query('jsondata');
 
    return (!empty($jsondata) ? json_decode($jsondata, TRUE) : NULL);
  }
 
  /**
   * Get the ID for the currently authenticated user.
   *
   * @return string|null
  */
  public function id()
  {
    if ($user = $this->user()) {
      return $this->user()->getAuthIdentifier();
    }
  }
 
  /**
   * Validate a user's credentials.
   *
   * @return bool
   */
  public function validate(Array $credentials=[])
  {
    if (empty($credentials['username']) || empty($credentials['password'])) {
      if (!$credentials=$this->getJsonParams()) {
        return false;
      }
    }
 
    $user = $this->provider->retrieveByCredentials($credentials);
       
    if (! is_null($user) && $this->provider->validateCredentials($user, $credentials)) {
      $this->setUser($user);
 
      return true;
    } else {
      return false;
    }
  }
 
  /**
   * Set the current user.
   *
   * @param  Array $user User info
   * @return void
   */
  public function setUser(Authenticatable $user)
  {
    $this->user = $user;
    return $this;
  }
}

First of all, our class needs to implement the Illuminate\Contracts\Auth\Guard interface. Thus, we need to define all the methods declared in that interface.

The important thing to note here is that the __construct function requires an implementation of Illuminate\Contracts\Auth\UserProvider. In our case, we'll pass an instance of App\Extensions\MongoUserProvider, as we'll see in the later section.

Next, there's a function getJsonParams that retrieves the user credentials from the request parameter named jsondata. As it's expected that we'll receive a JSON encoded string of the user credentials, we've used the json_decode function to decode the JSON data.

In the validate function, the first thing we check is the existence of the $credentials argument. If it's not present, we'll call the getJsonParams method to retrieve user credentials from the request parameters.

Next, we call the retrieveByCredentials method of the MongoUserProvider provider that retrieves the user from the MongoDB database back end. Finally, it's the validateCredentials method of the MongoUserProvider provider that checks the validity of the user.

So that was the implementation of our custom guard. The next section describes how to stitch these pieces together to form a successful authentication system.

Putting It All Together

So far, we've developed all the elements of the custom authentication guard that should provide us a new authentication system. However, it won't work out of the box as we need to register it in the first place using the Laravel service container bindings.

As you should already know, the Laravel service provider is the right place to implement the necessary bindings.

Go ahead and open the file app/Providers/AuthServiceProvider.php which allows us to add authentication service container bindings. If it doesn't contain any custom changes, you could just replace it with the following contents.

<?php
// app/Providers/AuthServiceProvider.php
namespace App\Providers;
 
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Gate;
use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;
use App\Services\Auth\JsonGuard;
use App\Extensions\MongoUserProvider;
use App\Database\MongoDatabase;
use App\Models\Auth\User;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Config;
 
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();
     
    $this->app->bind('App\Database\MongoDatabase', function ($app) {
      return new MongoDatabase(config('mongo.defaults.host'), config('mongo.defaults.port'), config('mongo.defaults.database'));
    });
     
    $this->app->bind('App\Models\Auth\User', function ($app) {
      return new User($app->make('App\Database\MongoDatabase'));
    });
 
    // add custom guard provider
    Auth::provider('mongo', function ($app, array $config) {
      return new MongoUserProvider($app->make('App\Models\Auth\User'));
    });
 
    // add custom guard
    Auth::extend('json', function ($app, $name, array $config) {
      return new JsonGuard(Auth::createUserProvider($config['provider']), $app->make('request'));
    });
  }
 
  public function register()
  {
    $this->app->bind(
      'App\Services\Contracts\NosqlServiceInterface',
      'App\Database\MongoDatabase'
    );
  }
}

Let's go through the boot method which contains most of the provider bindings.

To start with, we'll create bindings for the App\Database\MongoDatabase and App\Models\Auth\User elements.

$this->app->bind('App\Database\MongoDatabase', function ($app) {
  return new MongoDatabase(config('mongo.defaults.host'), config('mongo.defaults.port'), config('mongo.defaults.database'));
});
 
$this->app->bind('App\Models\Auth\User', function ($app) {
  return new User($app->make('App\Database\MongoDatabase'));
});

It's been a while that we've been talking about provider and guard, and it's time to plug our custom guard into the Laravel authentication system.

We've used the provider method of the Auth Facade to add our custom authentication provider under the key mongo. Recall that the key reflects the settings that were added earlier in the auth.php file.

Auth::provider('mongo', function ($app, array $config) {
  return new MongoUserProvider($app->make('App\Models\Auth\User'));
});

In a similar way, we'll inject our custom guard implementation using the extend method of the Auth facade.

Auth::extend('json', function ($app, $name, array $config) {
  return new JsonGuard(Auth::createUserProvider($config['provider']), $app->make('request'));
});

Next, there's the register method which we've used to bind the App\Services\Contracts\NosqlServiceInterface interface to the App\Database\MongoDatabase implementation.

$this->app->bind(
  'App\Services\Contracts\NosqlServiceInterface',
  'App\Database\MongoDatabase'
);

So whenever there's a need to resolve the App\Services\Contracts\NosqlServiceInterface dependency, Laravel responds with the implementation of the App\Database\MongoDatabase adapter.

The benefit of using this approach is that one could easily swap the given implementation with a custom implementation. For example, let's say someone would like to replace the App\Database\MongoDatabase implementation with the CouchDB implementation adapter in future. In that case, they just need to add the corresponding binding in the register method.

So that was the service provider at your disposal. At this moment, we have everything which is required to test our custom guard implementation, so the next and concluding section is all about that.

Does It Work?

You've done all the hard work setting up your first custom authentication guard, and now it's time to reap the benefits as we'll go ahead and give it a try.

Let's quickly implement the app/Http/Controllers/MongoController.php controller as shown below.

<?php
// app/Http/Controllers/MongoController.php
namespace App\Http\Controllers;
 
use App\Http\Controllers\Controller;
use Illuminate\Contracts\Auth\Guard;
 
class MongoController extends Controller
{
  public function login(Guard $auth_guard)
  {
    if ($auth_guard->validate()) {
      // get the current authenticated user
      $user = $auth_guard->user();
     
      echo 'Success!';
    } else {
      echo 'Not authorized to access this page!';
    }
  }
}

Take a close look at the dependency of the login method, which requires the implementation of the Illuminate\Contracts\Auth\Guard guard. Since we've set the custom guard as the default guard in the auth.php file, it's the App\Services\Auth\JsonGuard that'll be injected actually!

Next, we've called the validate method of the App\Services\Auth\JsonGuard class, which in turn initiates a series of method calls:

• It calls the retrieveByCredentials method of the App\Extensions\MongoUserProvider class.


• The retrieveByCredentials method calls the fetchUserByCredentials method of the App\Models\Auth\User class.


• The fetchUserByCredentials method calls the find method of the App\Database\MongoDatabase to retrieve the user credentials.


• Finally, the find method of the App\Database\MongoDatabase returns the response!

If everything works as expected, we should get the authenticated user by calling the user method of our guard.

To access the controller, you should add an associated route in the routes/web.php file.

Route::get('/custom/mongo/login', 'MongoController@login');

Try accessing the URL https://your-laravel-site/custom/mongo/login without passing any parameters and you should see the not authorized message.

On the other hand, try something like http://your-laravel-site/custom/mongo/login?jsondata={"username":"admin","password":"admin"} and that should return the success message if the user is present in your database.

Please note that this is just for example purposes to demonstrate how a custom guard works. You should implement a foolproof solution for a feature like login. In fact, I've just provided an insight into the authentication flow; you're responsible for building a robust and secure solution for your application.

That ends our journey today, and hopefully I'll be back with more useful stuff.

Conclusion

The Laravel framework provides a solid authentication system in the core that could be extended if you want to implement a custom one. That was the topic of today's article to implement a custom guard and plug it in to the Laravel authentication workflow.

In the course of that, we went ahead and developed a system that authenticates the user based on the JSON payload in the request and matches it with the MongoDB database. And to achieve that, we ended up creating a custom guard and a custom provider implementation.

I hope the exercise has provided you an insight into the Laravel authentication flow, and you should now feel more confident about its inner workings.

For those of you who are either just getting started with Laravel or looking to expand your knowledge, site, or application with extensions, we have a variety of things you can study on Envato Market.