django-registration Documentation

django-registration is a user-registration application for Django sites. It provides extensible support for several registration workflows:

• Default Django User Model: Registration using the standard Django user model.
• Custom User Models: Support for many different custom user model implementations.
• Two-step Registration: A workflow where an activation link is emailed to the user to complete registration.
• One-step Registration: A workflow where users are registered and immediately logged in.

The package is designed to be extensible for use cases beyond these built-in options.

By default, django-registration uses django_registration.validators.ReservedNameValidator to prevent users from registering names that could lead to impersonation or system confusion.

Reserved names include categories such as:

• Administrator impersonation: e.g., admin, administrator.
• Protocol-specific emails: e.g., webmaster.
• Sensitive subdomains: e.g., ftp, autodiscover.
• Sensitive URLs: e.g., contact, buy.

It is strongly recommended to leave this validation enabled.

To protect against homograph attacks (where visually similar characters from different scripts are used to impersonate other users), django-registration implements strict Unicode validation for usernames and email addresses (both local-part and domain).

Validation Rule: A value is rejected if it is mixed-script (contains characters from multiple different scripts) and contains characters listed in the Unicode Visually Confusable Characters file.

Key Validators:

• django_registration.validators.validate_confusables: Validates usernames.
• django_registration.validators.validate_confusables_email: Validates email addresses.

To minimize false positives, the local-part and domain of an email address are checked independently. It is strongly recommended to leave this validation enabled.

To implement custom registration workflows, you can subclass the two primary base view classes provided by django_registration.views. These classes leverage Django's class-based views (CBVs) to provide a flexible foundation for different user onboarding processes.

• RegistrationView: The base class for handling the initial user registration process.
• ActivationView: The base class for handling user activation (e.g., via email link).

Note that the built-in workflows (like email activation) provide their own specialized subclasses of these base classes. If you are using a built-in workflow, refer to its specific documentation for customization points. Use these base classes directly only when building a completely custom registration logic from scratch.

django-registration provides two built-in workflows for user registration:

1. Two-step activation workflow: A user signs up, then must click a link sent via email to activate their account.
2. One-step workflow: A user signs up and their account is immediately active and logged in.

To use either workflow, you must add "django_registration" to your INSTALLED_APPS in settings.py. Additionally, ensure django.contrib.auth is installed and migrated. If using a custom user model, refer to the custom user compatibility guide before proceeding.

The one-step workflow logs the user in immediately after account creation. To ensure this works with a custom user model, you must satisfy one of the following:

1. Use Django's ModelBackend as your authentication backend.
2. Use a custom authentication backend that accepts a combination of your model's USERNAME_FIELD and a password value named "password" as sufficient credentials.

The activation key is a URL-safe value generated using Django's cryptographic signing tools (django.core.signing.dumps). It is composed of:

encoded_username:timestamp:signature

• encoded_username: The username of the new account (URL-safe base64 encoded).
• timestamp: The registration time (base62 encoded).
• signature: An HMAC of the username and timestamp.

The workflow uses your Django SECRET_KEY for the HMAC and the REGISTRATION_SALT setting to namespace the signature. The ActivationView verifies both the signature and that the timestamp falls within the ACCOUNT_ACTIVATION_DAYS window before setting is_active to True.

The one-step workflow allows users to sign up, become immediately active, and be logged in automatically.

To use this workflow:

1. Add "django_registration" to your INSTALLED_APPS in settings.py.
2. (Optional) Use the REGISTRATION_OPEN setting to enable or disable registration globally. It defaults to True. Set it to False to reject all registration attempts.

INSTALLED_APPS = [
    ...
    "django_registration",
    ...
]

# Optional: Disable registration
REGISTRATION_OPEN = False

To implement a one-step registration workflow (where users are immediately logged in after registering), add django_registration to your INSTALLED_APPS and include the django_registration.backends.one_step.urls pattern in your root urlpatterns. It is recommended to include django.contrib.auth.urls alongside it to provide standard authentication views.

from django.urls import include, path

urlpatterns = [
    # Other URL patterns ...
    path("accounts/", include("django_registration.backends.one_step.urls")),
    path("accounts/", include("django.contrib.auth.urls")),
    # More URL patterns ...
]

Before deploying, ensure your Django environment is configured securely by running the built-in security check command:

python manage.py check --tag security