Merge pull request #413 from codeigniter4/magic-link-notice

feat: notify devs when user has used magic link login.

Author: lonnieezell

docs/events.md

@@ -9,6 +9,8 @@ Shield fires off several events during the lifecycle of the application that you
       - [login](#login)
       - [failedLogin](#failedlogin)
       - [logout](#logout)
+      - [magicLogin](#magiclogin)
+    - [Event Timing](#event-timing)
 
 ## Responding to Events
 
@@ -66,6 +68,18 @@ When the magic link login fails, the following array will be provided:
 
 Fired immediately after a successful logout. The only argument is the `User` entity.
 
+#### magicLogin
+
+Fired when a user has been successfully logged in via a magic link. This event does not have any parameters passed in. The authenticated user can be discovered through the `auth()` helper.
+
+```php
+Events::on('magicLogin', function() {
+    $user = auth()->user();
+
+    //
+})
+```
+
 ### Event Timing
 
 To learn more about Event timing, please see the list below.

docs/quickstart.md

@@ -13,6 +13,9 @@ NOTE: The examples assume that you have run the setup script and that you have c
     - [Change Access Token Lifetime](#change-access-token-lifetime)
     - [Enable Account Activation via Email](#enable-account-activation-via-email)
     - [Enable Two-Factor Authentication](#enable-two-factor-authentication)
+    - [Responding to Magic Link Logins](#responding-to-magic-link-logins)
+      - [Session Notification](#session-notification)
+      - [Event](#event)
   - [Authorization Flow](#authorization-flow)
     - [Change Available Groups](#change-available-groups)
     - [Set the Default Group](#set-the-default-group)
@@ -126,6 +129,37 @@ public array $actions = [
 ];
 ```
 
+### Responding to Magic Link Logins
+
+Magic Link logins allow a user that has forgotten their password to have an email sent with a unique, one-time login link. Once they've logged in you can decide how to respond. In some cases, you might want to redirect them to a special page where they must choose a new password. In other cases, you might simply want to display a one-time message prompting them to go to their account page and choose a new password.
+
+#### Session Notification
+
+You can detect if a user has finished the magic link login by checking for a session value, `magicLogin`. If they have recently completed the flow, it will exist and have a value of `true`.
+
+```php
+if (session('magicLogin')) {
+    return redirect()->route('set_password');
+}
+```
+
+This value sticks around in the session for 5 minutes. Once you no longer need to take any actions, you might want to delete the value from the session.
+
+```php
+session()->removeTempdata('magicLogin');
+```
+
+#### Event
+
+At the same time the above session variable is set, a `magicLogin` [event](https://codeigniter.com/user_guide/extending/events.html) is fired off that you may subscribe to. Note that no data is passed to the event as you can easily grab the current user from the `user()` helper or the `auth()->user()` method.
+
+```php
+Events::on('magicLogin', static function () {
+    // ...
+});
+```
+
+
 ## Authorization Flow
 
 ### Change Available Groups

docs/session_auth_event_and_logging.md

@@ -38,5 +38,5 @@ The following is a list of Events and Logging for Session Authenticator.
         - OK → no event
         - NG → no event
     2. Send request with token
-        - OK → event `login` / table `auth_logins`
+        - OK → event `login` and `magicLogin` / table `auth_logins`
         - NG → event `failedLogin` / table `auth_logins`

src/Controllers/MagicLinkController.php

@@ -163,6 +163,12 @@ public function verify(): RedirectResponse
 
         $this->recordLoginAttempt($identifier, true, $user->id);
 
+        // Give the developer a way to know the user
+        // logged in via a magic link.
+        session()->setTempdata('magicLogin', true);
+
+        Events::trigger('magicLogin');
+
         // Get our login redirect url
         return redirect()->to(config('Auth')->loginRedirect());
     }

tests/Authentication/MagicLinkTest.php

@@ -114,6 +114,9 @@ public function testMagicLinkVerifyExpired(): void
 
         $result->assertRedirectTo(route_to('magic-link'));
         $result->assertSessionHas('error', lang('Auth.magicLinkExpired'));
+
+        // It should have set temp session var
+        $this->assertFalse(session()->has('magicLogin'));
     }
 
     public function testMagicLinkVerifySuccess(): void
@@ -134,5 +137,9 @@ public function testMagicLinkVerifySuccess(): void
         $result->assertRedirectTo(site_url());
         $result->assertSessionHas('user', ['id' => $user->id]);
         $this->assertTrue(auth()->loggedIn());
+
+        // It should have set temp session var
+        $this->assertTrue(session()->has('magicLogin'));
+        $this->assertTrue(session('magicLogin'));
     }
 }