user-authentication.txt

.. _laravel-user-authentication:

===================
User Authentication
===================

.. facet::
   :name: genre
   :values: tutorial

.. meta::
   :keywords: php framework, odm, code example

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 2
   :class: singlecol

Overview
--------

In this guide, you can learn how to authenticate MongoDB users
by using Laravel's native authentication functionality. 

Laravel provides a native ``Auth`` module that includes authentication services,
such as guards that define how users are authenticated and providers that define
how users are retrieved. To learn more about these services, see `Authentication 
<https://laravel.com/docs/{+laravel-docs-version+}/authentication>`__ in the
Laravel documentation.

Modify the User Model
---------------------

By default, Laravel generates the ``User`` Eloquent model in your ``App/Models``
directory. To enable authentication for MongoDB users, your ``User`` model
must extend the ``MongoDB\Laravel\Auth\User`` class. 

To extend this class, navigate to your ``app/Models/User.php`` file and replace the
``use Illuminate\Foundation\Auth\User as Authenticatable`` statement with the following
code:

.. code-block:: php

   use MongoDB\Laravel\Auth\User as Authenticatable;

Next, ensure that your ``User`` class extends ``Authenticatable``, as shown in the following
code:

.. code-block:: php

   class User extends Authenticatable
   {
   ...
   }

After configuring your ``User`` model, create a corresponding controller. To learn how to
create a controller, see the :ref:`laravel-auth-controller` section on this page.

Example
~~~~~~~

The following code shows a ``User.php`` file that extends the ``MongoDB\Laravel\Auth\User``
class:

.. literalinclude:: /includes/auth/AuthUser.php
   :language: php
   :dedent:

.. _laravel-auth-controller:

Create the User Controller 
--------------------------

To store functions that manage authentication, create an authentication controller for
your ``User`` model. 

Run the following command from your project root to create a controller:

.. code-block:: php

   php artisan make:controller <filename>

Example
~~~~~~~

The following command creates a controller file called ``AuthController.php``:

.. code-block:: php

   php artisan make:controller AuthController

The ``AuthController.php`` file can store ``login()`` and ``logout()`` functions to
manage user authentication, as shown in the following code: 

.. literalinclude:: /includes/auth/AuthController.php
   :language: php
   :dedent:

Customize User Authentication
-----------------------------

You can customize your authentication files to align with your application's
needs and enable additional authentication features.

This section describes how to use the following features to customize the MongoDB user
authentication process:

- :ref:`laravel-user-auth-sanctum`
- :ref:`laravel-user-auth-passport`
- :ref:`laravel-user-auth-reminders`

.. _laravel-user-auth-sanctum:

Laravel Sanctum
~~~~~~~~~~~~~~~

Laravel Sanctum is an authentication package that can manage API requests and
single-page application authentication. To manage API requests, Sanctum issues
API tokens that are stored in the database and authenticates incoming HTTP
requests by using the ``Authorization`` header. To authenticate single-page applications,
Sanctum uses Laravel's cookie-based authentication services.

You can install Laravel Sanctum to manage your application's authentication
process. Run the following commands from your project root to install Laravel
Sanctum and publish its migration file:

.. code-block:: bash

   composer require laravel/sanctum
   php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"

To use Laravel Sanctum with the {+odm-short+}, modify the ``PersonalAccessToken`` model provided
by Sanctum to use the ``DocumentModel`` trait from the ``MongoDB\Laravel\Eloquent`` namespace.
The following code modifies the ``PersonalAccessToken`` model to enable MongoDB:

.. literalinclude:: /includes/auth/PersonalAccessToken.php
   :language: php
   :dedent:

Next, run the following command to modify the database schema:

.. code-block:: bash

   php artisan migrate
   
You can now instruct Sanctum to use the custom ``PersonalAccessToken`` model by calling
the ``usePersonalAccessTokenModel()`` method in one of your application's
service providers. To learn more, see `Overriding Default Models
<https://laravel.com/docs/{+laravel-docs-version+}/sanctum#overriding-default-models>`__
in the Laravel Sanctum guide.

.. tip::

   To learn more about the ``DocumentModel`` trait, see
   :ref:`laravel-third-party-model` in the Eloquent Model Class guide.

.. _laravel-user-auth-passport:

Laravel Passport
~~~~~~~~~~~~~~~~

Laravel Passport is an OAuth 2.0 server implementation that offers
API authentication for Laravel applications. Use Laravel Passport if
your application requires OAuth2 support.

.. tip::

   To learn more about Laravel Passport and the OAuth 2.0 protocol, see
   the following resources:

   - `Laravel Passport <https://laravel.com/docs/{+laravel-docs-version+}/passport>`__ in the
     Laravel documentation.

   - `OAuth 2.0 <https://oauth.net/2/>`__ on the OAuth website.

Install Laravel Passport
````````````````````````

To install Laravel Passport and run the database migrations required
to store OAuth2 clients, run the following command from your project root:

.. code-block:: bash

   php artisan install:api --passport

Next, navigate to your ``User`` model and add the ``Laravel\Passport\HasApiTokens``
trait. This trait provides helper methods that allow you to inspect a user's
authentication token and scopes. The following code shows how to add ``Laravel\Passport\HasApiTokens``
to your ``app\Models\User.php`` file:

.. code-block:: php

   <?php

   namespace App\Models;

   use MongoDB\Laravel\Auth\User as Authenticatable;
   use Laravel\Passport\HasApiTokens;

   class User extends Authenticatable
   {
      use HasApiTokens;
      ...
   }

Then, define an ``api`` authentication guard in your ``config\auth.php``
file and set the ``driver`` option to ``passport``. This instructs your
application to use Laravel Passport's ``TokenGuard`` class to authenticate
API requests. The following example adds the ``api`` authentication guard
to the ``guards`` array:

.. code-block:: php
   :emphasize-lines: 6-9

   'guards' => [
      'web' => [
         'driver' => 'session',
         'provider' => 'users',
      ],
      'api' => [
         'driver' => 'passport',
         'provider' => 'users',
      ],
   ],

Use Laravel Passport with {+odm-long+}
`````````````````````````````````````````

After installing Laravel Passport, you must enable Passport compatibility with MongoDB by
defining custom {+odm-short+} models that extend the corresponding Passport models.
To extend each Passport model class, include the ``DocumentModel`` trait in the custom models.
You can define the following {+odm-short+} model classes:

- ``MongoDB\Laravel\Passport\AuthCode``, which extends ``Laravel\Passport\AuthCode``
- ``MongoDB\Laravel\Passport\Client``, which extends ``Laravel\Passport\Client``
- ``MongoDB\Laravel\Passport\PersonalAccessClient``, which extends ``Laravel\Passport\PersonalAccessClient``
- ``MongoDB\Laravel\Passport\RefreshToken``, which extends ``Laravel\Passport\RefreshToken``
- ``MongoDB\Laravel\Passport\Token``, which extends ``Laravel\Passport\Token``

The following example code extends the default ``Laravel\Passport\AuthCode``
model class when defining a ``MongoDB\Laravel\Passport\AuthCode`` class and includes
the ``DocumentModel`` trait:

.. code-block:: php

   class MongoDB\Laravel\Passport\AuthCode extends Laravel\Passport\AuthCode
   {
      use MongoDB\Laravel\Eloquent\DocumentModel;

      protected $primaryKey = '_id';
      protected $keyType = 'string';
   }

After defining custom models that extend each ``Laravel\Passport`` class, instruct
Passport to use the models in the ``boot()`` method of your application's
``App\Providers\AppServiceProvider`` class. The following example adds each custom
model to the ``boot()`` method:

.. literalinclude:: /includes/auth/AppServiceProvider.php
   :language: php
   :emphasize-lines: 26-30
   :dedent:

Then, you can use Laravel Passport and MongoDB in your application.

.. _laravel-user-auth-reminders:

Password Reminders 
~~~~~~~~~~~~~~~~~~

To add support for MongoDB-based password reminders, register the following service
provider in your application:

.. code-block:: php

   MongoDB\Laravel\Auth\PasswordResetServiceProvider::class

This service provider modifies the internal ``DatabaseReminderRepository``
to enable password reminders.

Example
```````

The following code updates the ``providers.php`` file in the ``bootstrap`` directory
of a Laravel application to register the ``PasswordResetServiceProvider`` provider:

.. code-block:: php
   :emphasize-lines: 4

   return [
     App\Providers\AppServiceProvider::class,
     MongoDB\Laravel\MongoDBServiceProvider::class,
     MongoDB\Laravel\Auth\PasswordResetServiceProvider::class
   ];

Additional Information
----------------------

To learn more about user authentication, see `Authentication <https://laravel.com/docs/{+laravel-docs-version+}/authentication>`__
in the Laravel documentation.

To learn more about Eloquent models, see the
:ref:`laravel-eloquent-model-class` guide.