From 994e9560d04958f4bac3b57cff332f9822aea5a0 Mon Sep 17 00:00:00 2001
From: Nora Reidy <nora.reidy@mongodb.com>
Date: Fri, 19 Jul 2024 13:33:21 -0400
Subject: [PATCH] DOCSP-41241: Laravel Sanctum (#3050)

* DOCSP-41241: Laravel Sanctum

* apply phpcbf formatting

* edits

* code edit, change depth

* feedback

* edits

* JM tech review 1

---------

Co-authored-by: norareidy <norareidy@users.noreply.github.com>
Co-authored-by: rustagir <rea.rustagi@mongodb.com>
---
 docs/includes/auth/PersonalAccessToken.php | 16 ++++++
 docs/user-authentication.txt               | 62 ++++++++++++++++++++--
 2 files changed, 74 insertions(+), 4 deletions(-)
 create mode 100644 docs/includes/auth/PersonalAccessToken.php

diff --git a/docs/includes/auth/PersonalAccessToken.php b/docs/includes/auth/PersonalAccessToken.php
new file mode 100644
index 000000000..2a3c5e29c
--- /dev/null
+++ b/docs/includes/auth/PersonalAccessToken.php
@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Models;
+
+use Laravel\Sanctum\PersonalAccessToken as SanctumToken;
+use MongoDB\Laravel\Eloquent\DocumentModel;
+
+class PersonalAccessToken extends SanctumToken
+{
+    use DocumentModel;
+
+    protected $connection = 'mongodb';
+    protected $collection = 'personal_access_tokens';
+    protected $primaryKey = '_id';
+    protected $keyType = 'string';
+}
diff --git a/docs/user-authentication.txt b/docs/user-authentication.txt
index b86a8659f..ec5ebc9ee 100644
--- a/docs/user-authentication.txt
+++ b/docs/user-authentication.txt
@@ -14,7 +14,7 @@ User Authentication
 .. contents:: On this page
    :local:
    :backlinks: none
-   :depth: 1
+   :depth: 2
    :class: singlecol
 
 Overview
@@ -97,8 +97,62 @@ manage user authentication, as shown in the following code:
    :language: php
    :dedent:
 
-Enable Password Reminders 
--------------------------
+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-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 {+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.
+
+.. _laravel-user-auth-reminders:
+
+Password Reminders 
+~~~~~~~~~~~~~~~~~~
 
 To add support for MongoDB-based password reminders, register the following service
 provider in your application:
@@ -111,7 +165,7 @@ 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: