TOM Registration

This reusable TOM Toolkit app provides support for two user registration flows in the TOM Toolkit.

The two registration flows are as follows:

1. Open Registration - In this flow, the user fills in a registration form and is immediately able to access the TOM and see all public data.

2. Approval Registration - In this flow, the user fills in a registration form, and is inactive until an administrator reviews and approves their registration.

Installation

1. Install the package into your TOM environment:

pip install tom-registration

2. In your project settings.py, add tom_registration to your INSTALLED_APPS setting:

   INSTALLED_APPS = [
       ...
       'tom_registration',
   ]
   

   And add the follow setting, with appropriate values for your use case:

   TOM_REGISTRATION = {
       'REGISTRATION_AUTHENTICATION_BACKEND': 'django.contrib.auth.backends.ModelBackend',
       'REGISTRATION_REDIRECT_PATTERN': 'home',
       'REGISTRATION_STRATEGY': 'open',  # ['open', 'approval_required']
       'SEND_APPROVAL_EMAILS': True,  # Optional email behavior if `REGISTRATION_STRATEGY = 'approval_required'`, default is False
       'APPROVAL_SUBJECT': f'Your {TOM_NAME} registration has been approved!',  # Optional subject line of approval email, (Default Shown)
       'APPROVAL_MESSAGE': f'Your {TOM_NAME} registration has been approved. You can log in <a href="mytom.com/login">here</a>.'  # Optional html-enabled body for approval email, (Default Shown)
   }
   

   To prevent logged-in users from accessing the registration page, add RedirectAuthenticatedUsersFromRegisterMiddleware to the MIDDLEWARE settings:

   MIDDLEWARE = [
       ...
       'tom_common.middleware.AuthStrategyMiddleware',
       'tom_registration.middleware.RedirectAuthenticatedUsersFromRegisterMiddleware',
   ]
   

3. If you're using approval registration and you would like a message informing the user that their account is pending approval if they try to log in prior to approval, you'll need to make the following changes:

   First, in your settings.py, set the first item of your AUTHENTICATION_BACKENDS:

   AUTHENTICATION_BACKENDS = (
       'django.contrib.auth.backends.AllowAllUsersModelBackend',
       'guardian.backends.ObjectPermissionBackend'
   )
   

   Then, change the value of REGISTRATION_AUTHENTICATION_BACKEND in the TOM_REGISTRATION setting that was just created:

   TOM_REGISTRATION = {
       'REGISTRATION_AUTHENTICATION_BACKEND': 'django.contrib.auth.backends.AllowAllUsersModelBackend',
       ...
   }
   

   Also, you must be aware of your settings.AUTH_STRATEGY: If it is set to READ_ONLY nothing further is required. If your settings.AUTH_STRATEGY is set to LOCKED, then you need to add /accounts/register/ to your settings.OPEN_URLS list. For example,

   AUTH_STRATEGY = 'LOCKED'
   OPEN_URLS = ['/accounts/register/']
   

Email

In the approval required registration flow, there is available behavior to send basic emails notifying moderators of a registration request, and notifying users of registration approval. Administrators are determined by the Django MANAGERS setting. Email behavior can be enabled or disabled with SEND_APPROVAL_EMAILS.

The configuration of an email backend is a topic covered in depth by the Django docs. There are a number of required settings that will need to be added. An example of how the most important settings should look something like the following:

    MANAGERS = [('Manager1', 'manager@my_tom.com')]  # List of managers who should receive registration emails
    EMAIL_SUBJECT_PREFIX = f'[{TOM_NAME}]'  # Optional prefix for all approval requests to managers
    EMAIL_HOST = 'smtp.gmail.com'   # SMTP server for sending emails (this example is for gmail)
    EMAIL_PORT = 587  # Port for the SMTP server
    EMAIL_HOST_USER = 'my_tom@gmail.com'  # Email address for the account sending emails
    EMAIL_HOST_PASSWORD = '******************'  # Password for the account sending emails (app password for gmail)
    EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
    EMAIL_USE_TLS = True  # this is needed for gmail, other services may vary
    EMAIL_USE_SSL = False  # this is needed for gmail, other services may vary
    SERVER_EMAIL = "my_tom@email.com"  # Email address used as the "from" address if EMAIL_HOST_USER is not needed

Note if using gmail: the EMAIL_HOST_PASSWORD above is not the account email password associated with EMAIL_HOST_USER, but an app password generated by the account owner. This can be generated from the account settings page by searching for "app passwords".

Running the tests

In order to run the tests, run the following in your virtualenv:

    python tom_registration/tests/run_tests.py

For options see

    python tom_registration/tests/run_tests.py --help