Email-Verification for Django

Email verification for new signups or new users is a two-step verification process and adds a layer for security for valid users.

verify_email is a django app that provides this functionality right of the bat without any complex implementation.

Version Update (2.0.0):

This version contains breaking changes and is not compatible with the previous version 1.0.9

What's in this update

Features: * Added feature for re-requesting email in case the previous email was lost or deleted by mistake * Added a variable REQUEST_NEW_EMAIL_TEMPLATE where user can specify his custom template for requesting email again. More on this here. * Added a Django form for requesting email with a field email.

Read about this feature here

Bug Fixes: * Fixed a bug where the user was not able to request a new email using the previous link in case if the link expires.

Others * Using exceptions instead of normal string errors * code cleanup

The app takes care of :

• Settings user's is_active status to False.
• Generate hashed token for each user.
• Generate a verification link and send it to the user's email.
• Recieve a request from the verification link and verify for its validity.
• Activating the user's account.

What you have to implement is :

• Three steps in Quick start below...

Note : The app is designed to be used right of the bat, however, further customizations options are also provided in Advance section below.

Installation

NOTE: Don't forget to activate the virtual environment if you have one.

pip install Django-Verify-Email

Quick start

The steps to getting started are very simple. Like any other app, this can be installed easily by adding "verify_email" in your installed apps like:

Note: This documentation assumes that you already have a mail server configured for your project to send mails.

if not, then your first step should be Step 0:

Step 0 :-

--- Bypass this step if you already have these things set up for your project. ---

In your settings.py :

EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST = 'smtp.gmail.com'
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_HOST_USER = os.environ.get('EMAIL_ID') 
EMAIL_HOST_PASSWORD = os.environ.get('EMAIL_PW')

DEFAULT_FROM_EMAIL = 'noreply<[email protected]>'

Main steps...

---

Step 1 :-

Add "verify_email" to your INSTALLED_APPS setting like this:

    INSTALLED_APPS = [
        ...
        "verify_email.apps.VerifyEmailConfig",
    ]

Step 2 :-

urlpatterns = [
    ...
    path('verification/', include('verify_email.urls')),    

]

Step 3 :-

python manage.py migrate

Step 4 :-

For sending email from a signup form, in your views.py import:

...
from verify_email.email_handler import send_verification_email

Now in the function where you are validating the form:

...

def register_user(request):
    ...

    if form.is_valid():

        inactive_user = send_verification_email(request, form)

Attention : "send_verification_email()" takes two arguments, requests and form in order to set user's active status.

The "inactive_user" that is returned by "send_verification_email()" contains a saved user object just like form.save() would do(with is_active status set as False), which you can further use to extract user information from cleaned_data dictionary, as shown below :

inactive_user.cleaned_data['email']

# Output: test-user123@gmail.com

The user is already being saved as inactive and you don't have to .save() it explicitly.

If anything goes wrong in sending the verification link email, the user will not be saved, so that the user can try again.

At this point, you are good to go...

Start the development server and signup with an email and you should be getting an email on the entered email with the default template for account activation. (You can provide your own HTML template. see Advance Section)

Note : The app comes with default email templates which can be overriden. See Custom Email Templates

Verifying User's email :

Nothing...

That's right! , you don't have to implement any other code for validating users with their respective unique tokens and emails.

The app takes care of everything in the background.

• When the user clicks on the verification link, it comes to : path('verification/', include('verify_email')), which you defined in your project's urls.py in step 2 above.
• This pattern is further extended in this app's urls.py where it accepts encoded email and encoded hashed tokens from the verification link.
• It then checks for users by that email.
• If the user exists, it then checks for a token if it is valid for that user or not.
• If the token is valid, it activates the user's account by setting is_active attribute to True and last_login to timezone.now().
• If the token is already been redeemed or modified, you'll be redirected to a "verification failed" page.

This whole process from generating HMAC hashed token for each user to verify it for a unique user, is abstracted within the app 😃.

Advance

Expiration of link and Resending emails :

Re-Sending Email

Re-Sending Email using previous link

Resend Email using Email Form

<a href="{% url 'request-new-link-from-email' %}">

REQUEST_NEW_EMAIL_TEMPLATE = 'mytemplates/mycustomtemplate.html'

<form method='POST' >
            {% csrf_token %}

            <fieldset>
                {{form}}
            </fieldset>

            <div style="margin-top: 50px;">
                <button class="btn btn-outline-info" type="submit">Request New Email</button>
            </div>
</form>

Custom Email Templates :

HTML_MESSAGE_TEMPLATE = "path/to/html_template.html"

VERIFICATION_SUCCESS_TEMPLATE = "path/to/success.html"

VERIFICATION_FAILED_TEMPLATE = "path/to/failed.html"

REQUEST_NEW_EMAIL_TEMPLATE = "path/to/email.html"

LINK_EXPIRED_TEMPLATE = 'path/to/expired.html'

NEW_EMAIL_SENT_TEMPLATE  = 'path/to/new_email_sent.html'

SUBJECT = 'subject of email'

# default subject is: Email Verification Mail

Inside Templates :

---

Custom HTML Message Template :

Two variables are passed in context dict of "HTML_MESSAGE_TEMPLATE" :

• {{request}} : Which is the same request passed in to send_verification_email.
• {{link}} : Which contains verification link

IMPORTANT : if you are using custom html message template for email that has to be sent to user, provide a {{link}} as a template tag to contain verification link.

You Must Pass This In Your Template. Otherwise, the sent mail will not contain the verification link.

For Ex :

my_custom_email_message.html :

<div class="format-font" >
    <a href="{{link}}" class="my-button" >Verify</a>  # ----> The "link" variable is passed by the app's backend containing verification link.
</div>

----> "link" is a variable, that contains a verification link, and is passed in an HTML message template during sending the email to the user.

Custom HTML Verification Success and Failed pages :

Success :

Two variables are passed in the context dictionary of "VERIFICATION_SUCCESS_TEMPLATE" :

• {{mgs}}: Which contains the message to be displayed on successful verification.
• {{link}}: Which contains a redirect link to the login page.

In template :

<h1 style="text-align: center; color: white;">
    {{msg}}     # __--> message variable
</h1>

<a href="{{link}}" class="btn btn-primary">     # __--> Link of login page
    Login
</a>

Failed :

Only "{{msg}}" is passed for failed msg in the template.

In template :

<h1 style="text-align: center; color: white;">
    {{msg}}
</h1>

Successful Verification :

After verification is successful, you might want to redirect the user to the login page. You can do this in two ways :

• 1 Redirect from success webpage. The user will be prompted to show a success page with a button on it to navigate to the Login page. ``` LOGIN_URL = 'name of your login pattern'

  Note: This variable is also used by Django. * 2 <b>Redirect directly to the login page without stopping at the success message page.</b> The user will be directly sent to the login page, bypassing the success page. VERIFICATION_SUCCESS_TEMPLATE = None ```

There is always room for improvements and new ideas, feel free to raise PR or Issues