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',
    ],
    
    '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' => AppUser::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 a configuration file config/mongo.php that holds the default MongoDB connection settings.

 [
    '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 an interface file app/Services/Contracts/NosqlServiceInterface.php with the following contents.


It's a pretty simple interface that declares the basic CRUD methods that a class must define that implements this interface.
Now, let's define an actual class at app/Database/MongoDatabase.php.
connection = new MongoClient( "mongodb://{$host}:{$port}" );
    $this->database = $this->connection->{$database};
  }
 
  /**
   * @see AppServicesContractsNosqlServiceInterface::find()
   */
  public function find($collection, Array $criteria)
  {
    return $this->database->{$collection}->findOne($criteria);
  }

  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 that must implement the IlluminateContractsAuthAuthenticatable contract.
Go ahead and create a file app/Models/Auth/User.php with the following contents.
conn = $conn;
  }

  /**
   * Fetch user by Credentials
   *
   * @param array $credentials
   * @return IlluminateContractsAuthAuthenticatable
   */
  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 IlluminateContractsAuthAuthenticatable::getAuthIdentifierName()
   */
  public function getAuthIdentifierName()
  {
    return "username";
  }
 
  /**
   * {@inheritDoc}
   * @see IlluminateContractsAuthAuthenticatable::getAuthIdentifier()
   */
  public function getAuthIdentifier()
  {
    return $this->{$this->getAuthIdentifierName()};
  }

  /**
   * {@inheritDoc}
   * @see IlluminateContractsAuthAuthenticatable::getAuthPassword()
   */
  public function getAuthPassword()
  {
    return $this->password;
  }

  /**
   * {@inheritDoc}
   * @see IlluminateContractsAuthAuthenticatable::getRememberToken()
   */
  public function getRememberToken()
  {
    if (! empty($this->getRememberTokenName())) {
      return $this->{$this->getRememberTokenName()};
    }
  }

  /**
   * {@inheritDoc}
   * @see IlluminateContractsAuthAuthenticatable::setRememberToken()
   */
  public function setRememberToken($value)
  {
    if (! empty($this->getRememberTokenName())) {
      $this->{$this->getRememberTokenName()} = $value;
    }
  }

  /**
   * {@inheritDoc}
   * @see IlluminateContractsAuthAuthenticatable::getRememberTokenName()
   */
  public function getRememberTokenName()
  {
    return $this->rememberTokenName;
  }
}
You should have already noticed that AppModelsAuthUser implements the IlluminateContractsAuthAuthenticatable 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 that'll 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 that deals with the user retrieval from the back end.
Go ahead and create a file app/Extensions/MongoUserProvider.php as shown below.
model = $userModel;
  }

  /**
   * Retrieve a user by the given credentials.
   *
   * @param  array  $credentials
   * @return IlluminateContractsAuthAuthenticatable|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  IlluminateContractsAuthAuthenticatable  $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 IlluminateContractsAuthUserProvider 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 that 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 that interacts with the MongoUserProvider authentication provider.
Set Up the Authentication Guard
As we discussed earlier, the guard in the Laravel authentication system provisions how the user is authenticated. In our case, we'll check the presence of the jsondata request parameter that should contain the JSON-encoded string of the credentials.
In this section, we'll create a guard that interacts with the authentication provider that was just created in the last section.
Go ahead and create a file app/Services/Auth/JsonGuard.php with the following contents.
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 IlluminateContractsAuthAuthenticatable|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 IlluminateContractsAuthGuard 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 IlluminateContractsAuthUserProvider. In our case, we'll pass an instance of AppExtensionsMongoUserProvider, 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 that 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.
 'AppPoliciesModelPolicy',
  ];

  /**
   * Register any authentication / authorization services.
   *
   * @return void
   */
  public function boot()
  {
    $this->registerPolicies();
    
    $this->app->bind('AppDatabaseMongoDatabase', function ($app) {
      return new MongoDatabase(config('mongo.defaults.host'), config('mongo.defaults.port'), config('mongo.defaults.database'));
    });
    
    $this->app->bind('AppModelsAuthUser', function ($app) {
      return new User($app->make('AppDatabaseMongoDatabase'));
    });

    // add custom guard provider
    Auth::provider('mongo', function ($app, array $config) {
      return new MongoUserProvider($app->make('AppModelsAuthUser'));
    });

    // 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(
      'AppServicesContractsNosqlServiceInterface',
      'AppDatabaseMongoDatabase'
    );
  }
}
Let's go through the boot method that contains most of the provider bindings.
To start with, we'll create bindings for the AppDatabaseMongoDatabase and AppModelsAuthUser elements.
$this->app->bind('AppDatabaseMongoDatabase', function ($app) {
  return new MongoDatabase(config('mongo.defaults.host'), config('mongo.defaults.port'), config('mongo.defaults.database'));
});

$this->app->bind('AppModelsAuthUser', function ($app) {
  return new User($app->make('AppDatabaseMongoDatabase'));
});
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('AppModelsAuthUser'));
});
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 a register method that we've used to bind the AppServicesContractsNosqlServiceInterface interface to the AppDatabaseMongoDatabase implementation.
$this->app->bind(
  'AppServicesContractsNosqlServiceInterface',
  'AppDatabaseMongoDatabase'
);
So whenever there's a need to resolve the AppServicesContractsNosqlServiceInterface dependency, Laravel responds with the implementation of the AppDatabaseMongoDatabase 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 AppDatabaseMongoDatabase implementation with the CouchDB 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 that 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 a pretty basic controller file app/Http/Controllers/MongoController.php as shown below.
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 IlluminateContractsAuthGuard guard. Since we've set the custom guard as the default guard in the auth.php file, it's the AppServicesAuthJsonGuard that'll be injected actually!
Next, we've called the validate method of the AppServicesAuthJsonGuard class, which in turn initiates a series of method calls:

It calls the retrieveByCredentials method of the AppExtensionsMongoUserProvider class.
The retrieveByCredentials method calls the fetchUserByCredentials method of the User AppModelsAuthUser class.
The fetchUserByCredentials method calls the find method of the AppDatabaseMongoDatabase to retrieve the user credentials.
Finally, the find method of the AppDatabaseMongoDatabase returns the response!

If everything works as expected, we should get an 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 http://your-laravel-site/custom/mongo/login without passing any parameters and you should see a "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 a success message if the user is present in your database.
Please note that this is just for example purposes, to demonstrate how the 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. If you want me to write on any specific topics, don't forget to drop me a line!
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.
I would love to hear your feedback and suggestions, so shout out loud using the feed below!