What you'll learn
In this part of the series, you'll learn the following:
- What Sanctum is
- How to install and use Laravel Sanctum
- Implement the Sign-Up function
- Implement the Login function
- Implement the Logout function
- Restructure the routes to protected and public
Laravel Sanctum setup
Laravel Sanctum, also commonly known as Sanctum is a lightweight authentication system used to authenticate token-based APIs and SPAs (ReactJs, VueJs, etc). In this section, I will show you how to authenticate users with Sanctum.
Install Sanctum
Due to Laravel's aim to provide a great developer experience, the Laravel project you generated in the first part of the series includes Sanctum, and you can confirm that by going to composer.json
file, and it should be inside the require
array like so:
The green box is the require
array. If you can't find Sanctum inside the array in your composer.json
file, run the following command to install it:
composer require laravel/sanctum
The above command will install Sanctum inside your app, and you can confirm by checking the composer.json
file again.
Create personal access tokens migration
After confirming Sanctum's installation, the next thing is to create a personal access tokens table in the database, you do that by publishing Sanctum's configurations and migrations file by running the following in your command line:
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
The above command will create a create_personal_access_tokens_table.php
in your /database/migrations
folder and a sanctum.php
file inside the /config
folder, once you have verified the creation of those two files, the next thing to do is to migrate the new migration file, and you do that with the following command:
php artisan migrate
The above command will add a new personal_access_tokens
table to your database, check your database manager to verify:
Next, go to the app/Http/Kernel.php
file and replace the api
array inside the middlewareGroups
array with the following code:
'api' => [
\Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
'throttle:api',
\Illuminate\Routing\Middleware\SubstituteBindings::class,
],
The above code is the middleware that will be used to authenticate our API.
Next, I'll show you can how to protect routes in Laravel.
Protecting Routes
To protect your routes, you need to group the protected routes with a middleware function like so:
// posts routes
Route::group(['middleware' => ['auth:sanctum']], function () {
// protected routes go here
});
the above code uses the static group
function on the Route
Facade and adds the middleware array that utilizes the 'auth:sanctum'
middleware to protect the routes that you define inside the function. To show you how this works, I'll add all the post routes inside the function like so:
// posts routes
Route::group(['middleware' => ['auth:sanctum']], function () {
Route::resource('posts', PostController::class);
Route::get('/posts/search/{title}', [PostController::class, 'search']);
Route::get('/post/author/{id}', [PostController::class, 'get_author']);
});
Now try to get all posts by making a GET request to localhost:8000/api/posts
and you should get the following result:
The green box is the result you would get from the request, and it reads "message": "Unauthenticated."
, and that's it! the route has been protected successfully, Now you need to define the steps the user has to take to get authenticated. Next, we will define the signup
function.
Note: The above is just an example, I'm going to restructure all the routes later.
Next, I'll show you how to set up a controller for the functions related to authentication.
AuthController
You learned in the second part of the series that controllers are used to organizing functions in your application, So you'll need to create a controller that will contain all the functions related to authentication.
First, create a controller with artisan, name it AuthController like so:
php artisan make:controller AuthController
Note: You should not add the
--resource
flag, as we won't be using theCRUD
functionality here.
That should create a controller file that contains the following code:
<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
class AuthController extends Controller
{
//
}
Next, add the dependencies required which in this case will be:
use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Http\Response;
use Illuminate\Support\Facades\Hash;
Add the code above under the namespace App\Http\Controllers;
line.
- The
User
is the user model and migration that was created when you generated your Laravel application. - The
Request
is the object that contains any data the user sends to the server. - The
Response
is the object that contains any data the server sends back to the user. - The
Hash
containsbcrypt
function that will be used to hash the passwords.
Next, I'll show you how to create the Sign-Up function
Sign Up
For users to be able to sign in, you need to create the function. So create a public sign_up
function like so:
public function sign_up(Request $request){
}
Next, validate the data coming through the request object like so:
$data = $request->validate([
'name' => 'required|string',
'email' => 'required|string|unique:users,email',
'password' => 'required|string|confirmed'
]);
The above code validates the data using the validate
function.
- The name is a required string.
- The email is a required string and has to be a unique value inside the column in the users table.
- The password is a required string and needs to be confirmed, so the user needs to input it a second time.
Next, create user using the static create
function on the User
model like so:
$user = User::create([
'name' => $data['name'],
'email' => $data['email'],
'password' => bcrypt($data['password'])
]);
The above code uses the create
function with an array of the previous data
variable to create a user.
Note: The
password
in the above array is wrapped inbcrypt
function, so the password will be hashed before saving the user to the database.
Next, generate an authentication token using the createToken
function on the $user
like so:
$token = $user->createToken('apiToken')->plainTextToken;
The above code will create a token that will be sent along with every request to a protected route.
Next, create the response that will be sent back once the user has been created successfully:
$res = [
'user' => $user,
'token' => $token
];
return response($res, 201);
The above code created a variable named $res
which is an array that contains the created user
and the generated token
, and returns it using the response
function along with the status code 201
which means that a resource was created, which is the user and the token. Now the sign_up
function should look like so:
public function sign_up(Request $request){
$data = $request->validate([
'name' => 'required|string',
'email' => 'required|string|unique:users,email',
'password' => 'required|string|confirmed'
]);
$user = User::create([
'name' => $data['name'],
'email' => $data['email'],
'password' => bcrypt($data['password'])
]);
$token = $user->createToken('apiToken')->plainTextToken;
$res = [
'user' => $user,
'token' => $token
];
return response($res, 201);
}
Next, create a signup route for the above function like so:
Route::post('/signup', [AuthController::class, 'sign_up']);
Note: This route will be public.
You can now create a user by sending the required data to the /signup
route, like so:
- The purple box is the type of request you'll send for this route, which is a
POST
request. - The yellow box is the URL of the route
localhost:8000/api/signup
. - The red box is the data I sent to the server in
form-data
format. - The green box is the result you'll get after sending the request successfully - this will be the user that was created and the generated token.
Next, add the generated token as the bearer token
and send a GET request to the protected routes you defined earlier:
- The purple box is the type of request you'll send for this route, which is a
GET
request. - The yellow box is the URL of the route
localhost:8000/api/posts
. - The orange box is the type of token I sent to the server which is the
bearer token
. - The blue box is the token I sent to the server which is the token that was generated when I signed up(this is why you get logged in automatically once you sign up on any application).
- The green box is the result you'll get after sending the request successfully - this will be the posts in the database which was unavailable earlier because I was not authenticated.
Next, I'll show you how to create the Sign-In function.
Sign In
You need to create a login function so users can log in. To do so, create a login
function like so:
public function login(Request $request)
{
}
Next, validate the request data like so:
$data = $request->validate([
'email' => 'required|string',
'password' => 'required|string'
]);
- The email is a required string.
- The password is a required string.
Next, check if the user is registered like so:
$user = User::where('email', $data['email'])->first();
if (!$user || !Hash::check($data['password'], $user->password)) {
return response([
'msg' => 'incorrect username or password'
], 401);
}
The above code does the following:
- Define a
$user
variable that contains the user with the given email. - Check if the
$user
is registered and return'msg' => 'incorrect username or password'
with a401
status code if it isn't.
Note: 401 status code means the user is unauthorized.
Next, generate a token if the email passes the above check, like so:
$token = $user->createToken('apiToken')->plainTextToken;
The above code generates a token that will be used to log in.
Next, create the response that will be sent back to the user like so:
$res = [
'user' => $user,
'token' => $token
];
return response($res, 201);
The above code created a variable named $res
which is an array that contains the created user
and the generated token
, and returns it using the response
function along with the status code 201
which means that a resource was created, in this case the token. Now the login
function should look like so:
public function login(Request $request)
{
$data = $request->validate([
'email' => 'required|string',
'password' => 'required|string'
]);
$user = User::where('email', $data['email'])->first();
if (!$user || !Hash::check($data['password'], $user->password)) {
return response([
'msg' => 'incorrect username or password'
], 401);
}
$token = $user->createToken('apiToken')->plainTextToken;
$res = [
'user' => $user,
'token' => $token
];
return response($res, 201);
}
Next, create a login route for the above function like so:
Route::post('/login', [AuthController::class, 'login']);
Note: This route will be public.
You can now log in by sending the email and password of a registered user to the /login
route, like so:
- The purple box is the type of request you'll send for this route, which is a
POST
request. - The yellow box is the URL of the route:
localhost:8000/api/login
. - The red box is the data I sent to the server in
form-data
format. - The green box is the result you'll get after sending the request successfully - this will be the logged-in user and the generated token. Next, add the generated token as the bearer token, and viola! you are now authenticated and can visit protected routes.
Next, I'll show you how to create the Logout function
Logout
The login function is the simplest of all the AuthController
functions in our case.
First, create a public logout
function like so:
public function logout(Request $request)
{
}
Next, you need to delete the user's valid token, and you do that like so:
auth()->user()->tokens()->delete();
return [
'message' => 'user logged out'
];
The above function deletes the token for a logged-in user, which means the bearer token will no longer work and the user will be unauthenticated, and returns 'message' => 'user logged out'
.
Now, create a route for the logout function like so:
Route::post('/logout', [AuthController::class, 'logout']);
- The purple box is the type of request you'll send for this route, which is a
POST
request. - The yellow box is the URL of the route
localhost:8000/api/logout
. - The orange box is the type of token I sent to the server which is the
bearer token
. - The blue box is the token I sent to the server which is the token that was generated when I logged in.
- The green box is the result you'll get after sending the request successfully - this will be the message that was returned from the
logout
function.
Restructuring the routes
After the Signup, Login, and Logout functions have been implemented successfully, the next thing is to separate the protected routes and public routes.
In this case it will be required that you remove the resource
method that you used to group the CRUD
routes earlier because the create
, update
and delete
routes will now be protected because an unauthenticated user should not be able to create, update or delete posts.
So the api.php
file will look like so now:
// signup and login
Route::post('/signup', [AuthController::class, 'sign_up']);
Route::post('/login', [AuthController::class, 'login']);
// public post routes
Route::get('/posts/search/{title}', [PostController::class, 'search']);
Route::get('/post/author/{id}', [PostController::class, 'get_author']);
// public author routes
Route::get('/authors/search/{name}', [AuthorController::class, 'search']);
Route::get('/author/posts/{id}', [AuthorController::class, 'get_posts']);
// private posts and authors routes
Route::group(['middleware' => ['auth:sanctum']], function () {
// private post routes
Route::post('/posts', [PostController::class, 'store']);
Route::put('/posts/{id}', [PostController::class, 'update']);
Route::delete('/posts/{id}', [PostController::class, 'destroy']);
// private author routes
Route::post('/authors', [AuthorController::class, 'store']);
Route::put('/authors/{id}', [AuthorController::class, 'update']);
Route::delete('/authors/{id}', [AuthorController::class, 'destroy']);
// logout
Route::post('/logout', [AuthController::class, 'logout']);
});
And that's it!, you have successfully implemented the authentication part of the API. In the next part, I will show you how to test APIs in Laravel.
Please use the comment section for suggestions and feedback, I would really appreciate that. I hope you enjoyed the article!
All the code for this series can be found here
Top comments (4)
what if i want to have role more than 1?
Do I have to create token every time one log in? Won't the database become overload with same user but million of tokens
No, because the token is deleted from the database after the user is logged out or after the expiration time. See the Logout section for more details.
Logout methos worked for me however i testes rest routes with auth middleware unfortunately they returned response as it is authenticated.
what is a reason?