A Magic Link plugin which sits on top of the existing user sign in and registration process.
For details about which version of this package to use with your version of Craft CMS please see the table below:
| Craft Version | Magic Login Version |
|---|---|
| <4.0.0 | 2.x |
| 4.0.0 | 3.x |
This plugin requires Craft CMS Pro 3.5.0 or later in order to take advantage of the Template Roots feature.
Also due to the User based functionality of this plugin, we require a Craft Pro License to be installed.
To install the plugin, follow these instructions.
-
Open your terminal and go to your Craft project:
cd /path/to/project -
Then tell Composer to load the plugin:
composer require creode/magic-login -
In the Control Panel, go to Settings → Plugins and click the “Install” button for Magic Login.
The Magic Login plugin is a simple plugin that sits on top of the existing user login journey. The plugin provides a way for users to register and login using a unqiue one time url that is sent out to the provided email address, to verify the identity of a user.
The main aim of this plugin is to add simple, extendible functionality utilising as much of the existing login and registration journey as possible. The plugin was built with customisation in mind, allowing all frontend templates to be customised to the users liking. For those people who just want this functioning, simple styled templates have been provided as default to get you up and running fast.
The Magic Login plugin comes with a few different configuration options as standard with more on the way as the plugin continues to mature. These are the following:
- Random Password Length - (Default Value: 16, Min: 16)
- Login Link Timeout - How long a link lasts before it expires (Default Value: 15 mins)
- Magic Link Email Subject - (Default Value: Magic Login Link)
Documented in the sections below are tips on using the magic login plugin within your existing project. This covers overwriting their templates, the list of routes provided by this plugin, using the existing stylesheets with your overwritten templates and how to include existing templates as partials in your project.
As of Version 2.0 the user registration functionality for Magic Logins will no longer throw an error if the user already exists. Instead it will send the link off the user and log them in if a Craft account is present for them.
For security reasons we don't want to make it apparent that an email has already registered on the website so as a fallback we will always show the link has been sent text. Perhaps in future we can add extra configuration settings to the plugin to allow these messages to be displayed back to the user.
All of the templates on this plugin are overwritable using the Template Roots feature of Craft. The templates you can overwrite are listed below:
- magic-login/_login-form.twig - Main Login form rendered at /magic-login/login
- magic-login/_login-link-sent.twig - Shows link sent form once a user attempts to login
- magic-login/_register-form.twig - Main Registration form rendered at /magic-login/register
- magic-login/emails/_login.twig - Email template sent out to a user which contains the Magic Login Link
If you follow that folder structure inside your sites /templates file any of the above templates can be completely re-written in order to be configured or styled however you would like.
A few routes are defined as part of this plugin:
- magic-login/register - Basically renders the standard registration form.
- magic-login/login - Renders a basic login form.
- magic-login/auth/{publicKey}/{timestamp}/{signature} - Handles the authorisation process of an existing magic link.
Whilst we have the following routes this plugin aims to also implement functionality on top of the existing user registration routes so a number of the form submission places are the same as if you were trying to register a user normally.
As part of this plugin we use asset bundles for styling the default templates. If you are overriding these templates but plan on including our existing styling you can do so by adding the following asset bundle into your own templates.
{% do view.registerAssetBundle("creode\\magiclogin\\assetbundles\\magiclogin\\MagicLoginAsset") %}
We are also aware with this plugin that sometimes you may want to inject the existing templates into your own template code. Craft and twig comes with a way of doing this by adding the following to your template:
{% include 'magic-login/_login-form' %}
In order to get the magic link functionality to work we have had to make a few assumptions of functionality under the hood. the biggest hurdle is that by default Craft requires a user to set a password when registering a new user. In order to keep this process as streamlined as possible we handle the generation of a random password behind the scenes. The length of this password can be configured for security but can go no lower than 16 characters. We see Magic Login as more of an addon and try not to make to many assumptions on how it should be used. We therefore also allow a user to be registered using a password of their choosing if required giving you the option to use it or not.
In order to distinguish users which are allowed to use Magic Login functionality we create a new user group titled "Magic Login". This group was created so that we can target users using it with updates in the future in required. Another route we could have taken would be to assign a permission to a user but this felt a little too loose but maybe this is an option for the future.
In order to let this plugins user journey work as smoothly as possible, we tweak the user activation journey provided by Craft CMS. When a user registers using the Magic Login user journey, we cancel any user activation emails sent out. This is because at the end of this process we will send out a magic login link anyway prior to logging the user in, therefore an account will instead be activated instead once the Magic Login link has been clicked.
For now this suited the needs of the project this plugin was built for however if required we can always have an extra checkbox in the admin area to turn this functionality on and off.
This change is only applied when following the Magic Login Registration route however and all other functionality that depends on the standard Craft actionUserSave functionality will remain in tact.
From the root of this plugin ensure to install the dependencies using composer:
composer install
From there you can access the codecept executable with the following:
php vendor/bin/codecept run
Some things to do, and ideas for potential features:
- Set Email Validation Error Message to be Configurable in the CMS
- Add extra configuration and logic if a user tries to login with an email address that doesn't exist
- Once an issue around automated testing and plugin initialisation is fixed, clean up the plugin. See Craft issue here
- Allow you to publish the default templates to the right location within your project to get started quickly
- Potentially create a new permission used to determine if a user is allowed to perform Magic Login
Brought to you by Creode