Real Python: Get Started With Django Part 2: Django User Management

Note:All templates used in this tutorial should be placed in the users/templates directory. If the tutorial mentions a template file users/dashboard.html , then the actual file path is users/templates/users/dashboard.html . For base.html , the actual path is users/templates/base.html , and so on.

The users/templates directory doesn’t exist by default, so you’ll have to create it first. The structure of your project will look like this:

awesome_website/
│
├── awesome_website/
│   ├── __init__.py
│   ├── asgi.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
│
├── users/
│   │
│   ├── migrations/
│   │   └── __init__.py
│   │
│   ├── templates/
│   │   │
│   │   ├── registration/  ← Templates used by Django user management
│   │   │
│   │   ├── users/  ← Other templates of your application
│   │   │
│   │   └── base.html  ← The base template of your application
│   │
│   ├── __init__.py
│   ├── admin.py
│   ├── apps.py
│   ├── models.py
│   ├── tests.py
│   └── views.py
│
├── db.sqlite3
└── manage.py

Create a Login Page

For the login page, Django will try to use a template called registration/login.html . Go ahead and create it:

<!--users/templates/registration/login.html-->

{% extends 'base.html' %}

{% block content %}
<h2>Login</h2>

<form method="post">
    {% csrf_token %}
    {{ form.as_p }}
    <input type="submit" value="Login">
</form>

<a href="{% url 'dashboard' %}">Back to dashboard</a>
{% endblock %}

This will display a Login heading, followed by a login form. Django uses a dictionary, also known as a context , to pass data to a template while rendering it. In this case, a variable called form will already be included in the context—all you need to do is display it. Using {{ form.as_p }} will render the form as a series of HTML paragraphs, making it look a bit nicer than just {{ form }} .

The {% csrf_token %} line inserts a cross-site request forgery (CSRF) token, which is required by every Django form. There’s also a button for submitting the form and, at the end of the template, a link that will take your users back to the dashboard.

You can further improve the looks of the form by adding a small CSS script to the base template:

<!--users/templates/base.html-->

<style>
    label, input {
        display: block;
    }
    span.helptext {
        display: none;
    }
</style>

<h1>Welcome to Awesome Website</h1>

{% block content %}
{% endblock %}

By adding the above code to the base template, you’ll improve the looks of all of your forms, not just the one in the dashboard.

You can now open http://localhost:8000/accounts/login/ in your browser, and you should see something like this:

Use the credentials of your admin user and press Login . Don’t be alarmed if you see an error screen:

According to the error message, Django can’t find a path for accounts/profile/ , which is the default destination for your users after a successful login. Instead of creating a new view, it would make more sense to reuse the dashboard view here.

Luckily, Django makes it easy to change the default redirection. All you need to do is add one line at the end of the settings file:

# awesome_website/settings.py

LOGIN_REDIRECT_URL = "dashboard"

Try to log in again. This time you should be redirected to the dashboard without any errors.

Create a Logout Page

Now your users can log in, but they should also be able to log out. This process is more straightforward because there’s no form—they just need to click a link. After that, Django will redirect your users to accounts/logout and will try to use a template called registration/logged_out.html .

However, just like before, you can change the redirection. For example, it would make sense to redirect your users back to the dashboard. To do so, you need to add one line at the end of the settings file:

# awesome_website/settings.py

LOGOUT_REDIRECT_URL = "dashboard"

Now that both login and logout are working, it would be a good idea to add proper links to your dashboard:

<!--users/templates/users/dashboard.html-->

{% extends 'base.html' %}

{% block content %}
Hello, {{ user.username|default:'Guest' }}!

<div>
    {% if user.is_authenticated %}
        <a href="{% url 'logout' %}">Logout</a>
    {% else %}
        <a href="{% url 'login' %}">Login</a>
    {% endif %}
</div>
{% endblock %}

If a user is logged in, then user.is_authenticated will return True and the dashboard will show the Logout link. If a user is not logged in, then user variable will be set to AnonymousUser , and user.is_authenticated will return False . In that case, the Login link will be displayed.

The updated dashboard should look like this for nonauthenticated users:

If you log in, then you should see this screen:

Congratulations! You just completed the most important part of the user management system: logging users in and out of the application. But there are a couple more steps ahead of you.

Change Passwords

At some point, your users might want to change their passwords. Instead of making them ask the admin to do it for them, you can add a password change form to your application. Django needs two templates to make this work:

1. registration/password_change_form.html to display the password change form

2. registration/password_change_done.html to show a confirmation that the password was successfully changed

Start with registration/password_change_form.html :

<!--users/templates/registration/password_change_form.html-->

{% extends 'base.html' %}

{% block content %}
<h2>Change password</h2>

<form method="post">
    {% csrf_token %}
    {{ form.as_p }}
    <input type="submit" value="Change">
</form>

<a href="{% url 'dashboard' %}">Back to dashboard</a>
{% endblock %}

This template looks almost the same as the login template you created earlier. But this time, Django will put a password change form here, not a login form, so the browser will display it differently.

The other template you need to create is registration/password_change_done.html :

<!--users/templates/registration/password_change_done.html-->

{% extends 'base.html' %}

{% block content %}
<h2>Password changed</h2>

<a href="{% url 'dashboard' %}">Back to dashboard</a>
{% endblock %}

This will reassure your users that the password change was successful and let them go back to the dashboard.

The dashboard would be a perfect place to include a link to your newly created password change form. You just have to make sure it’s shown to logged in users only:

<!--users/templates/users/dashboard.html-->

{% extends 'base.html' %}

{% block content %}
Hello, {{ user.username|default:'Guest' }}!

<div>
    {% if user.is_authenticated %}
        <a href="{% url 'logout' %}">Logout</a>
        <a href="{% url 'password_change' %}">Change password</a>
    {% else %}
        <a href="{% url 'login' %}">Login</a>
    {% endif %}
</div>
{% endblock %}

If you follow the link in your browser, then you should see the following form:

Go ahead and test it. Change the password, log out, and log in again. You can also try to access the password change page without logging in by accessing the URL http://localhost:8000/accounts/password_change/ directly in your browser. Django is clever enough to detect that you should log in first and will automatically redirect you to the login page.

Send Password Reset Links

Mistakes happen to the best of us, and every now and then someone might forget a password. Your Django user management system should handle that situation, too. This functionality is a bit more complicated because, in order to deliver password reset links, your application has to send emails.

Don’t worry—you don’t have to configure your own email server. For this tutorial, you just need a local test server to confirm that emails are sent. Open your terminal and run this command:

(venv) $ python -m smtpd -n -c DebuggingServer localhost:1025

This will start a simple SMTP server at http://localhost:1025 . It won’t send any emails to actual email addresses. Instead, it’ll show the content of the messages in the command line.

All you need to do now is let Django know that you are going to use it. Add these two lines at the end of the settings file:

# awesome_website/settings.py

EMAIL_HOST = "localhost"
EMAIL_PORT = 1025

Django needs two templates for sending password reset links:

1. registration/password_reset_form.html to display the form used to request a password reset email

2. registration/password_reset_done.html to show a confirmation that a password reset email was sent

They will be very similar to the password change templates you created earlier. Start with the form:

<!--users/templates/registration/password_reset_form.html-->

{% extends 'base.html' %}

{% block content %}
<h2>Send password reset link</h2>

<form method="post">
    {% csrf_token %}
    {{ form.as_p }}
    <input type="submit" value="Reset">
</form>

<a href="{% url 'dashboard' %}">Back to dashboard</a>
{% endblock %}

Now add a confirmation template:

<!--users/templates/registration/password_reset_done.html-->

{% extends 'base.html' %}

{% block content %}
<h2>Password reset done</h2>

<a href="{% url 'login' %}">Back to login</a>
{% endblock %}

It would also be a good idea to include a link to the password reset form on the login page:

<!--users/templates/registration/login.html-->

{% extends 'base.html' %}

{% block content %}
<h2>Login</h2>

<form method="post">
    {% csrf_token %}
    {{ form.as_p }}
    <input type="submit" value="Login">
</form>

<a href="{% url 'dashboard' %}">Back to dashboard</a>
<a href="{% url 'password_reset' %}">Reset password</a>
{% endblock %}

Your newly created password reset form should look like this:

Type in your admin’s email address ( admin@example.com ) and press Reset . You should see the following message in the terminal running the email server:

---------- MESSAGE FOLLOWS ----------
b'Content-Type: text/plain; charset="utf-8"'
b'MIME-Version: 1.0'
b'Content-Transfer-Encoding: 7bit'
b'Subject: Password reset on localhost:8000'
b'From: webmaster@localhost'
b'To: admin@example.com'
b'Date: Wed, 22 Apr 2020 20:32:39 -0000'
b'Message-ID: <20200422203239.28625.15187@pawel-laptop>'
b'X-Peer: 127.0.0.1'
b''
b''
b"You're receiving this email because you requested a password reset for your
user account at localhost:8000."
b''
b'Please go to the following page and choose a new password:'
b''
b'http://localhost:8000/accounts/reset/MQ/5fv-f18a25af38f3550a8ca5/'
b''
b"Your username, in case you've forgotten: admin"
b''
b'Thanks for using our site!'
b''
b'The localhost:8000 team'
b''
------------ END MESSAGE ------------

This is the content of an email that would be sent to your admin. It contains information about the application that sent it plus a password reset link.

Reset Passwords

Each password reset email sent by Django contains a link that can be used to reset the password. To handle that link correctly, Django needs two more templates:

1. registration/password_reset_confirm.html to display the actual password reset form

2. registration/password_reset_complete.html to show a confirmation that a password was reset

These will look very similar to the password change templates. Start with the form:

<!--users/templates/registration/password_reset_confirm.html-->

{% extends 'base.html' %}

{% block content %}
<h2>Confirm password reset</h2>

<form method="post">
    {% csrf_token %}
    {{ form.as_p }}
    <input type="submit" value="Confirm">
</form>
{% endblock %}

Just like before, Django will automatically provide a form, but this time it’ll be a password reset form. You also need to add a confirmation template:

<!--users/templates/registration/password_reset_complete.html-->

{% extends 'base.html' %}

{% block content %}
<h2>Password reset complete</h2>

<a href="{% url 'login' %}">Back to login</a>
{% endblock %}

Now, if you follow the password reset link from one of the emails, then you should see a form like this in your browser:

You can now check if it works. Insert a new password into the form, click Confirm , log out, and log in using the new password.

Change Email Templates

You can change the default templates for Django emails just like any other user management–related templates:

• registration/password_reset_email.html determines the body of the email
• registration/password_reset_subject.txt determines the subject of the email

Django provides a lot of variables in the email template context that you can use to compose your own messages:

<!--users/templates/registration/password_reset_email.html-->

Someone asked for password reset for email {{ email }}.
Follow the link below:
{{ protocol}}://{{ domain }}{% url 'password_reset_confirm' uidb64=uid token=token %}

You can also change the subject to something shorter, like Reset password . If you implement these changes and send a password reset email again, then you should see this message:

---------- MESSAGE FOLLOWS ----------
b'Content-Type: text/plain; charset="utf-8"'
b'MIME-Version: 1.0'
b'Content-Transfer-Encoding: 7bit'
b'Subject: Reset password'
b'From: webmaster@localhost'
b'To: admin@example.com'
b'Date: Wed, 22 Apr 2020 20:36:36 -0000'
b'Message-ID: <20200422203636.28625.36970@pawel-laptop>'
b'X-Peer: 127.0.0.1'
b''
b'Someone asked for password reset for email admin@example.com.'
b'Follow the link below:'
b'http://localhost:8000/accounts/reset/MQ/5fv-f18a25af38f3550a8ca5/'
------------ END MESSAGE ------------

As you can see, both the subject and the content of the email have changed.

Set Up Social Authentication

Start by installing the module:

(venv) $ python -m pip install social-auth-app-django

Like any other Django application, you have to add it to INSTALLED_APPS . Notice that, in this case, the name of the Django application is different from the name of the Python module:

# awesome_website/settings.py

INSTALLED_APPS = [
    "users",
    "social_django",
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
]

Next, add two context processors to awesome_website/settings.py :

# awesome_website/settings.py

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.debug",
                "django.template.context_processors.request",
                "django.contrib.auth.context_processors.auth",
                "django.contrib.messages.context_processors.messages",
                "social_django.context_processors.backends",
                "social_django.context_processors.login_redirect",
            ],
        },
    },
]

After you do that, apply the migrations:

(venv) $ python manage.py migrate

You also need to include the social authentication URLs in your application, just like you did with the ones provided by Django:

# users/urls.py

from django.conf.urls import include, url
from users.views import dashboard, register

urlpatterns = [
    url(r"^accounts/", include("django.contrib.auth.urls")),
    url(r"^dashboard/", dashboard, name="dashboard"),
    url(r"^oauth/", include("social_django.urls")),
    url(r"^register/", register, name="register"),
]

All of that was a general configuration for Django. To use social authentication specifically with GitHub, you have to add a dedicated authentication backend.

By default, Django settings don’t specify authentication backends, and the default backend used by Django is django.contrib.auth.backends.ModelBackend . So to use social authentication, you have to create a new value in settings:

# awesome_website/settings.py

AUTHENTICATION_BACKENDS = [
    "django.contrib.auth.backends.ModelBackend",
    "social_core.backends.github.GithubOAuth2",
]

The first backend on the list is the default one used by Django. If you don’t include it here, then Django won’t be able to log in standard users. The second backend is used for GitHub logins.

The last thing to do is to add a link to the GitHub login on your login page:

<!--users/templates/registration/login.html-->

{% extends 'base.html' %}

{% block content %}
<h2>Login</h2>

<form method="post">
    {% csrf_token %}
    {{ form.as_p }}
    <input type="submit" value="Login">
</form>

<a href="{% url 'dashboard' %}">Back to dashboard</a>
<a href="{% url 'social:begin' 'github' %}">Login with GitHub</a>
<a href="{% url 'password_reset' %}">Reset password</a>
<a href="{% url 'register' %}">Register</a>
{% endblock %}

You might notice that the new URL uses the namespace social . Namespaces are Django’s way of organizing URLs in more complex projects.

Using a unique namespace ensures that there will be no conflicts between your application’s URLs and the URLS of other applications. The social authentication application uses the namespace social , so every URL you want to use has to start with social: .

Create a GitHub Application

To use GitHub authentication with Django user management, you first have to create an application. Log in to your GitHub account, go to GitHub’s page for registering a new OAuth application , and fill in the form:

The most important part is the Authorization callback URL . It has to point back to your application.

After you register the application, you’ll be redirected to a page with credentials:

Add the values of Client ID and Client Secret to settings the same way you added Mailgun email credentials:

# awesome_website/settings.py

SOCIAL_AUTH_GITHUB_KEY = os.environ.get("SOCIAL_AUTH_GITHUB_KEY")
SOCIAL_AUTH_GITHUB_SECRET = os.environ.get("SOCIAL_AUTH_GITHUB_SECRET")

You can now check if this works. Go to your application’s login page and select the option to log in with GitHub. Assuming you’ve logged out after creating the application in the previous step, you should be redirected to GitHub’s login page:

In the next step you’ll be asked to authorize the GitHub application:

If you confirm, then you’ll be redirected back to your application. You can now find a new user in the admin panel :

The newly created user has the same username as your GitHub handle and doesn’t have a password.

Select Authentication Backend

There’s one problem with the example above: by enabling GitHub login, you accidentally broke the normal user creation process.

That happened because Django previously had only one authentication backend to choose from, and now it has two. Django doesn’t know which one to use when creating new users, so you’ll have to help it decide. To do that, replace the line user = form.save() in your registration view:

# users/views.py

from django.contrib.auth import login
from django.shortcuts import redirect, render
from django.urls import reverse
from users.forms import CustomUserCreationForm

def dashboard(request):
    return render(request, "users/dashboard.html")

def register(request):
    if request.method == "GET":
        return render(
            request, "users/register.html", {"form": CustomUserCreationForm}
        )
    elif request.method == "POST":
        form = CustomUserCreationForm(request.POST)
        if form.is_valid():
            user = form.save(commit=False)
            user.backend = "django.contrib.auth.backends.ModelBackend"
            user.save()
            login(request, user)
            return redirect(reverse("dashboard"))

A user is created from the form like before, but this time it’s not immediately saved thanks to commit=False . In the next line, a backend is associated with the user, and only then is the user saved to the database. This way, you can use both normal user creation and social media authentication in the same Django user management system.