Personnalisation de l’authentification dans Django

L’authentification livrée avec Django est suffisante dans la plupart des cas, mais vous pouvez rencontrez des besoins qui ne sont pas couverts par la solution proposée par défaut. Afin de personnaliser l’authentification pour les besoins de vos projets, vous devez comprendre quels sont les points d’ancrage permettant d’étendre et de remplacer les composants du système de Django. Ce document fournit des détails sur la façon dont le système d’authentification peut être adapté.

Les moteurs d’authentification permettent d’adapter le système lorsque un nom d’utilisateur et un mot de passe stockés dans le modèle User doivent servir à authentifier l’utilisateur avec un autre service que celui par défaut de Django.

Vous pouvez donner des permissions personnalisées à vos modèles qui peuvent être vérifiées à travers le système d’autorisation de Django.

Vous pouvez étendre le modèle User par défaut ou le substituer par un tout autre modèle personnalisé.

Autres sources d’authentification

Dans certaines situations, il peut être nécessaire de se connecter à une autre source d’authentification, c’est-à-dire une autre source de noms d’utilisateur et de mots de passe ou d’autres méthodes d’authentification.

Par exemple, votre entreprise possède peut-être déjà une infrastructure LDAP stockant les noms d’utilisateur et mots de passe pour tous ses employés. Il serait fastidieux aussi bien pour l’administrateur réseau que pour les utilisateurs eux-mêmes de devoir gérer des comptes séparés dans LDAP et dans les applications basées sur Django.

Ainsi, pour faire face à ce genre de situations, le système d’authentification de Django vous permet de brancher d’autres sources d’authentification. Vous pouvez surcharger le système par défaut de Django basé sur la base de données ou vous pouvez utiliser le système par défaut en parallèle avec d’autres systèmes.

Consultez la référence sur les moteurs d’authentification pour plus d’informations sur les moteurs d’authentification intégrés à Django.

Définition de moteurs d’authentification

En arrière-plan, Django maintient une liste de « moteurs d’authentification » qu’il sollicite lors de l’authentification. Lorsque quelqu’un appelle django.contrib.auth.authenticate() comme expliqué ci-dessus dans Comment connecter un utilisateur, Django tente une authentification avec chaque moteur d’authentification. Si la première méthode d’authentification échoue, Django essaie avec la deuxième et ainsi de suite jusqu’à ce que tous les moteurs aient été sollicités.

La liste des moteurs d’authentification à utiliser est définie dans le réglage AUTHENTICATION_BACKENDS. Il doit s’agir d’une liste de chemins Python vers des classes Python qui sont capables d’authentifier des utilisateurs. Ces classes peuvent se trouver n’importe où dans votre chemin Python.

Par défaut, AUTHENTICATION_BACKENDS contient :

('django.contrib.auth.backends.ModelBackend',)

Il s’agit du moteur d’authentification de base qui vérifie la base de données Django des utilisateurs et interroge les permissions intégrées. Il ne protège pas contre les attaques de force brute et n’utilise pas de mécanisme de « rate limiting » (restriction du nombre de tentatives dans le temps). Vous pouvez soit écrire votre propre mécanisme de restriction dans un moteur d’authentification personnalisé ou utiliser les mécanismes offerts par la plupart des serveurs Web.

L’ordre dans la liste AUTHENTICATION_BACKENDS a son importance ; si le même nom d’utilisateur et mot de passe est valable dans plusieurs moteurs, Django s’arrête dès qu’un moteur a accepté les données d’authentification.

Si un moteur génère une exception PermissionDenied, l’authentification échouera immédiatement. Django ne continue pas avec les moteurs suivants.

Note

Dès qu’un utilisateur s’est authentifié, Django mémorise le moteur utilisé pour authentifier cet utilisateur dans sa session ; il réutilise ensuite ce même moteur pour toute la durée de la session chaque fois qu’il est nécessaire d’accéder à l’utilisateur actuellement authentifié. Cela signifie en pratique que les sources d’authentification sont mises en cache par session et que si vous modifiez AUTHENTICATION_BACKENDS, vous devrez réinitialiser les données de sessions dans le cas où vous voulez forcer les utilisateurs à s’authentifier à nouveau en utilisant une autre méthode. Une façon simple de faire cela est d’exécuter Session.objects.all().delete().

Écriture d’un moteur d’authentification

Un moteur d’authentification est une classe qui implémente obligatoirement deux méthodes : get_user(user_id) et authenticate(**credentials). Facultativement, elle peut aussi implémenter un ensemble de méthodes d’autorisation liées aux permissions.

La méthode get_user accepte un paramètre user_id, qui peut être un nom d’utilisateur, un identifiant de base de données ou toute autre valeur, mais qui doit représenter la clé primaire de votre objet User. Elle renvoie un objet User.

La méthode authenticate accepte des données d’authentification en paramètre. La plupart du temps, elle ressemblera à ceci :

class MyBackend(object):
    def authenticate(self, username=None, password=None):
        # Check the username/password and return a User.
        ...

Mais elle pourrait aussi authentifier avec un jeton, comme ceci :

class MyBackend(object):
    def authenticate(self, token=None):
        # Check the token and return a User.
        ...

D’une manière ou d’une autre, authenticate doit vérifier les données d’authentification qu’elle reçoit et, dans le cas où ces données sont valides, elle doit renvoyer un objet User correspondant à ces données. Dans le cas contraire, elle doit renvoyer None.

Le site d’administration de Django est étroitement couplé à l’objet User de Django. La meilleure façon de gérer cela est de créer un objet Django User pour chaque utilisateur existant dans votre moteur (par ex. dans votre annuaire LDAP, votre base de données SQL externe, etc.). Vous pouvez soit écrire un script pour le faire de manière anticipée, soit déléguer à votre méthode authenticate la création de l’objet User lors de chaque première connexion.

Voici un exemple de moteur qui s’authentifie en fonction de variables nom d’utilisateur et mot de passe définies dans votre fichier settings.py et crée un objet User de Django lors de la première authentification de l’utilisateur :

from django.conf import settings
from django.contrib.auth.models import User, check_password

class SettingsBackend(object):
    """
    Authenticate against the settings ADMIN_LOGIN and ADMIN_PASSWORD.

    Use the login name, and a hash of the password. For example:

    ADMIN_LOGIN = 'admin'
    ADMIN_PASSWORD = 'sha1$4e987$afbcf42e21bd417fb71db8c66b321e9fc33051de'
    """

    def authenticate(self, username=None, password=None):
        login_valid = (settings.ADMIN_LOGIN == username)
        pwd_valid = check_password(password, settings.ADMIN_PASSWORD)
        if login_valid and pwd_valid:
            try:
                user = User.objects.get(username=username)
            except User.DoesNotExist:
                # Create a new user. Note that we can set password
                # to anything, because it won't be checked; the password
                # from settings.py will.
                user = User(username=username, password='get from settings.py')
                user.is_staff = True
                user.is_superuser = True
                user.save()
            return user
        return None

    def get_user(self, user_id):
        try:
            return User.objects.get(pk=user_id)
        except User.DoesNotExist:
            return None

Gestion des autorisations dans les moteurs personnalisés

Les moteurs d’authentification personnalisés peuvent fournir leurs propres permissions.

Le modèle utilisateur délègue les fonctions de consultation des permissions (get_group_permissions(), get_all_permissions(), has_perm() et has_module_perms()) à tout moteur d’authentification qui implémente ces fonctions.

Les permissions données à l’utilisateur sera un surensemble de toutes les permissions renvoyées par tous les moteurs. Cela signifie que Django accorde une permission à un utilisateur pour autant qu’au moins un moteur le permette.

New in Django 1.8:

Si un moteur génère une exception PermissionDenied dans has_perm() ou has_module_perms(), l’autorisation échouera immédiatement et Django ne continuera pas avec les moteurs suivants.

Le moteur simple ci-dessus pourrait implémenter les permissions pour l’administrateur « magique » assez simplement :

class SettingsBackend(object):
    ...
    def has_perm(self, user_obj, perm, obj=None):
        if user_obj.username == settings.ADMIN_LOGIN:
            return True
        else:
            return False

Cela accorde toutes les permissions à l’utilisateur dont l’accès a été accordé dans l’exemple précédent. Notez qu’en plus des mêmes paramètres passés aux fonctions associées à django.contrib.auth.models.User, les fonctions du moteur d’authentification acceptent toutes en paramètre l’objet utilisateur, qui pourrait être l’utilisateur anonyme.

Une implémentation complète des autorisations se trouve dans la classe ModelBackend dans django/contrib/auth/backends.py, qui constitue le moteur par défaut et interroge la plupart du temps la table auth_permission. Si vous souhaitez définir un comportement personnalisé uniquement pour une partie de l’API des moteurs, vous pouvez profiter de l’héritage Python et hériter de ModelBackend au lieu de réécrire l’API complète dans votre propre moteur.

Autorisation pour les utilisateurs anonymes

Un utilisateur anonyme est un utilisateur que ne s’est pas authentifié, c’est-à-dire qu’il n’a fourni aucun détail d’authentification valide. Cependant, cela ne signifie pas forcément qu’il ne reçoit aucune autorisation. Au niveau le plus élémentaire, la plupart des sites Web autorisent les utilisateurs anonymes à naviguer sur la plupart des pages du site, et certains autorisent également l’envoi de commentaires, etc.

Le système de permissions de Django ne prévoit pas d’endroit où stocker des permissions pour les utilisateurs anonymes. Cependant, l’objet utilisateur transmis au moteur d’authentification peut être un objet django.contrib.auth.models.AnonymousUser permettant au moteur de définir un comportement d’autorisation spécifique aux utilisateurs anonymes. C’est particulièrement utile pour les auteurs d’applications réutilisables qui peuvent déléguer toutes les questions d’autorisations au moteur d’authentification, plutôt que, par exemple, d’exiger des réglages pour contrôler les droits d’accès anonymes.

Autorisation pour les utilisateurs inactifs

Un utilisateur inactif est un utilisateur authentifié mais dont l’attribut is_active est défini à False. Toutefois, cela ne signifie pas qu’ils ne reçoivent aucun droit. Par exemple, ils sont autorisés à activer leur compte.

La prise en charge des utilisateurs anonymes dans le système des permissions permet d’imaginer un scénario où les utilisateurs anonymes ont certaines permissions que les utilisateurs authentifiés inactifs n’ont pas.

N’oubliez pas de tester l’attribut is_active de l’utilisateur dans les méthodes de votre propre moteur de permissions.

Gestion des permissions sur les objets

Le système de permissions de Django pose les fondations pour des permissions sur les objets, même s’il n’existe pas d’implémentation concrète dans le cœur de Django. Cela signifie que le contrôle des permissions sur les objets renvoie toujours False ou une liste vide (selon le contrôle effectué). Un moteur d’authentification reçoit les paramètres nommés obj et user_obj pour chaque méthode d’autorisation liée aux objets et peut renvoyer les permissions au niveau des objets comme il convient.

Permissions personnalisées

Pour créer des permissions personnalisées pour un objet modèle donné, utilisez l’attribut Meta permissions du modèle`.

Ce modèle d’exemple Task crée trois permissions personnalisées, c’est-à-dire des actions que les utilisateurs peuvent effectuer ou non avec les instances Task, spécifiquement à votre application :

class Task(models.Model):
    ...
    class Meta:
        permissions = (
            ("view_task", "Can see available tasks"),
            ("change_task_status", "Can change the status of tasks"),
            ("close_task", "Can remove a task by setting its status as closed"),
        )

La seule conséquence de ce code est la création de ces permissions supplémentaires lors du lancement de manage.py migrate (la fonction qui crée les permissions est connectée au signal post_migrate). Votre code a ensuite la charge de contrôler la valeur de ces permissions lorsqu’un utilisateur essaie d’accéder à la fonctionnalité fournie par l’application (affichage de tâches, modification de l’état des tâches, fermeture des tâches). En poursuivant sur l’exemple précédent, le code suivant contrôle si un utilisateur peut voir les tâches :

user.has_perm('app.view_task')

Extension du modèle User existant

Il existe deux manières d’étendre le modèle User par défaut sans le substituer par votre propre modèle. Si les modifications requises sont purement comportementales et ne nécessitent pas de modifier ce qui est stocké dans la base de données, vous pouvez créer un modèle mandataire basé sur User. Ceci expose toutes les fonctionnalités offertes par les modèles mandataires, y compris l’ordre de tri par défaut, les gestionnaires personnalisés ou les méthodes de modèle personnalisées.

Si vous souhaitez stocker des informations liées au modèle User, vous pouvez utiliser une relation un-à-un vers un modèle contenant les champs correspondant aux informations supplémentaires. Ce modèle un-à-un est souvent appelé un modèle de profil, car il peut stocker des informations non liées à l’authentification au sujet d’un utilisateur du site. Par exemple, vous pouvez créer un modèle Employee:

from django.contrib.auth.models import User

class Employee(models.Model):
    user = models.OneToOneField(User)
    department = models.CharField(max_length=100)

En supposant qu’il existe un employé Fred Smith référencé à la fois par un modèle User et un modèle Employee, vous pouvez accéder aux informations liées en utilisant les conventions standards des modèles liés de Django :

>>> u = User.objects.get(username='fsmith')
>>> freds_department = u.employee.department

Pour ajouter les champs du modèle de profil à la page de l’utilisateur dans l’interface d’administration, définissez un InlineModelAdmin (pour cet exemple, nous utiliserons un StackedInline) dans le fichier admin.py de votre application et ajoutez-le à une classe UserAdmin qui sera enregistrée avec la classe User:

from django.contrib import admin
from django.contrib.auth.admin import UserAdmin as BaseUserAdmin
from django.contrib.auth.models import User

from my_user_profile_app.models import Employee

# Define an inline admin descriptor for Employee model
# which acts a bit like a singleton
class EmployeeInline(admin.StackedInline):
    model = Employee
    can_delete = False
    verbose_name_plural = 'employee'

# Define a new User admin
class UserAdmin(BaseUserAdmin):
    inlines = (EmployeeInline, )

# Re-register UserAdmin
admin.site.unregister(User)
admin.site.register(User, UserAdmin)

Ces modèles de profil n’ont aucune particularité, ce ne sont que des modèles Django qui possèdent un lien un-à-un avec un modèle User. En tant que tels, ils ne sont pas automatiquement créés lorsqu’un utilisateur est créé, mais il est possible de profiter du signal django.db.models.signals.post_save pour créer ou mettre à jour les modèles liés selon les besoins.

Notez que l’utilisation de modèles liés provoque des requêtes ou des jointures supplémentaires pour récupérer les données liées et que donc, en fonction de vos besoins, il peut être préférable de substituer le modèle User par un modèle possédant les champs supplémentaires. Cependant, des liens existants vers le modèle User par défaut dans les applications de votre projet pourraient justifier la charge supplémentaire sur la base de données.

Substitution par un modèle User personnalisé

Certains types de projets ont des exigences en terme d’authentification pour lesquelles le modèle User intégré de Django ne convient pas toujours. Par exemple, certains sites préfèrent utiliser l’adresse électronique comme identifiant d’identification plutôt qu’un nom d’utilisateur.

Django permet de surcharger le modèle User par défaut en attribuant une valeur au réglage AUTH_USER_MODEL se référant à un modèle personnalisé :

AUTH_USER_MODEL = 'myapp.MyUser'

Cette syntaxe pointée spécifie le nom de l’application Django (qui doit figurer dans INSTALLED_APPS) et le nom du modèle Django que vous souhaitez utiliser comme modèle d’utilisateur.

Avertissement

La modification de AUTH_USER_MODEL a une forte influence sur la structure de votre base de données. Cela modifie les tables disponibles et affecte la construction de clés étrangères et de relations plusieurs-à-plusieurs. Si vous avez l’intention de définir AUTH_USER_MODEL, il est préférable de le faire avant de créer la première migration ou de lancer manage.py migrate pour la première fois.

La modification de ce paramètre après avoir créé les tables n’est pas prise en charge par makemigrations et vous devrez corriger manuellement votre schéma, reprendre les données de l’ancienne table des utilisateurs, et peut-être réappliquer manuellement certaines migrations.

Avertissement

En raison des limites de Django liées à la fonctionnalité de dépendance dynamique pour les modèles remplaçables à chaud, vous devez vous assurer que le modèle référencé par AUTH_USER_MODEL est créé lors de la première migration de son application (généralement appelée 0001_initial) ; sinon, vous aurez des problèmes de dépendances.

En outre, vous pouvez rencontrer une erreur CircularDependencyError lors de l’exécution des migrations lorsque Django n’est pas en mesure de briser automatiquement la boucle de dépendance en raison de la dépendance dynamique. Si vous rencontrez cette erreur, vous devez rompre la boucle en déplaçant les modèles dont dépend votre modèle d’utilisateur dans une deuxième migration (vous pouvez essayer de faire deux modèles normaux qui ont une clé ForeignKey l’un vers l’autre et voir comment makemigrations résout la dépendance circulaire si vous voulez voir comment cela se passe habituellement).

Applications réutilisables et AUTH_USER_MODEL

Les applications réutilisables ne devraient pas implémenter de modèle d’utilisateur personnalisé. Un projet peut utiliser beaucoup d’applications, et deux applications réutilisables qui implémenteraient chacune un modèle d’utilisateur personnalisé ne pourraient pas être utilisées conjointement. Si vous avez besoin de stocker des informations liées aux utilisateurs dans une application, utilisez une liaison ForeignKey ou OneToOneField vers settings.AUTH_USER_MODEL comme expliqué ci-dessous.

Références au modèle d’utilisateur

Si vous référencez directement User (par exemple dans une clé étrangère), votre code ne fonctionnera pas dans des projets où le réglage AUTH_USER_MODEL a été défini à un autre modèle d’utilisateur.

get_user_model()[source]

Au lieu de faire directement référence à User, il est préférable de référencer le modèle d’utilisateur en utilisant django.contrib.auth.get_user_model(). Cette méthode renvoie le modèle d’utilisateur actuellement actif, soit le modèle personnalisé s’il a été défini, soit User.

Lorsque vous définissez une clé étrangère ou des relations plusieurs-à-plusieurs vers le modèle d’utilisateur, vous devriez indiquer le modèle personnalisé au moyen du réglage AUTH_USER_MODEL. Par exemple :

from django.conf import settings
from django.db import models

class Article(models.Model):
    author = models.ForeignKey(settings.AUTH_USER_MODEL)

New in Django 1.7:

Lorsque vous vous connectez aux signaux envoyés par le modèle d’utilisateur, vous devriez indiquer le modèle personnalisé au moyen du réglage AUTH_USER_MODEL. Par exemple :

from django.conf import settings
from django.db.models.signals import post_save

def post_save_receiver(sender, instance, created, **kwargs):
    pass

post_save.connect(post_save_receiver, sender=settings.AUTH_USER_MODEL)

En règle générale, vous devez référencer le modèle d’utilisateur avec le réglage AUTH_USER_MODEL dans tout code exécuté au moment de l’importation. get_user_model() ne fonctionne qu’une fois que Django a importé tous les modèles.

Indication d’une modèle d’utilisateur personnalisé

Considérations sur la conception des modèles

Réfléchissez sérieusement avant de déléguer les informations non directement liées à l’authentification au modèle d’utilisateur personnalisé.

Il peut être préférable de stocker les informations d’utilisateur spécifiques à une application dans un modèle ayant une relation avec le modèle User. Cela permet à chaque application de définir ses propres exigences de données utilisateurs sans risquer d’entrer en conflit avec les autres applications. D’un autre côté, les requêtes qui auront besoin de ces informations liées devront effectuer une jointure de base de données, ce qui peut avoir une influence sur les performances.

Django s’attend à ce qu’un minimum d’exigences soient respectées dans les modèles d’utilisateur personnalisés.

1. Le modèle doit comporter un seul champ unique pouvant être utilisé pour l’identification. Cela peut être un nom d’utilisateur, une adresse électronique ou tout autre attribut unique.

2. Le modèle doit fournir une manière de décrire l’utilisateur dans une forme « courte » et dans une forme « longue ». L’interprétation la plus courante étant de considérer le prénom comme identifiant « court » et le nom complet comme identifiant « long ». Cependant, il n’y a aucune contrainte sur les valeurs renvoyées par ces deux méthodes ; elles peuvent tout aussi bien renvoyer la même valeur si vous le souhaitez.

Changed in Django 1.8:

Les versions précédentes de Django exigeaient que le modèle possède également une clé primaire de type nombre entier.

La manière la plus simple de construire un modèle d’utilisateur personnalisé en respectant les contraintes est d’hériter de AbstractBaseUser. Cette classe fournit l’implémentation de base d’un modèle User, y compris les mots de passe hachés et les jetons de réinitialisation des mots de passe. Vous devez ensuite fournir les détails d’implémentation critiques :

class models.CustomUser

USERNAME_FIELD

Une chaîne contenant le nom du champ du modèle d’utilisateur utilisé comme identifiant unique. C’est normalement quelque chose comme un nom d’utilisateur ou une adresse électronique, ou encore tout autre identifiant unique. Ce champ doit être unique (c’est-à-dire que unique=True doit apparaître dans sa définition).

Dans l’exemple suivant, le champ identifier est utilisé comme champ d’identification :

class MyUser(AbstractBaseUser):
    identifier = models.CharField(max_length=40, unique=True)
    ...
    USERNAME_FIELD = 'identifier'

New in Django 1.8.

USERNAME_FIELD prend dorénavant en charge les clés ForeignKey. Comme il n’existe pas de moyen de passer des instances de modèles durant le dialogue avec createsuperuser, attendez-vous à ce que l’utilisateur saisisse la valeur de to_field (la clé primaire primary_key par défaut) d’une instance existante.

REQUIRED_FIELDS

Une liste de noms de champs qui devront être renseignés lors de la création d’un utilisateur par la commande de gestion createsuperuser. La commande demandera de fournir une valeur pour chacun de ces champs. Cette liste doit contenir tous les champs pour lesquels l’attribut blank est False ou non défini, et peut inclure des champs supplémentaires pour lesquels vous souhaitez que l’utilisateur donne une valeur lorsqu’un utilisateur est créé de manière interactive. REQUIRED_FIELDS n’a aucun effet dans d’autres parties de Django, comme lors de la création d’un utilisateur par l’interface d’administration.

Par exemple, voici la définition partielle d’un modèle d’utilisateur définissant deux champs obligatoires, une date de naissance et une hauteur :

class MyUser(AbstractBaseUser):
    ...
    date_of_birth = models.DateField()
    height = models.FloatField()
    ...
    REQUIRED_FIELDS = ['date_of_birth', 'height']

Note

REQUIRED_FIELDS doit contenir tous les champs obligatoires de votre modèle d’utilisateur, mais ne doit pas contenir le champ USERNAME_FIELD ni le champ password car de toute façon, il faudra fournir des valeurs pour ces champs.

New in Django 1.8.

REQUIRED_FIELDS prend dorénavant en charge les clés ForeignKey. Comme il n’existe pas de moyen de passer des instances de modèles durant le dialogue avec createsuperuser, attendez-vous à ce que l’utilisateur saisisse la valeur de to_field (la clé primaire primary_key par défaut) d’une instance existante.

is_active

Un attribut booléen indiquant si l’utilisateur est considéré comme « actif ». Cet attribut est fournit comme attribut de AbstractBaseUser et valant True par défaut. La manière dont vous allez l’implémenter dépendra des détails des moteurs d’authentification choisis. Consultez la documentation de l’attribut is_active du modèle d’utilisateur intégré pour plus de détails.

get_full_name()

Une façon longue d’identifier formellement un utilisateur. Fréquemment interprété comme le nom complet de l’utilisateur, mais cela peut être n’importe quelle chaîne de caractères identifiant la personne.

get_short_name()

Un identifiant court et informel de l’utilisateur. Fréquemment interprété comme le prénom de l’utilisateur, mais cela peut être n’importe quelle chaîne de caractères identifiant l’utilisateur de manière informelle. Elle peut aussi renvoyer la même valeur que django.contrib.auth.models.User.get_full_name().

Les méthodes suivantes sont disponibles pour chaque sous-classe de AbstractBaseUser:

class models.AbstractBaseUser

get_username()

Renvoie la valeur du champ spécifié dans USERNAME_FIELD.

is_anonymous()

Renvoie toujours False. C’est une manière de différencier ces objets de AnonymousUser. Généralement, il est préférable d’utiliser la méthode is_authenticated().

is_authenticated()

Renvoie toujours True. C’est une manière de savoir si l’utilisateur a été authentifié. Cela ne dit rien sur les permissions et ne vérifie pas si l’utilisateur est actif. C’est seulement une indication que l’utilisateur a fourni un nom d’utilisateur et un mot de passe valides.

set_password(raw_password)

Définit le mot de passe de l’utilisateur à la chaîne brute indiquée, en se chargeant du hachage du mot de passe. L’objet AbstractBaseUser n’est pas enregistré par cette méthode.

Lorsque raw_password vaut None, le mot de passe sera défini comme non utilisable, comme si on avait appelé set_unusable_password().

check_password(raw_password)

Renvoie True si la chaîne brute transmise est le mot de passe correct de cet utilisateur (cette méthode se charge du hachage du mot de passe en vue de la comparaison).

set_unusable_password()

Marque l’utilisateur comme n’ayant pas de mot de passe défini. Ce n’est pas la même chose que de définir une chaîne vide comme mot de passe. check_password() ne renvoie jamais True pour cet utilisateur. L’objet AbstractBaseUser n’est pas enregistré par cette méthode.

Cela peut être utile si le processus d’authentification de votre application se fait par une source externe existante telle qu’un annuaire LDAP.

has_usable_password()

Renvoie False si set_unusable_password() a été appelée pour cet utilisateur.

get_session_auth_hash()

New in Django 1.7.

Renvoie une empreinte HMAC du champ de mot de passe. Utilisé pour Invalidation de session lors du changement de mot de passe.

Il faudrait aussi défini un gestionnaire personnalisé pour votre modèle User. Si ce dernier définit les champs username, email, is_staff, is_active, is_superuser, last_login et date_joined comparables au modèle User par défaut de Django, vous pouvez simplement utiliser le gestionnaire UserManager de Django. Cependant, si votre modèle User définit des champs différents, vous devrez définir un gestionnaire personnalisé héritant de BaseUserManager et fournissant deux méthodes supplémentaires :

class models.CustomUserManager

create_user(*username_field*, password=None, **other_fields)

Le prototype de create_user() doit accepter en paramètre le champ nom d’utilisateur ainsi que tous les champs obligatoires. Par exemple, si votre modèle d’utilisateur utilise email comme champ nom d’utilisateur et que date_of_birth est un champ obligatoire, create_user devrait être définie ainsi :

def create_user(self, email, date_of_birth, password=None):
    # create user here
    ...

create_superuser(*username_field*, password, **other_fields)

Le prototype de create_superuser() doit accepter en paramètre le champ nom d’utilisateur ainsi que tous les champs obligatoires. Par exemple, si votre modèle d’utilisateur utilise email comme champ nom d’utilisateur et que date_of_birth est un champ obligatoire, create_superuser devrait être définie ainsi :

def create_superuser(self, email, date_of_birth, password):
    # create superuser here
    ...

Au contraire de create_user(), create_superuser() doit exiger de l’appelant qu’il fournisse un mot de passe.

BaseUserManager fournit les méthodes utilitaires suivantes :

class models.BaseUserManager

normalize_email(email)

Une classmethod qui normalise les adresses électroniques en transformant en minuscules la partie nom de domaine de l’adresse.

get_by_natural_key(username)

Récupère une instance utilisateur en utilisant le contenu du champ spécifié dans USERNAME_FIELD.

make_random_password(length=10, allowed_chars='abcdefghjkmnpqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789')

Renvoie un mot de passe aléatoire de la longueur indiquée et utilisant les caractères de la chaîne des caractères autorisés. Notez que la valeur par défaut de allowed_chars ne contient pas de lettres pouvant prêter à confusion, comme :

• i, l, I et 1 (i minuscule, L minuscule, i majuscule et le chiffre 1)

• o, O et 0 (o minuscule, o majuscule et zéro)

Extension du modèle User par défaut de Django

Si le modèle User de Django vous convient entièrement et que vous voulez simplement ajouter quelques informations de profil supplémentaires, il suffit d’hériter de django.contrib.auth.models.AbstractUser et d’ajouter vos propres champs de profil. Il est toutefois conseillé de créer un modèle séparé, comme indiqué dans la note « Considérations de conception des modèles » de Indication d’une modèle d’utilisateur personnalisé. AbstractUser fournit une implémentation complète du modèle User par défaut sous forme de modèle abstrait.

Utilisateurs personnalisés et formulaires d’authentification intégrés

Comme l’on peut s’y attendre, les formulaires et les vues intégrés de Django ont certaines attentes à propos du modèle utilisateur avec lequel ils fonctionnent.

Si votre modèle utilisateur ne correspond pas à ces attentes, il peut être nécessaire de définir des formulaires de remplacement et de transmettre ces formulaires dans la configuration des vues d’authentification.

• UserCreationForm

  Dépend du modèle User. Doit être réécrit pour tout modèle utilisateur personnalisé.

• UserChangeForm

  Dépend du modèle User. Doit être réécrit pour tout modèle utilisateur personnalisé.

• AuthenticationForm

  Fonctionne avec toute sous-classe de AbstractBaseUser, et s’adapte afin d’utiliser le champ défini dans USERNAME_FIELD.

• PasswordResetForm

  S’attend à ce que le modèle d’utilisateur possède un champ nommé email permettant d’identifier l’utilisateur et un champ booléen nommé is_active pour empêcher les utilisateurs inactifs de réinitialiser leur mot de passe.

• SetPasswordForm

  Fonctionne avec toute sous-classe de AbstractBaseUser.

• PasswordChangeForm

  Fonctionne avec toute sous-classe de AbstractBaseUser.

• AdminPasswordChangeForm

  Fonctionne avec toute sous-classe de AbstractBaseUser.

Utilisateurs personnalisés et django.contrib.admin

Si vous souhaitez que votre modèle utilisateur personnalisé fonctionne également dans l’interface d’administration, celui-ci doit définir certains attributs et méthodes supplémentaires. Ces méthodes permettent au site d’administration de contrôler l’accès de l’utilisateur à son contenu :

class models.CustomUser

is_staff

Renvoie True si l’utilisateur est autorisé à accéder au site d’administration.

is_active

Renvoie True si le compte utilisateur est actuellement actif.

has_perm(perm, obj=None):

Renvoie True si l’utilisateur possède la permission indiquée. Si obj est transmis, la permission doit être vérifiée en relation avec une instance d’objet spécifique.

has_module_perms(app_label):

Renvoie True si l’utilisateur possède la permission d’accéder aux modèles de l’application indiquée.

Il sera aussi nécessaire d’inscrire le modèle d’utilisateur personnalisé à l’interface d’administration. Si votre modèle hérite de django.contrib.auth.models.AbstractUser, vous pouvez utiliser la classe existante de Django django.contrib.auth.admin.UserAdmin. Cependant, si votre modèle hérite de AbstractBaseUser, vous devrez définir une classe ModelAdmin personnalisée. Il est possible d’hériter de la classe django.contrib.auth.admin.UserAdmin, mais il faudra alors surcharger toutes les définitions qui se référent à des champs de django.contrib.auth.models.AbstractUser et qui ne se trouvent pas dans votre classe d’utilisateur personnalisée.

Utilisateurs personnalisés et permissions

Pour faciliter l’intégration du système des permissions de Django à votre propre classe d’utilisateur, Django propose PermissionsMixin. Il s’agit d’un modèle abstrait que vous pouvez ajouter à la hiérarchie de classes de votre modèle d’utilisateur et qui vous offre ainsi toutes les méthodes et les champs de base de données nécessaires pour la prise en charge du modèle des permissions de Django.

PermissionsMixin contient les méthodes et attributs suivants :

class models.PermissionsMixin

is_superuser

Valeur booléenne. Indique que cet utilisateur possède toutes les permissions sans avoir besoin de les lui attribuer explicitement.

get_group_permissions(obj=None)

Renvoie l’ensemble des permissions (chaînes) que l’utilisateur obtient au travers des groupes auxquels il/elle appartient.

Si obj est transmis, ne renvoie que les permissions de groupe liées à cet objet spécifique.

get_all_permissions(obj=None)

Renvoie l’ensemble des permissions (chaînes) que l’utilisateur obtient directement ou au travers des groupes auxquels il appartient.

Si obj est transmis, ne renvoie que les permissions liées à cet objet spécifique.

has_perm(perm, obj=None)

Renvoie True si l’utilisateur possède la permission indiquée, où perm est au format "<étiquette application>.<code permission>" (voir permissions). Si l’utilisateur est inactif, cette méthode renvoie toujours False.

Si obj est transmis, cette méthode ne contrôle pas la permission au niveau du modèle, mais pour l’objet indiqué.

has_perms(perm_list, obj=None)

Renvoie True si l’utilisateur possède toutes les permissions indiquées, où chaque permission est au format "<étiquette application>.<code permission>". Si l’utilisateur est inactif, cette méthode renvoie toujours False.

Si obj est transmis, cette méthode ne contrôle pas les permissions au niveau du modèle, mais pour l’objet indiqué.

has_module_perms(package_name)

Renvoie True si l’utilisateur possède au moins une permission dans le module indiqué (l’étiquette d’application Django). Si l’utilisateur est inactif, cette méthode renvoie toujours False.

ModelBackend

Si vous n’intégrez pas PermissionsMixin vous devez vous assurer de ne pas appeler les méthodes de permissions sur ModelBackend. ModelBackend s’attend à ce que certains champs soient disponibles dans votre modèle d’utilisateur. Si ce dernier ne fournit pas ces champs, vous obtiendrez des erreurs de base de données lorsque vous contrôlez les permissions.

Utilisateurs personnalisés et modèles mandataires

Une limite connue des modèles d’utilisateur personnalisés est que leur installation casse tout modèle mandataire étendant le modèle User. Les modèles mandataires doivent hériter d’une classe de base concrète ; en définissant un modèle d’utilisateur personnalisé, vous supprimez la capacité de Django à identifier de manière fiable la classe de base.

Si votre projet utilise des modèles mandataires, vous devez soit modifier ces modèles afin qu’ils étendent le modèle d’utilisateur réellement utilisé dans votre projet, soit fusionner le comportement du modèle mandataire dans votre sous-classe de User.

Utilisateurs personnalisés et tests/instantanés

Si vous écrivez une application qui interagit avec le modèle d’utilisateur, vous devez prendre certaines précautions pour vous assurer que votre suite de tests fonctionne quel que soit le modèle d’utilisateur utilisé par un projet. Tout test qui crée une instance d’utilisateur risque d’échouer si le modèle d’utilisateur a été substitué. Cela s’applique aussi à la création d’utilisateurs au moyen d’instantanés.

Pour s’assurer que la suite de tests passe quelle que soit la configuration du projet, django.contrib.auth.tests.utils définit un décorateur @skipIfCustomUser. Celui-ci provoque l’omission du test si un modèle User différent de celui de Django est utilisé. Ce décorateur peut être appliqué à un seul test ou à toute une classe de tests.

En fonction de votre application, il peut aussi être nécessaire d’ajouter des tests pour être sûr que l’application fonctionne avec tout modèle d’utilisateur, pas simplement avec le modèle User par défaut. Pour vous aider dans cette tâche, Django fournit deux modèles d’utilisateur de substitution pouvant être utilisés dans les suites de tests :

class tests.custom_user.CustomUser

Un modèle d’utilisateur personnalisé utilisant un champ email comme nom d’utilisateur et doté d’une configuration de permissions de base adaptée à l’interface d’administration ;

class tests.custom_user.ExtensionUser

Un modèle d’utilisateur personnalisé héritant de django.contrib.auth.models.AbstractUser et avec un champ supplémentaire date_of_birth.

Vous pouvez dès lors utiliser le décorateur @override_settings pour que le test en question utilise le modèle d’utilisateur personnalisé. Par exemple, voici un canevas de tests pour tester trois modèles d’utilisateur, celui par défaut ainsi que les deux modèles d’utilisateur fournis par l’application auth:

from django.contrib.auth.tests.utils import skipIfCustomUser
from django.contrib.auth.tests.custom_user import CustomUser, ExtensionUser
from django.test import TestCase, override_settings


class ApplicationTestCase(TestCase):
    @skipIfCustomUser
    def test_normal_user(self):
        "Run tests for the normal user model"
        self.assertSomething()

    @override_settings(AUTH_USER_MODEL='auth.CustomUser')
    def test_custom_user(self):
        "Run tests for a custom user model with email-based authentication"
        self.assertSomething()

    @override_settings(AUTH_USER_MODEL='auth.ExtensionUser')
    def test_extension_user(self):
        "Run tests for a simple extension of the built-in User."
        self.assertSomething()

Un exemple complet

Voici un exemple d’application d’utilisateur personnalisé compatible avec l’interface d’administration. Ce modèle d’utilisateur utilise une adresse électronique comme nom d’utilisateur et possède un champ date de naissance obligatoire ; il ne fournit aucun contrôle de permission, excepté un simple drapeau admin sur le compte utilisateur. Ce modèle est compatible avec tous les formulaires et les vues d’authentification intégrés, à l’exception des formulaires de création d’utilisateur. Cet exemple illustre la façon dont la plupart des composants interagissent, mais il ne s’agit pas de code pouvant être directement copié dans des projets en production.

Ce code pourrait être entièrement placé dans un fichier models.py d’une application d’authentification personnalisée :

from django.db import models
from django.contrib.auth.models import (
    BaseUserManager, AbstractBaseUser
)


class MyUserManager(BaseUserManager):
    def create_user(self, email, date_of_birth, password=None):
        """
        Creates and saves a User with the given email, date of
        birth and password.
        """
        if not email:
            raise ValueError('Users must have an email address')

        user = self.model(
            email=self.normalize_email(email),
            date_of_birth=date_of_birth,
        )

        user.set_password(password)
        user.save(using=self._db)
        return user

    def create_superuser(self, email, date_of_birth, password):
        """
        Creates and saves a superuser with the given email, date of
        birth and password.
        """
        user = self.create_user(email,
            password=password,
            date_of_birth=date_of_birth
        )
        user.is_admin = True
        user.save(using=self._db)
        return user


class MyUser(AbstractBaseUser):
    email = models.EmailField(
        verbose_name='email address',
        max_length=255,
        unique=True,
    )
    date_of_birth = models.DateField()
    is_active = models.BooleanField(default=True)
    is_admin = models.BooleanField(default=False)

    objects = MyUserManager()

    USERNAME_FIELD = 'email'
    REQUIRED_FIELDS = ['date_of_birth']

    def get_full_name(self):
        # The user is identified by their email address
        return self.email

    def get_short_name(self):
        # The user is identified by their email address
        return self.email

    def __str__(self):              # __unicode__ on Python 2
        return self.email

    def has_perm(self, perm, obj=None):
        "Does the user have a specific permission?"
        # Simplest possible answer: Yes, always
        return True

    def has_module_perms(self, app_label):
        "Does the user have permissions to view the app `app_label`?"
        # Simplest possible answer: Yes, always
        return True

    @property
    def is_staff(self):
        "Is the user a member of staff?"
        # Simplest possible answer: All admins are staff
        return self.is_admin

Puis, pour inscrire ce modèle d’utilisateur personnalisé dans l’administration de Django, le code suivant doit se trouver dans le fichier admin.py de l’application :

from django import forms
from django.contrib import admin
from django.contrib.auth.models import Group
from django.contrib.auth.admin import UserAdmin as BaseUserAdmin
from django.contrib.auth.forms import ReadOnlyPasswordHashField

from customauth.models import MyUser


class UserCreationForm(forms.ModelForm):
    """A form for creating new users. Includes all the required
    fields, plus a repeated password."""
    password1 = forms.CharField(label='Password', widget=forms.PasswordInput)
    password2 = forms.CharField(label='Password confirmation', widget=forms.PasswordInput)

    class Meta:
        model = MyUser
        fields = ('email', 'date_of_birth')

    def clean_password2(self):
        # Check that the two password entries match
        password1 = self.cleaned_data.get("password1")
        password2 = self.cleaned_data.get("password2")
        if password1 and password2 and password1 != password2:
            raise forms.ValidationError("Passwords don't match")
        return password2

    def save(self, commit=True):
        # Save the provided password in hashed format
        user = super(UserCreationForm, self).save(commit=False)
        user.set_password(self.cleaned_data["password1"])
        if commit:
            user.save()
        return user


class UserChangeForm(forms.ModelForm):
    """A form for updating users. Includes all the fields on
    the user, but replaces the password field with admin's
    password hash display field.
    """
    password = ReadOnlyPasswordHashField()

    class Meta:
        model = MyUser
        fields = ('email', 'password', 'date_of_birth', 'is_active', 'is_admin')

    def clean_password(self):
        # Regardless of what the user provides, return the initial value.
        # This is done here, rather than on the field, because the
        # field does not have access to the initial value
        return self.initial["password"]


class UserAdmin(BaseUserAdmin):
    # The forms to add and change user instances
    form = UserChangeForm
    add_form = UserCreationForm

    # The fields to be used in displaying the User model.
    # These override the definitions on the base UserAdmin
    # that reference specific fields on auth.User.
    list_display = ('email', 'date_of_birth', 'is_admin')
    list_filter = ('is_admin',)
    fieldsets = (
        (None, {'fields': ('email', 'password')}),
        ('Personal info', {'fields': ('date_of_birth',)}),
        ('Permissions', {'fields': ('is_admin',)}),
    )
    # add_fieldsets is not a standard ModelAdmin attribute. UserAdmin
    # overrides get_fieldsets to use this attribute when creating a user.
    add_fieldsets = (
        (None, {
            'classes': ('wide',),
            'fields': ('email', 'date_of_birth', 'password1', 'password2')}
        ),
    )
    search_fields = ('email',)
    ordering = ('email',)
    filter_horizontal = ()

# Now register the new UserAdmin...
admin.site.register(MyUser, UserAdmin)
# ... and, since we're not using Django's built-in permissions,
# unregister the Group model from admin.
admin.site.unregister(Group)

Finalement, définissez le modèle personnalisé comme modèle d’utilisateur par défaut dans votre projet au moyen du réglage AUTH_USER_MODEL dans votre fichier settings.py:

AUTH_USER_MODEL = 'customauth.MyUser'