Laravel: All the Authentication events

Because you can hook to them and do nice and interesting things

Photo by Oleg Laptev on Unsplash

Just in case you didn’t know, the Authentication stack of the framework comes with a lot of Events. These are fired depending on what happened in the authentication flow, and usually contain the useful information about the authentication itself, like the credentials used, or the User authenticated and for which Guard.

It’s not mandatory, but recommended, to have a look into The Power of Authentication I, II and III. Or at least the first article.

For example, one of the events is called Registered, which after firing is picked up by the SendEmailVerificationNotification listener. The latter is in charge of sending a verification email if the user has not verified his email.

This is just one of the many Authentication Events there are available out of the box.

What Events? Where are they? Take a look into the Events directory. There is almost a dozen of events. Don’t worry, we’re gonna get a description of each of these in a nice way, since these are fired depending on what happened.

Note of awareness: Laravel 7.0 won’t some traits or authentication routes, as these seems to under rework. Some of the following code will point to version 6.0 nevertheless.

The flowchart of (all) Events

This is the flowchart of events that happen in the Authentication flow. I use this chart because some Events don’t (and shouldn’t) fire before others, while others are unrelated.

If you feel lost, don’t feel bad for coming back and see where is the event you’re looking for.

Registered and Verified

The Registered event fires when the User registers into the application by issuing his information and authentication credentials, which by default are the email and password.

The event must be fired where the registration logic runs, after the User has been persisted inside the database, which is inside a Registration Controller trait.

The Registered event contains the registered user.

By default, Users registered won’t be able to use the application until they verify their email.

Once they do, the Verified event will be fired after their profile is marked with the verification timestamp, inside a Verification Controller trait.

The Verified event contains the verified user.

Attempting

When a User registered tries to log in, the Attempting event will fire before any other authentication logic runs.

This event is fired inside the Guard, and should be fired inside it but before any credential validation.

The Attempting event contains the credentials, the Guard name being used, and if the user wants to be remembered by a stateful mechanism (like cookies).

Validated, Login and Other Device Logout

After the attempt to verify the credentials is successful, the User will be validated against the credentials issued, and this is when the Validated event fires.

For self-promotion purposes, this event is pivotal for my Two Factor Authentication package.

The Validated event contains the User that should be able to login, but before the login logic is run.

After the validated User is retrieved, and the Login event will fire after the Login logic runs.

This event also fires when you manually login a given User into the application, which bypasses any credential validation.

The Login event contains the authenticated User, the Guard name being used, and if the user is set to be remembered by a stateful mechanism (like cookies).

The OtherDeviceLogout is an optional event, and fires after the Guard makes invalid all other devices where the session is authenticated for the same User.

There is a Laracast video explaining how to set up and make it work, but the gist is very simple: if you want the User to be logged in only in one device, call the logoutOtherDevices(). This will instantly close the session in all other devices.

Authenticated, Current Device Logout and Log out

This one is very tricky. The Authenticated event fires when the User is identified as authenticated inside the application, which occurs when the User data is pulled out from the Provider using the identifier in the current Session, or other stateful mechanism.

When the Session mechanism doesn’t exists, or is unavailable, a cookie will be tried to be decoded to check if it has a valid remember token. If that’s the case, this will fire the Login event, not the Authenticated event, but eventually subsequent requests will fire the latter.

If you need to hook into the Authenticated event, use a Subscriber and hook into the Login event too. Both are never fired at the same time in the same Request. This is intended.

The Authenticated event contains the authenticated User and the Guard name.

After the user is inside the application, he can close his session. This is when the Logout event fires. The event fires after any stateful mechanism is invalidated, like sessions and cookies. It also invalidates the remember mechanism.

The Logout event contains the User logged out and from what Guard name.

If you log out the User from other devices, the remember mechanism will be invalidated everywhere, even if in the current device a remember token exists. To avoid this, instead of calling the logout() method, the logoutCurrentDevice() method must be called.

When the above method is called, the CurrentDeviceLogout will fire after the user is cleared from the stateful mechanisms, which by default are the session and cookies, but not the remember token.

Failed and Lockout

These ones are pretty simple. When the User issues invalid credentials, like a nonexistent email, or the wrong password, the Failed event will fire.

The Failed Event contains the credentials and the Guard name being used.

Some Users may still try to issue invalid credentials repeteadly. When a number of failed attempts are reached, the Lockout event will fire. This is not done in the Guard, but rather, inside the Login Controller, code handled by a trait.

The Lockout Event contains the Request instance that was locked out.

Password Reset

This one is pretty simple. When the User forgets his password, he can ask the application to create a new one. Once the new password is persisted into the database, the PasswordReset event will be fired, which is done in the ResetPasswordController trait.

The PasswordReset event contains the user that resetted his password.

And these are all. Happy hooking into these events!