Download the PHP package laragear/email-login without Composer

Email Login

Authenticate users through their email in 1 minute.

Keep this package free

Your support allows me to keep this package free, up-to-date and maintainable. Alternatively, you can spread the word!

Installation

Then call Composer to retrieve the package.

1 minute quickstart

Email Login is very simple to after installing: put the email of the user you want to authenticate in a form, and an email will be sent to him with a single-time link to authenticate.

First, install the configuration file and the base the controllers using the email-login:install Artisan command.

After that, ensure you register the routes that the login email will use for authentication using the included route registrar helper at Laragear\EmailLogin\Http\Routes class.

[!TIP]

You may change the route path for the email login as an argument, additionally to the controller.

Finally, add a "login" box that receives the user email by making a POST to auth/email, anywhere in your application.

That's it, your user is ready to log in with its email.

This package will handle the whole logic for you, but you can always go full manual with your own routes and controllers.

Sending the login email

To implement the login email manually, you need to capture the user credentials from the form submission. The EmailLoginRequest does most of the heavy lifting for you.

If you're using the defaults that come with Laravel, the request automatically validates the email. You only need to return the sendAndBack() method to redirect the user back to the form.

You can also use send() and back() separately if you need to do something before sending the email, and use the validate() method if you want to expand on the email validation rules.

Both sendAndBack() and send() return true if the user with the credentials is found and the email is sent (or queued to be sent), and false if the user doesn't exist. Some apps will be fine by obfuscating the user existence, but some may want to show if the user doesn't exist.

Custom credentials

When sending an Email Login, the validated data is used to find the user to be authenticated through the User Provider of the Guard. For example, if you validate the username key, only that will be used to find the user and send the email.

You can override the credentials to find the user using the withCredentials() method with a list of the keys in the request input that should be used as credentials. The list may be different from the validated request input.

Keys can also be callbacks that receive the query to find the User.

Alternatively, if you issue key-value pair, the value of the key will be used as a credential value.

Login expiration

The link to login sent in the email has an expiration time, which by default is 5 minutes. You can change this globally through the strtotime().

Custom remember key

If your request has the remember key, and it's truthy, the user will be remembered into the application when he logs in. If the key is different, you may set a string with the key name through the withRemember() method.

Alternatively, issuing anything else will be used as the condition, like a boolean or a callback.

Specifying the guard

By default, the Email Login assumes the user will authenticate using the default guard, which in most vanilla Laravel applications is web. You may want to change the default guard in the configuration, or change it at runtime using withGuard():

Email URL link

You may change the URL where the Email Login will point to through the configuration, or at runtime using the withPath(), withAction(), and withRoute() methods. You may set also parameters using an array as a second argument, if you need to.

You may also only append query parameters to the default URL set in the configuration using withParameters() method.

[!WARNING]

The route must exist. This route should show a form to login, not login the user immediately. See Login in from a mail.

Customizing the Mailable

The most basic approach to use your own Mailable class is to set it through the withMailable() method, either as a class name (instanced by the Container) or as a Mailable instance.

Alternatively, you may want to use callback to customize the included Mailable instance. The callback receives the LoginEmail mailable. Inside the callback you're free to modify the mailable to your liking, like changing the view or the destination, or even return a new Mailable.

Opaque throttling

If you want to throttle sending the email opaquely, just use the withThrottle() method with the amount of seconds. During that time, the email will not be sent. This is great to avoid a massive amount of emails.

The throttling uses the same cache used to store the email login intent, and the request fingerprint (IP) by default. You may change the cache store to use as second name, and even the key to use as throttler as third argument.

Adding metadata

You can save data that's valid only for the login attempt using the withMetadata() method. You may set here an array of keys and values that you can later retrieve when the login is successful.

[!TIP]

The metadata is not transmitted in the email link, but stored as part of the Email Login Intent inside your application cache.

Login in from a Mail

The login procedure from an email must be done in two controller actions: one showing a form, and another authenticating the user. Both of these routes should use the guest middleware to avoid being hit by an authenticated user.

[!WARNING]

The Log In must be done in two controller actions because some email clients and servers will preload, cache and/or prefetch the login link. While this is usually done to accelerate navigation or filter malicious sites, this will accidentally log in the user outside its device, and render subsequent login attempts unsuccessful.

To avoid this accidental authentication, make a route that shows a form to login, and another to authenticate the user.

Use the LoginByEmailRequest to return the view with the form to login, and to log in the user, on both users.

• When the login is invalid or expired, an HTTP 419 (Expired) error is shown to the user instead of the view. Otherwise, you may use the included laragear::email-login.web.login view to show the form.
• When receiving the login form submission, the user will be automatically logged in.

Retrieving metadata

If you have set metadata before sending the email, you can retrieve it using the metadata() method along with the key in dot.notation, and optionally a default value if it's not set.

Email Login Broker

If you want a more manual way to log in the user, use the EmailLoginBroker, which is what the Form Request helpers use behind the scenes.

To create an email login intent, use the create(). It requires the authentication guard, the user ID, and an expiration time. It returns a random token that should be used to transmit via Email.

After the user is redirected to your email login form, use the get() method with the token to retrieve the EmailLoginIntent.

Once the form submission is received, use the pull() method to remove the intent from the cache store and log in the user using the EmailLoginIntent instance data.

Custom token string

When generating the email login token, a random ULID will be generated. You may change the default generator by setting a callback that receives the EmailLoginIntent and returns a (hopefully very) random string. You may do this in your AppServiceProvider::register().

Advanced Configuration

Mail Login was made to work out-of-the-box, but you may override the configuration by simply publishing the config file if you're not using Laravel's defaults.

After that, you will receive the config/email-login.php config file with an array like this:

Guard

The default Authentication Guard to use. When null, it fall backs to the application default, which is usually web. The User Provider set for the guard is used to find the user.

Route name & View

This named route is linked in the email, which contains the view form to log in the user.

Throttle

When throttling the email, this configuration will be used to set which cache store and prefix to use.

Cache

Email Login intents are saved into the cache for a given duration. Here you can change the cache store and prefix used to store them. When null, it will use the default application store.

Link expiration

When mailing the link, a signed URL will be generated with an expiration time. You can control how many minutes to keep the link valid until it is expunged by the cache store.

Mail driver

This specifies which mail driver to use to send the login email, and the queue connection and name that will receive it. When null, it will fall back to the application default, which is usually smtp.

This also sets the default view to use to create the email, which uses Markdown.

Laravel Octane Compatibility

• There are no singletons using a stale application instance.
• There are no singletons using a stale config instance.
• There are no singletons using a stale request instance.
• Two static property accessible to write are
  • LoginByMailRequest::$destroyOnRegeneration
  • EmailLoginBroker::$tokenGenerator

There should be no problems using this package with Laravel Octane.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Blocking authentication after the email is sent.

Once the Login Email is sent to the user, the LoginByEmailRequest won't be able to block the authentication procedure since it does not check for anything more than a valid Email Login intent.

For example, if a user is banned after the login email is sent, the user will still be able to authenticate.

To avoid this, extend the LoginByEmailRequest and modify the login() method to add further checks on a manually retrieved user. Then use this new class on your login controller of choice.

License

The MIT License (MIT). Please see License File for more information.

Laravel is a Trademark of Taylor Otwell. Copyright © 2011-2024 Laravel LLC.