Fixed #3011 -- Added swappable auth.User models.

Thanks to the many people that contributed to the development and review of
this patch, including (but not limited to) Jacob Kaplan-Moss, Anssi
Kääriäinen, Ramiro Morales, Preston Holmes, Josh Ourisman, Thomas Sutton,
and Roger Barnes, as well as the many, many people who have contributed to
the design discussion around this ticket over many years.

Squashed commit of the following:

commit d84749a
Merge: 531e771 7c11b1a
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Wed Sep 26 18:37:04 2012 +0800

    Merge remote-tracking branch 'django/master' into t3011

commit 531e771
Merge: 29d1abb 1f84b04
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Wed Sep 26 07:09:23 2012 +0800

    Merged recent trunk changes.

commit 29d1abb
Merge: 8a527dd 54c81a1
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Mon Sep 24 07:49:46 2012 +0800

    Merge remote-tracking branch 'django/master' into t3011

commit 8a527dd
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Mon Sep 24 07:48:05 2012 +0800

    Ensure sequences are reset correctly in the presence of swapped models.

commit e2b6e22
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Sun Sep 23 17:53:05 2012 +0800

    Modifications to the handling and docs for auth forms.

commit 98aba85
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Sun Sep 23 15:28:57 2012 +0800

    Improved error handling and docs for get_user_model()

commit 0229209
Merge: 6494bf9 8599f64
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Sun Sep 23 14:50:11 2012 +0800

    Merged recent Django trunk changes.

commit 6494bf9
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Mon Sep 17 21:38:44 2012 +0800

    Improved validation of swappable model settings.

commit 5a04cde
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Mon Sep 17 07:15:14 2012 +0800

    Removed some unused imports.

commit ffd535e
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Sun Sep 16 20:31:28 2012 +0800

    Corrected attribute access on for get_by_natural_key

commit 913e1ac
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Sun Sep 16 20:12:34 2012 +0800

    Added test for proxy model safeguards on swappable models.

commit 280bf19
Merge: dbb3900 935a863
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Sun Sep 16 18:16:49 2012 +0800

    Merge remote-tracking branch 'django/master' into t3011

commit dbb3900
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Sun Sep 16 18:09:27 2012 +0800

    Fixes for Python 3 compatibility.

commit dfd7213
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Sun Sep 16 15:54:30 2012 +0800

    Added protection against proxying swapped models.

commit abcb027
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Sun Sep 16 15:11:10 2012 +0800

    Cleanup and documentation of AbstractUser base class.

commit a9491a8
Merge: fd8bb4e 08bcb4a
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Sun Sep 16 14:46:49 2012 +0800

    Merge commit '08bcb4aec1ed154cefc631b8510ee13e9af0c19d' into t3011

commit fd8bb4e
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Sun Sep 16 14:20:14 2012 +0800

    Documentation improvements coming from community review.

commit b550a6d
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Sun Sep 16 13:52:47 2012 +0800

    Refactored skipIfCustomUser into the contrib.auth tests.

commit 52a02f1
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Sun Sep 16 13:46:10 2012 +0800

    Refactored common 'get' pattern into manager method.

commit b441a6b
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Sun Sep 16 13:41:33 2012 +0800

    Added note about backwards incompatible change to admin login messages.

commit 08bcb4a
Author: Anssi Kääriäinen <akaariai@gmail.com>
Date:   Sat Sep 15 18:30:33 2012 +0300

    Splitted User to AbstractUser and User

commit d9f5e5a
Author: Anssi Kääriäinen <akaariai@gmail.com>
Date:   Sat Sep 15 18:30:02 2012 +0300

    Reworked REQUIRED_FIELDS + create_user() interaction

commit 579f152
Merge: 9184972 93e6733
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Sat Sep 15 20:18:37 2012 +0800

    Merge remote-tracking branch 'django/master' into t3011

commit 9184972
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Sat Sep 15 20:18:19 2012 +0800

    Deprecate AUTH_PROFILE_MODULE and get_profile().

commit 334cdfc
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Sat Sep 15 20:00:12 2012 +0800

    Added release notes for new swappable User feature.

commit 5d7bb22
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Sat Sep 15 19:59:49 2012 +0800

    Ensure swapped models can't be queried.

commit 57ac6e3
Merge: f2ec915 abfba3b
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Sat Sep 15 14:31:54 2012 +0800

    Merge remote-tracking branch 'django/master' into t3011

commit f2ec915
Merge: 1952656 5e99a3d
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Sun Sep 9 08:29:51 2012 +0800

    Merge remote-tracking branch 'django/master' into t3011

commit 1952656
Merge: 2c5e833 c4aa26a
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Sun Sep 9 08:22:26 2012 +0800

    Merge recent changes from master.

commit 2c5e833
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Sun Sep 9 07:53:46 2012 +0800

    Corrected admin_views tests following removal of the email fallback on admin logins.

commit 20d1892
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Sun Sep 9 01:00:37 2012 +0800

    Added conditional skips for all tests dependent on the default User model

commit 40ea8b8
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Sat Sep 8 23:47:02 2012 +0800

    Added documentation for REQUIRED_FIELDS in custom auth.

commit e6aaf65
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Sat Sep 8 23:20:02 2012 +0800

    Added first draft of custom User docs.

    Thanks to Greg Turner for the initial text.

commit 75118bd
Author: Thomas Sutton <me@thomas-sutton.id.au>
Date:   Mon Aug 20 11:17:26 2012 +0800

    Admin app should not allow username discovery

    The admin app login form should not allow users to discover the username
    associated with an email address.

commit d088b3a
Author: Thomas Sutton <me@thomas-sutton.id.au>
Date:   Mon Aug 20 10:32:13 2012 +0800

    Admin app login form should use swapped user model

commit 7e82e83
Merge: e29c010 39aa890
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Fri Sep 7 23:45:03 2012 +0800

    Merged master changes.

commit e29c010
Merge: 8e3fd70 30bdf22
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Mon Aug 20 13:12:57 2012 +0800

    Merge remote-tracking branch 'django/master' into t3011

commit 8e3fd70
Merge: 507bb50 26e0ba0
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Mon Aug 20 13:09:09 2012 +0800

    Merged recent changes from trunk.

commit 507bb50
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Mon Jun 4 20:41:37 2012 +0800

    Modified auth app so that login with alternate auth app is possible.

commit dabe362
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Mon Jun 4 20:10:51 2012 +0800

    Modified auth management commands to handle custom user definitions.

commit 7cc0baf
Author: Russell Keith-Magee <russell@keith-magee.com>
Date:   Mon Jun 4 14:17:28 2012 +0800

    Added model Meta option for swappable models, and made auth.User a swappable model

django/conf/global_settings.py

@@ -488,6 +488,8 @@
 # AUTHENTICATION #
 ##################
 
+AUTH_USER_MODEL = 'auth.User'
+
 AUTHENTICATION_BACKENDS = ('django.contrib.auth.backends.ModelBackend',)
 
 LOGIN_URL = '/accounts/login/'

django/contrib/admin/forms.py

@@ -4,12 +4,12 @@
 
 from django.contrib.auth import authenticate
 from django.contrib.auth.forms import AuthenticationForm
-from django.contrib.auth.models import User
-from django.utils.translation import ugettext_lazy, ugettext as _
+from django.utils.translation import ugettext_lazy
 
 ERROR_MESSAGE = ugettext_lazy("Please enter the correct username and password "
         "for a staff account. Note that both fields are case-sensitive.")
 
+
 class AdminAuthenticationForm(AuthenticationForm):
     """
     A custom authentication form used in the admin app.
@@ -26,17 +26,6 @@ def clean(self):
         if username and password:
             self.user_cache = authenticate(username=username, password=password)
             if self.user_cache is None:
-                if '@' in username:
-                    # Mistakenly entered e-mail address instead of username? Look it up.
-                    try:
-                        user = User.objects.get(email=username)
-                    except (User.DoesNotExist, User.MultipleObjectsReturned):
-                        # Nothing to do here, moving along.
-                        pass
-                    else:
-                        if user.check_password(password):
-                            message = _("Your e-mail address is not your username."
-                                        " Try '%s' instead.") % user.username
                 raise forms.ValidationError(message)
             elif not self.user_cache.is_active or not self.user_cache.is_staff:
                 raise forms.ValidationError(message)

django/contrib/admin/models.py

@@ -1,8 +1,8 @@
 from __future__ import unicode_literals
 
 from django.db import models
+from django.conf import settings
 from django.contrib.contenttypes.models import ContentType
-from django.contrib.auth.models import User
 from django.contrib.admin.util import quote
 from django.utils.translation import ugettext_lazy as _
 from django.utils.encoding import smart_text
@@ -12,15 +12,17 @@
 CHANGE = 2
 DELETION = 3
 
+
 class LogEntryManager(models.Manager):
     def log_action(self, user_id, content_type_id, object_id, object_repr, action_flag, change_message=''):
         e = self.model(None, None, user_id, content_type_id, smart_text(object_id), object_repr[:200], action_flag, change_message)
         e.save()
 
+
 @python_2_unicode_compatible
 class LogEntry(models.Model):
     action_time = models.DateTimeField(_('action time'), auto_now=True)
-    user = models.ForeignKey(User)
+    user = models.ForeignKey(settings.AUTH_USER_MODEL)
     content_type = models.ForeignKey(ContentType, blank=True, null=True)
     object_id = models.TextField(_('object id'), blank=True, null=True)
     object_repr = models.CharField(_('object repr'), max_length=200)

django/contrib/admin/sites.py

@@ -9,7 +9,6 @@
 from django.core.exceptions import ImproperlyConfigured
 from django.core.urlresolvers import reverse, NoReverseMatch
 from django.template.response import TemplateResponse
-from django.utils.safestring import mark_safe
 from django.utils import six
 from django.utils.text import capfirst
 from django.utils.translation import ugettext as _
@@ -18,12 +17,15 @@
 
 LOGIN_FORM_KEY = 'this_is_the_login_form'
 
+
 class AlreadyRegistered(Exception):
     pass
 
+
 class NotRegistered(Exception):
     pass
 
+
 class AdminSite(object):
     """
     An AdminSite object encapsulates an instance of the Django admin application, ready
@@ -41,7 +43,7 @@ class AdminSite(object):
     password_change_done_template = None
 
     def __init__(self, name='admin', app_name='admin'):
-        self._registry = {} # model_class class -> admin_class instance
+        self._registry = {}  # model_class class -> admin_class instance
         self.name = name
         self.app_name = app_name
         self._actions = {'delete_selected': actions.delete_selected}
@@ -80,20 +82,23 @@ def register(self, model_or_iterable, admin_class=None, **options):
             if model in self._registry:
                 raise AlreadyRegistered('The model %s is already registered' % model.__name__)
 
-            # If we got **options then dynamically construct a subclass of
-            # admin_class with those **options.
-            if options:
-                # For reasons I don't quite understand, without a __module__
-                # the created class appears to "live" in the wrong place,
-                # which causes issues later on.
-                options['__module__'] = __name__
-                admin_class = type("%sAdmin" % model.__name__, (admin_class,), options)
+            # Ignore the registration if the model has been
+            # swapped out.
+            if not model._meta.swapped:
+                # If we got **options then dynamically construct a subclass of
+                # admin_class with those **options.
+                if options:
+                    # For reasons I don't quite understand, without a __module__
+                    # the created class appears to "live" in the wrong place,
+                    # which causes issues later on.
+                    options['__module__'] = __name__
+                    admin_class = type("%sAdmin" % model.__name__, (admin_class,), options)
 
-            # Validate (which might be a no-op)
-            validate(admin_class, model)
+                # Validate (which might be a no-op)
+                validate(admin_class, model)
 
-            # Instantiate the admin class to save in the registry
-            self._registry[model] = admin_class(model, self)
+                # Instantiate the admin class to save in the registry
+                self._registry[model] = admin_class(model, self)
 
     def unregister(self, model_or_iterable):
         """
@@ -319,6 +324,7 @@ def login(self, request, extra_context=None):
             REDIRECT_FIELD_NAME: request.get_full_path(),
         }
         context.update(extra_context or {})
+
         defaults = {
             'extra_context': context,
             'current_app': self.name,

django/contrib/admin/templates/admin/base.html

@@ -26,7 +26,7 @@
         {% if user.is_active and user.is_staff %}
         <div id="user-tools">
             {% trans 'Welcome,' %}
-            <strong>{% filter force_escape %}{% firstof user.first_name user.username %}{% endfilter %}</strong>.
+            <strong>{% filter force_escape %}{% firstof user.get_short_name user.username %}{% endfilter %}</strong>.
             {% block userlinks %}
                 {% url 'django-admindocs-docroot' as docsroot %}
                 {% if docsroot %}

django/contrib/admin/templates/admin/login.html

@@ -30,7 +30,7 @@
 <form action="{{ app_path }}" method="post" id="login-form">{% csrf_token %}
   <div class="form-row">
     {% if not form.this_is_the_login_form.errors %}{{ form.username.errors }}{% endif %}
-    <label for="id_username" class="required">{% trans 'Username:' %}</label> {{ form.username }}
+    <label for="id_username" class="required">{{ form.username.label }}:</label> {{ form.username }}
   </div>
   <div class="form-row">
     {% if not form.this_is_the_login_form.errors %}{{ form.password.errors }}{% endif %}

django/contrib/admin/views/decorators.py

@@ -4,6 +4,7 @@
 from django.contrib.auth.views import login
 from django.contrib.auth import REDIRECT_FIELD_NAME
 
+
 def staff_member_required(view_func):
     """
     Decorator for views that checks that the user is logged in and is a staff

django/contrib/auth/__init__.py

@@ -6,9 +6,10 @@
 BACKEND_SESSION_KEY = '_auth_user_backend'
 REDIRECT_FIELD_NAME = 'next'
 
+
 def load_backend(path):
     i = path.rfind('.')
-    module, attr = path[:i], path[i+1:]
+    module, attr = path[:i], path[i + 1:]
     try:
         mod = import_module(module)
     except ImportError as e:
@@ -21,6 +22,7 @@ def load_backend(path):
         raise ImproperlyConfigured('Module "%s" does not define a "%s" authentication backend' % (module, attr))
     return cls()
 
+
 def get_backends():
     from django.conf import settings
     backends = []
@@ -30,6 +32,7 @@ def get_backends():
         raise ImproperlyConfigured('No authentication backends have been defined. Does AUTHENTICATION_BACKENDS contain anything?')
     return backends
 
+
 def authenticate(**credentials):
     """
     If the given credentials are valid, return a User object.
@@ -46,6 +49,7 @@ def authenticate(**credentials):
         user.backend = "%s.%s" % (backend.__module__, backend.__class__.__name__)
         return user
 
+
 def login(request, user):
     """
     Persist a user id and a backend in the request. This way a user doesn't
@@ -69,6 +73,7 @@ def login(request, user):
         request.user = user
     user_logged_in.send(sender=user.__class__, request=request, user=user)
 
+
 def logout(request):
     """
     Removes the authenticated user's ID from the request and flushes their
@@ -86,6 +91,22 @@ def logout(request):
         from django.contrib.auth.models import AnonymousUser
         request.user = AnonymousUser()
 
+
+def get_user_model():
+    "Return the User model that is active in this project"
+    from django.conf import settings
+    from django.db.models import get_model
+
+    try:
+        app_label, model_name = settings.AUTH_USER_MODEL.split('.')
+    except ValueError:
+        raise ImproperlyConfigured("AUTH_USER_MODEL must be of the form 'app_label.model_name'")
+    user_model = get_model(app_label, model_name)
+    if user_model is None:
+        raise ImproperlyConfigured("AUTH_USER_MODEL refers to model '%s' that has not been installed" % settings.AUTH_USER_MODEL)
+    return user_model
+
+
 def get_user(request):
     from django.contrib.auth.models import AnonymousUser
     try:

django/contrib/auth/backends.py

@@ -1,6 +1,6 @@
 from __future__ import unicode_literals
-
-from django.contrib.auth.models import User, Permission
+from django.contrib.auth import get_user_model
+from django.contrib.auth.models import Permission
 
 
 class ModelBackend(object):
@@ -12,10 +12,11 @@ class ModelBackend(object):
     # configurable.
     def authenticate(self, username=None, password=None):
         try:
-            user = User.objects.get(username=username)
+            UserModel = get_user_model()
+            user = UserModel.objects.get_by_natural_key(username)
             if user.check_password(password):
                 return user
-        except User.DoesNotExist:
+        except UserModel.DoesNotExist:
             return None
 
     def get_group_permissions(self, user_obj, obj=None):
@@ -60,8 +61,9 @@ def has_module_perms(self, user_obj, app_label):
 
     def get_user(self, user_id):
         try:
-            return User.objects.get(pk=user_id)
-        except User.DoesNotExist:
+            UserModel = get_user_model()
+            return UserModel.objects.get(pk=user_id)
+        except UserModel.DoesNotExist:
             return None
 
 
@@ -94,17 +96,21 @@ def authenticate(self, remote_user):
         user = None
         username = self.clean_username(remote_user)
 
+        UserModel = get_user_model()
+
         # Note that this could be accomplished in one try-except clause, but
         # instead we use get_or_create when creating unknown users since it has
         # built-in safeguards for multiple threads.
         if self.create_unknown_user:
-            user, created = User.objects.get_or_create(username=username)
+            user, created = UserModel.objects.get_or_create(**{
+                getattr(UserModel, 'USERNAME_FIELD', 'username'): username
+            })
             if created:
                 user = self.configure_user(user)
         else:
             try:
-                user = User.objects.get(username=username)
-            except User.DoesNotExist:
+                user = UserModel.objects.get_by_natural_key(username)
+            except UserModel.DoesNotExist:
                 pass
         return user
 

django/contrib/auth/fixtures/custom_user.json

@@ -0,0 +1,14 @@
+[
+    {
+        "pk": "1",
+        "model": "auth.customuser",
+        "fields": {
+            "password": "sha1$6efc0$f93efe9fd7542f25a7be94871ea45aa95de57161",
+            "last_login": "2006-12-17 07:03:31",
+            "email": "staffmember@example.com",
+            "is_active": true,
+            "is_admin": false,
+            "date_of_birth": "1976-11-08"
+       }
+    }
+]

django/contrib/auth/forms.py

@@ -7,9 +7,10 @@
 from django.utils.html import format_html, format_html_join
 from django.utils.http import int_to_base36
 from django.utils.safestring import mark_safe
+from django.utils.text import capfirst
 from django.utils.translation import ugettext, ugettext_lazy as _
 
-from django.contrib.auth import authenticate
+from django.contrib.auth import authenticate, get_user_model
 from django.contrib.auth.models import User
 from django.contrib.auth.hashers import UNUSABLE_PASSWORD, identify_hasher
 from django.contrib.auth.tokens import default_token_generator
@@ -135,7 +136,7 @@ class AuthenticationForm(forms.Form):
     Base class for authenticating users. Extend this to get a form that accepts
     username/password logins.
     """
-    username = forms.CharField(label=_("Username"), max_length=30)
+    username = forms.CharField(max_length=30)
     password = forms.CharField(label=_("Password"), widget=forms.PasswordInput)
 
     error_messages = {
@@ -157,6 +158,11 @@ def __init__(self, request=None, *args, **kwargs):
         self.user_cache = None
         super(AuthenticationForm, self).__init__(*args, **kwargs)
 
+        # Set the label for the "username" field.
+        UserModel = get_user_model()
+        username_field = UserModel._meta.get_field(getattr(UserModel, 'USERNAME_FIELD', 'username'))
+        self.fields['username'].label = capfirst(username_field.verbose_name)
+
     def clean(self):
         username = self.cleaned_data.get('username')
         password = self.cleaned_data.get('password')
@@ -198,9 +204,10 @@ def clean_email(self):
         """
         Validates that an active user exists with the given email address.
         """
+        UserModel = get_user_model()
         email = self.cleaned_data["email"]
-        self.users_cache = User.objects.filter(email__iexact=email,
-                                               is_active=True)
+        self.users_cache = UserModel.objects.filter(email__iexact=email,
+                                                    is_active=True)
         if not len(self.users_cache):
             raise forms.ValidationError(self.error_messages['unknown'])
         if any((user.password == UNUSABLE_PASSWORD)