Authentication

Introduction

Laravel makes implementing authentication very simple. In fact, almost everything is configured for you out of the box. The authentication configuration file is located at config/auth.php, which contains several well documented options for tweaking the behavior of the authentication services.

By default, Laravel includes an App\User model in your app directory. This model may be used with the default Eloquent authentication driver.

Remember: when building the database schema for this model, make the password column at least 60 characters. Also, before getting started, make sure that your users (or equivalent) table contains a nullable, string remember_token column of 100 characters. This column will be used to store a token for "remember me" sessions being maintained by your application. This can be done by using $table->rememberToken(); in a migration.

If your application is not using Eloquent, you may use the database authentication driver which uses the Laravel query builder.

Authenticating Users

Laravel ships with two authentication related controllers out of the box. The AuthController handles new user registration and "logging in", while the PasswordController contains the logic to help existing users reset their forgotten passwords.

Each of these controllers uses a trait to include their necessary methods. For many applications, you will not need to modify these controllers at all. The views that these controllers render are located in the resources/views/auth directory. You are free to customize these views however you wish.

The User Registrar

To modify the form fields that are required when a new user registers with your application, you may modify the App\Services\Registrar class. This class is responsible for validating and creating new users of your application.

The validator method of the Registrar contains the validation rules for new users of the application, while the create method of the Registrar is responsible for creating new User records in your database. You are free to modify each of these methods as you wish. The Registrar is called by the AuthController via the methods contained in the AuthenticatesAndRegistersUsers trait.

Manual Authentication

If you choose not to use the provided AuthController implementation, you will need to manage the authentication of your users using the Laravel authentication classes directly. Don't worry, it's still a cinch! First, let's check out the attempt method:

<?php namespace App\Http\Controllers;

use Auth;
use Illuminate\Routing\Controller;

class AuthController extends Controller {

    /**
     * Handle an authentication attempt.
     *
     * @return Response
     */
    public function authenticate()
    {
        if (Auth::attempt(['email' => $email, 'password' => $password]))
        {
            return redirect()->intended('dashboard');
        }
    }

}

The attempt method accepts an array of key / value pairs as its first argument. The password value will be hashed. The other values in the array will be used to find the user in your database table. So, in the example above, the user will be retrieved by the value of the email column. If the user is found, the hashed password stored in the database will be compared with the hashed password value passed to the method via the array. If the two hashed passwords match, a new authenticated session will be started for the user.

The attempt method will return true if authentication was successful. Otherwise, false will be returned.

Note: In this example, email is not a required option, it is merely used as an example. You should use whatever column name corresponds to a "username" in your database.

The intended redirect function will redirect the user to the URL they were attempting to access before being caught by the authentication filter. A fallback URI may be given to this method in case the intended destination is not available.

Authenticating A User With Conditions

You also may add extra conditions to the authentication query:

if (Auth::attempt(['email' => $email, 'password' => $password, 'active' => 1]))
{
    // The user is active, not suspended, and exists.
}

Determining If A User Is Authenticated

To determine if the user is already logged into your application, you may use the check method:

if (Auth::check())
{
    // The user is logged in...
}

Authenticating A User And "Remembering" Them

If you would like to provide "remember me" functionality in your application, you may pass a boolean value as the second argument to the attempt method, which will keep the user authenticated indefinitely, or until they manually logout. Of course, your users table must include the string remember_token column, which will be used to store the "remember me" token.

if (Auth::attempt(['email' => $email, 'password' => $password], $remember))
{
    // The user is being remembered...
}

If you are "remembering" users, you may use the viaRemember method to determine if the user was authenticated using the "remember me" cookie:

if (Auth::viaRemember())
{
    //
}

Authenticating Users By ID

To log a user into the application by their ID, use the loginUsingId method:

Auth::loginUsingId(1);

Validating User Credentials Without Login

The validate method allows you to validate a user's credentials without actually logging them into the application:

if (Auth::validate($credentials))
{
    //
}

Logging A User In For A Single Request

You may also use the once method to log a user into the application for a single request. No sessions or cookies will be utilized:

if (Auth::once($credentials))
{
    //
}

Manually Logging In A User

If you need to log an existing user instance into your application, you may call the login method with the user instance:

Auth::login($user);

This is equivalent to logging in a user via credentials using the attempt method.

Logging A User Out Of The Application

Auth::logout();

Of course, if you are using the built-in Laravel authentication controllers, a controller method that handles logging uers out of the application is provided out of the box.

Authentication Events

When the attempt method is called, the auth.attempt event will be fired. If the authentication attempt is successful and the user is logged in, the auth.login event will be fired as well.

Retrieving The Authenticated User

Once a user is authenticated, there are several ways to obtain an instance of the User.

First, you may access the user from the Auth facade:

<?php namespace App\Http\Controllers;

use Illuminate\Routing\Controller;

class ProfileController extends Controller {

    /**
     * Update the user's profile.
     *
     * @return Response
     */
    public function updateProfile()
    {
        if (Auth::user())
        {
            // $request->user() returns an instance of the authenticated user...
        }
    }

}

Second, you may access the authenticated user via an Illuminate\Http\Request instance:

<?php namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Routing\Controller;

class ProfileController extends Controller {

    /**
     * Update the user's profile.
     *
     * @return Response
     */
    public function updateProfile(Request $request)
    {
        if ($request->user())
        {
            // $request->user() returns an instance of the authenticated user...
        }
    }

}

Thirdly, you may type-hint the Illuminate\Contracts\Auth\User contract. This type-hint may be added to a controller constructor, controller method, or any other constructor of a class resolved by the service container:

<?php namespace App\Http\Controllers;

use Illuminate\Routing\Controller;
use Illuminate\Contracts\Auth\User;

class ProfileController extends Controller {

    /**
     * Update the user's profile.
     *
     * @return Response
     */
    public function updateProfile(User $user)
    {
        // $user is an instance of the authenticated user...
    }

}

Protecting Routes

Route middleware can be used to allow only authenticated users to access a given route. Laravel provides the auth middleware by default, and it is defined in app\Http\Middleware\Authenticate.php. All you need to do is attach it to a route definition:

// With A Route Closure...

Route::get('profile', ['middleware' => 'auth', function()
{
    // Only authenticated users may enter...
}]);

// With A Controller...

Route::get('profile', ['middleware' => 'auth', 'uses' => '[email protected]']);

HTTP Basic Authentication

HTTP Basic Authentication provides a quick way to authenticate users of your application without setting up a dedicated "login" page. To get started, attach the auth.basic middleware to your route:

Protecting A Route With HTTP Basic

Route::get('profile', ['middleware' => 'auth.basic', function()
{
    // Only authenticated users may enter...
}]);

By default, the basic middleware will use the email column on the user record as the "username".

Setting Up A Stateless HTTP Basic Filter

You may also use HTTP Basic Authentication without setting a user identifier cookie in the session, which is particularly useful for API authentication. To do so, define a middleware that calls the onceBasic method:

public function handle($request, Closure $next)
{
    return Auth::onceBasic() ?: $next($request);
}

If you are using PHP FastCGI, HTTP Basic authentication may not work correctly out of the box. The following lines should be added to your .htaccess file:

RewriteCond %{HTTP:Authorization} ^(.+)$
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

Password Reminders & Reset

Model & Table

Most web applications provide a way for users to reset their forgotten passwords. Rather than forcing you to re-implement this on each application, Laravel provides convenient methods for sending password reminders and performing password resets.

To get started, verify that your User model implements the Illuminate\Contracts\Auth\Remindable contract. Of course, the User model included with the framework already implements this interface, and uses the Illuminate\Auth\Reminders\Remindable trait to include the methods needed to implement the interface.

Generating The Reminder Table Migration

Next, a table must be created to store the password reset tokens. The migration for this table is included with Laravel out of the box, and resides in the database/migrations directory. So all you need to do is migrate:

php artisan migrate

Password Reminder Controller

Laravel also includes an Auth\PasswordController that contains the logic necessary to reset user passwords. We've even provided views to get you started! The views are located in the resources/views/auth directory. You are free to modify these views as you wish to suit your own application's design.

Your user will receive an e-mail with a link that points to the getReset method of the PasswordController. This method will render the password reset form and allow users to reset their passwords. After the password is reset, the user will automatically be logged into the application and redirected to /home. You can customize the post-reset redirect location by defining a redirectTo property on the PasswordController:

protected $redirectTo = '/dashboard';

Note: By default, password reset tokens expire after one hour. You may change this via the reminder.expire option of your config/auth.php file.

Authentication Drivers

Laravel offers the database and eloquent authentication drivers out of the box. For more information about adding additional authentication drivers, check out the Authentication extension documentation.