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.


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.


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.

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.

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

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

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.

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.

Powered by WPeMatico

Leave a Comment

Scroll to Top