Authentication Views

Django provides several views that you can use for handling login, logout, and password management. These make use of the built-in auth forms but you can pass in your own forms as well. Django provides no default template for the authentication views – however the template context is documented for each view below.

There are different methods to implement these views in your project, however the easiest and most common way is to include the provided URLconf in django.contrib.auth.urls in your own URLconf, for example:

urlpatterns = [url('^', include('django.contrib.auth.urls'))]

This will make each of the views available at a default URL (detailed below).

The built-in views all return a TemplateResponse instance, which allows you to easily customize the response data before rendering. Most built-in authentication views provide a URL name for easier reference.

login

Logs a user in.

Default URL: /login/

Optional arguments:

  • template_name: The name of a template to display for the view used to log the user in. Defaults to registration/login.html.
  • redirect_field_name: The name of a GET field containing the URL to redirect to after login. Defaults to next.
  • authentication_form: A callable (typically just a form class) to use for authentication. Defaults to AuthenticationForm.
  • current_app: A hint indicating which application contains the current view. See the namespaced URL resolution strategy for more information.
  • extra_context: A dictionary of context data that will be added to the default context data passed to the template.

Here’s what login does:

  • If called via GET, it displays a login form that POSTs to the same URL. More on this in a bit.
  • If called via POST with user submitted credentials, it tries to log the user in. If login is successful, the view redirects to the URL specified in next. If next isn’t provided, it redirects to LOGIN_REDIRECT_URL (which defaults to /accounts/profile/). If login isn’t successful, it redisplays the login form.
    It’s your responsibility to provide the html for the login template, called registration/login.html by default.

Template Context

  • form: A Form object representing the AuthenticationForm.
  • next: The URL to redirect to after successful login. This may contain a query string, too.
  • site: The current Site, according to the SITE_ID setting. If you don’t have the site framework installed, this will be set to an instance of RequestSite, which derives the site name and domain from the current HttpRequest.
  • site_name: An alias for site.name. If you don’t have the site framework installed, this will be set to the value of request.META['SERVER_NAME']. If you’d prefer not to call the template registration/login.html, you can pass the template_name parameter via the extra arguments to the view in your URLconf.

logout

Logs a user out.

Default URL: /logout/

Optional arguments:

  • next_page: The URL to redirect to after logout.
  • template_name: The full name of a template to display after logging the user out. Defaults to registration/logged_out.html if no argument is supplied.
  • redirect_field_name: The name of a GET field containing the URL to redirect to after log out. Defaults to next. Overrides the next_page URL if the given GET parameter is passed.
  • current_app: A hint indicating which application contains the current view. See the namespaced URL resolution strategy for more information.
  • extra_context: A dictionary of context data that will be added to the default context data passed to the template.

Template context:

  • title: The string “Logged out”, localized.
  • site: The current Site, according to the SITE_ID setting. If you don’t have the site framework installed, this will be set to an instance of RequestSite, which derives the site name and domain from the current HttpRequest.
  • site_name: An alias for site.name. If you don’t have the site framework installed, this will be set to the value of request.META['SERVER_NAME'].
  • current_app: A hint indicating which application contains the current view. See the namespaced URL resolution strategy for more information.
  • extra_context: A dictionary of context data that will be added to the default context data passed to the template.

logout_then_login

Logs a user out, then redirects to the login page.

Default URL: None provided.

Optional arguments:

  • login_url: The URL of the login page to redirect to. Defaults to LOGIN_URL if not supplied.
  • current_app: A hint indicating which application contains the current view. See the namespaced URL resolution strategy for more information.
  • extra_context: A dictionary of context data that will be added to the default context data passed to the template.

password_change

Allows a user to change their password.

Default URL: /password_change/

Optional arguments:

  • template_name: The full name of a template to use for displaying the password change form. Defaults to registration/password_change_form.html if not supplied.
  • post_change_redirect: The URL to redirect to after a successful password change.
  • password_change_form: A custom “change password” form which must accept a user keyword argument. The form is responsible for actually changing the user’s password. Defaults to PasswordChangeForm.
  • current_app: A hint indicating which application contains the current view. See the namespaced URL resolution strategy for more information.
  • extra_context: A dictionary of context data that will be added to the default context data passed to the template.

Template context:

  • form: The password change form (see password_change_form above).

password_change_done

The page shown after a user has changed their password.

Default URL: /password_change_done/

Optional arguments:

  • template_name: The full name of a template to use. Defaults to registration/password_change_done.html if not supplied.
  • current_app: A hint indicating which application contains the current view. See the namespaced URL resolution strategy for more information.
  • extra_context: A dictionary of context data that will be added to the default context data passed to the template.

password_reset

Allows a user to reset their password by generating a one-time use link that can be used to reset the password, and sending that link to the user’s registered email address.

If the email address provided does not exist in the system, this view won’t send an email, but the user won’t receive any error message either. This prevents information leaking to potential attackers.
If you want to provide an error message in this case, you can subclass PasswordResetForm and use the password_reset_form argument.

Users flagged with an unusable password aren’t allowed to request a password reset to prevent misuse when using an external authentication source like LDAP. Note that they won’t receive any error message since this would expose their account’s existence but no mail will be sent either.

Default URL: /password_reset/

Optional arguments:

  • template_name: The full name of a template to use for displaying the password reset form. Defaults to registration/password_reset_form.html if not supplied.
  • email_template_name: The full name of a template to use for generating the email with the reset password link. Defaults to registration/password_reset_email.html if not supplied.
  • subject_template_name: The full name of a template to use for the subject of the email with the reset password link. Defaults to registration/password_reset_subject.txt if not supplied.
  • password_reset_form: Form that will be used to get the email of the user to reset the password for. Defaults to PasswordResetForm.
  • token_generator: Instance of the class to check the one-time link. This will default to default_token_generator, it’s an instance of django.contrib.auth.tokens.PasswordResetTokenGenerator.
  • post_reset_redirect: The URL to redirect to after a successful password reset request.
  • from_email: A valid email address. By default, Django uses the DEFAULT_FROM_EMAIL.
  • current_app: A hint indicating which application contains the current view. See the namespaced URL resolution strategy for more information.
  • extra_context: A dictionary of context data that will be added to the default context data passed to the template.
  • html_email_template_name: The full name of a template to use for generating a text/html multipart email with the password reset link. By default, HTML email is not sent.

Template context:

  • form: The form (see password_reset_form above) for resetting the user’s password.

Email template context:

  • email: An alias for user.email
  • user: The current User, according to the email form field. Only active users are able to reset their passwords (User.is_active is True).
  • site_name: An alias for site.name. If you don’t have the site framework installed, this will be set to the value of request.META['SERVER_NAME'].
  • domain: An alias for site.domain. If you don’t have the site framework installed, this will be set to the value of request.get_host().
  • protocol: http or https
  • uid: The user’s primary key encoded in base 64.
  • token: Token to check that the reset link is valid.

Sample registration/password_reset_email.html (email body template):

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

The same template context is used for subject template. Subject must be single line plain text string.

password_reset_done

The page shown after a user has been emailed a link to reset their password. This view is called by default if the password_reset() view doesn’t have an explicit post_reset_redirect URL set.

Default URL: /password_reset_done/

Optional arguments:

  • template_name: The full name of a template to use. Defaults to registration/password_reset_done.html if not supplied.
  • current_app: A hint indicating which application contains the current view. See the namespaced URL resolution strategy for more information.
  • extra_context: A dictionary of context data that will be added to the default context data passed to the template.

password_reset_confirm

Presents a form for entering a new password.

Default URL: /password_reset_confirm/

Optional arguments:

  • uidb64: The user’s id encoded in base 64. Defaults to None.
  • token: Token to check that the password is valid. Defaults to None.
  • template_name: The full name of a template to display the confirm password view. Default value is registration/password_reset_confirm.html.
  • token_generator: Instance of the class to check the password. This will default to default_token_generator, it’s an instance of django.contrib.auth.tokens.PasswordResetTokenGenerator.
  • set_password_form: Form that will be used to set the password. Defaults to SetPasswordForm
  • post_reset_redirect: URL to redirect after the password reset done. Defaults to None.
  • current_app: A hint indicating which application contains the current view. See the namespaced URL resolution strategy for more information.
  • extra_context: A dictionary of context data that will be added to the default context data passed to the template.

Template context:

  • form: The form (see set_password_form above) for setting the new user’s password.
  • validlink: Boolean, True if the link (combination of uidb64 and token) is valid or unused yet.

password_reset_complete

Presents a view which informs the user that the password has been successfully changed.

Default URL: /password_reset_complete/

Optional arguments:

  • template_name: The full name of a template to display the view. Defaults to registration/password_reset_complete.html.
  • current_app: A hint indicating which application contains the current view. See the namespaced URL resolution strategy for more information.
  • extra_context: A dictionary of context data that will be added to the default context data passed to the template.

The redirect_to_login helper function

Django provides a convenient function, redirect_to_login that can be used in a view for implementing custom access control. It redirects to the login page, and then back to another URL after a successful login.

Required arguments:

  • next: The URL to redirect to after a successful login.

Optional arguments:

  • login_url: The URL of the login page to redirect to. Defaults to LOGIN_URL if not supplied.
  • redirect_field_name: The name of a GET field containing the URL to redirect to after log out. Overrides next if the given GET parameter is passed.