django.contrib.auth

Ce document présente le matériel de référence d’API des composants du système d’authentification de Django. Pour plus de détails sur l’utilisation de ces composants et sur la manière de personnaliser l’authentification et l’autorisation, consultez le guide thématique sur l’authentification.

Le modèle User

Champs

class models.User

Les objets User possèdent les champs suivants :

username

Obligatoire. Au maximum 150 caractères. Les noms d’utilisateur peuvent contenir des caractères alphanumériques (_, @, +, . et -).

La longueur max_length devrait suffire dans beaucoup de situations. Si vous avez besoin d’une plus grande longueur, utilisez plutôt un modèle d’utilisateur personnalisé. Si vous utilisez MySQL avec le codage utf8mb4 (recommandé pour une prise en charge intégrale d’Unicode), indiquez au maximum max_length=191 parce que MySQL ne peut créer d’index unique que jusqu’à une longueur de 191 caractères dans ce cas.

Noms d’utilisateurs et Unicode

Django n’acceptait à l’origine que des lettres ASCII dans les noms d’utilisateurs. Même si ce n’a pas été un choix délibéré, les caractères Unicode ont toujours été acceptés avec Python 3. Django 1.10 ajoute officiellement la prise en charge de l’Unicode dans les noms d’utilisateurs, en conservant le comportement ASCII pur avec Python 2.

Changed in Django 1.10:

La longueur maximale max_length a passé de 30 à 150 caractères.

first_name

Facultatif. Au maximum 30 caractères.

last_name

Facultatif. Au maximum 30 caractères.

email

Facultatif. Adresse électronique.

password

Obligatoire. Une empreinte avec métadonnées du mot de passe (Django ne stocke pas le mot de passe en clair). La longueur des mots de passe réels n’est pas limitée, ni les caractères qu’ils contiennent. Voir la documentation sur les mots de passe.

groups

Une relation plusieurs-à-plusieurs vers Group.

user_permissions

Une relation plusieurs-à-plusieurs vers Permission.

is_staff

Valeur booléenne. Indique si cet utilisateur peut accéder au site d’administration.

is_active

Valeur booléenne. Indique si cet utilisateur doit être considéré comme actif. Nous recommandons de définir ce drapeau à False au lieu de supprimer le compte ; ainsi, si vos applications comportent des clés étrangères vers des utilisateurs, les clés étrangères ne seront pas cassées.

Ceci ne détermine pas forcément si l’utilisateur peut se connecter ou non. Les moteurs d’authentification ne sont pas obligés de vérifier le drapeau is_active, mais le moteur par défaut (ModelBackend) et le moteur RemoteUserBackend le font. Vous pouvez utiliser AllowAllUsersModelBackend ou AllowAllUsersRemoteUserBackend si vous voulez autoriser les utilisateurs inactifs à se connecter. Dans ce cas, vous devrez aussi adapter le formulaire AuthenticationForm utilisé par la vue login() car il rejette les utilisateurs inactifs. Soyez conscient que les méthodes de contrôle des permissions telles que has_perm() ainsi que l’authentification dans le site d’administration de Django renvoient toutes False pour les utilisateurs inactifs.

Changed in Django 1.10:

Dans les anciennes versions, ModelBackend et RemoteUserBackend permettaient aux utilisateurs inactifs de s’authentifier.

is_superuser

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

last_login

Horodatage de la dernière connexion de l’utilisateur.

date_joined

Horodatage indiquant la date de création du compte. Défini par défaut à la date/heure du moment où le compte a été créé.

Attributs

class models.User

is_authenticated

Attribut en lecture seule qui vaut toujours True (contrairement à AnonymousUser.is_authenticated qui vaut toujours False). C’est une façon de savoir si l’utilisateur a été authentifié. Aucune permission n’est prise en compte et il n’y a pas de contrôle sur le drapeau is_active de l’utilisateur ou sur la validité de la session. Même si cet attribut est généralement consulté pour request.user afin de déterminer s’il a été défini par AuthenticationMiddleware (représentant l’utilisateur actuellement connecté), vous devez savoir que cet attribut vaut True pour toute instance de User.

Changed in Django 1.10:

Dans les anciennes versions, il s’agissait d’une méthode. La rétro-compatibilité permettant de l’utiliser comme une méthode sera enlevée dans Django 2.0.

is_anonymous

Attribut en lecture seule qui vaut toujours False. C’est une façon de différencier les objets User des objets AnonymousUser. Généralement, il vaut mieux utiliser is_authenticated que cet attribut.

Changed in Django 1.10:

Dans les anciennes versions, il s’agissait d’une méthode. La rétro-compatibilité permettant de l’utiliser comme une méthode sera enlevée dans Django 2.0.

Méthodes

class models.User

get_username()

Renvoie le nom d’utilisateur de cet utilisateur. Comme le modèle User peut être substitué, il est préférable d’utiliser cette méthode plutôt que de référencer directement l’attribut username.

get_full_name()

Renvoie first_name et last_name séparés par une espace.

get_short_name()

Renvoie le prénom (first_name).

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 User 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 User 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_group_permissions(obj=None)

Renvoie l’ensemble des permissions (chaînes) que l’utilisateur obtient au travers des groupes auxquels il 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 la documentation sur les 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.

email_user(subject, message, from_email=None, **kwargs)

Envoie un courriel à l’utilisateur. Si from_email vaut None, Django utilise DEFAULT_FROM_EMAIL. Tout paramètre **kwargs sera transmis à l’appel sous-jacent send_mail().

Méthodes du gestionnaire

class models.UserManager

Le modèle User possède un gestionnaire personnalisé comportant les méthodes utilitaires suivantes (en plus de celles fournies par BaseUserManager) :

create_user(username, email=None, password=None, **extra_fields)

Crée, enregistre et renvoie un objet User.

Les attributs username et password sont définis en fonction des paramètres transmis. La partie domaine de email est automatiquement convertie en minuscules et l’attribut is_active de l’objet User renvoyé sera défini à True.

Si aucun mot de passe n’est indiqué, set_unusable_password() est appelée.

Les paramètres nommés extra_fields sont directement transmis à la méthode __init__ de la classe User, de manière à permettre la définition de champs supplémentaires sans restriction dans un modèle d’utilisateur personnalisé.

Voir Création d’utilisateurs pour un exemple d’utilisation.

create_superuser(username, email, password, **extra_fields)

Identique à create_user(), mais définit is_staff et is_superuser à True.

L’objet AnonymousUser

class models.AnonymousUser

django.contrib.auth.models.AnonymousUser est une classe qui implémente l’interface django.contrib.auth.models.User, avec les différences suivantes :

• id est toujours None.

• username contient toujours la chaîne vide.

• get_username() renvoie toujours la chaîne vide.

• is_anonymous vaut True au lieu de False.

• is_authenticated vaut False au lieu de True.

• is_staff et is_superuser sont toujours False.

• is_active est toujours False.

• groups et user_permissions sont toujours vides.

• set_password(), check_password(), save() et delete() génèrent l’exception NotImplementedError.

En pratique, vous n’aurez probablement jamais besoin d’utiliser directement des objets AnonymousUser vous-même, mais ils sont utilisés dans les requêtes Web, comme expliqué dans la section suivante.

Le modèle Permission

class models.Permission

Champs

Les objets Permission possèdent les champs suivants :

class models.Permission

name

Obligatoire. 255 caractères au maximum. Exemple : 'Can vote'.

content_type

Obligatoire. Une référence à la table de base de données django_content_type, qui contient un enregistrement pour chaque modèle installé.

codename

Obligatoire. 100 caractères au maximum. Exemple : 'can_vote'.

Méthodes

Les objets Permission possèdent les mêmes méthodes d’accès aux données que tout autre modèle Django.

Le modèle Group

class models.Group

Champs

Les objets Group possèdent les champs suivants :

class models.Group

name

Obligatoire. 80 caractères au maximum. Tous les caractères sont autorisés. Exemple : 'Utilisateurs fantastiques'.

permissions

Une relation plusieurs-à-plusieurs vers Permission.

group.permissions.set([permission_list])
group.permissions.add(permission, permission, ...)
group.permissions.remove(permission, permission, ...)
group.permissions.clear()

Validateurs

class validators.ASCIIUsernameValidator

New in Django 1.10.

Un validateur de champ n’autorisant que les caractères ASCII en plus de @, ., +, - et _. Il s’agit du validateur par défaut pour User.username avec Python 2.

class validators.UnicodeUsernameValidator

New in Django 1.10.

Un validateur de champ autorisant les caractères Unicode en plus de @, ., +, - et _. Il s’agit du validateur par défaut pour User.username avec Python 3.

Signaux de connexion et de déconnexion

L’infrastructure d’authentification définit les signaux suivants qui peuvent être utilisés comme notification lorsqu’un utilisateur se connecte ou se déconnecte.

user_logged_in()

Envoyé lorsqu’un utilisateur se connecte avec succès.

Paramètres envoyés avec ce signal :

sender

La classe de l’utilisateur qui vient de se connecter.

request

L’instance HttpRequest actuelle.

user

L’instance utilisateur qui vient de se connecter.

user_logged_out()

Envoyé lorsque la méthode logout est appelée.

sender

Comme ci-dessus : la classe de l’utilisateur qui vient de se déconnecter ou None si l’utilisateur n’était pas authentifié.

request

L’instance HttpRequest actuelle.

user

L’instance de l’utilisateur qui vient de se déconnecter ou None si l’utilisateur n’était pas authentifié.

user_login_failed()

Envoyé lorsque le processus de connexion d’un utilisateur a échoué.

sender

Le nom du module utilisé pour l’authentification.

credentials

Un dictionnaire de paramètres nommés contenant les données d’authentification qui ont été transmises à authenticate() ou à votre propre moteur d’authentification. Les données d’authentification correspondant à certains motifs « sensibles » (par ex. « password ») ne sont pas transmis en clair dans les paramètres du signal.

Moteurs d’authentification

Cette section présente les moteurs d’authentification livrés avec Django. Pour de plus amples informations sur la manière de les utiliser et sur l’écriture de vos propres moteurs d’authentification, consultez la section Autres sources d’authentification du Guide d’authentification des utilisateurs.

Moteurs d’authentification disponibles

Les moteurs suivants sont disponibles dans django.contrib.auth.backends:

class ModelBackend

Il s’agit du moteur d’authentification utilisé par défaut par Django. Il effectue l’authentification sur la base de l’identifiant d’un utilisateur et de son mot de passe. Pour le modèle d’utilisateur par défaut de Django, l’identifiant de l’utilisateur est le nom d’utilisateur (username), pour les modèles d’utilisateur personnalisés, c’est le champ contenu dans USERNAME_FIELD (voir Personnalisation des utilisateurs et de l’authentification).

Il gère également le modèle de permissions par défaut tel que défini pour User et PermissionsMixin.

has_perm(), get_all_permissions(), get_user_permissions() et get_group_permissions() acceptent en paramètre un objet pour des permissions spécifiques à cet objet, mais ce moteur n’implémente pas cette possibilité à part le renvoi d’un ensemble vide de permissions si

authenticate(username=None, password=None, **kwargs)

Essaie d’authentifier username avec password en appelant User.check_password. Si aucun username n’est fourni, elle essaie d’obtenir un nom d’utilisateur à partir de kwargs avec la clé CustomUser.USERNAME_FIELD. Renvoie soit un utilisateur authentifié, soit None.

get_user_permissions(user_obj, obj=None)

Renvoie l’ensemble des chaînes de permissions dont user_obj bénéficie à partir de ses propres permissions d’utilisateur. Renvoie un ensemble vide si is_anonymous ou si is_active vaut False.

get_group_permissions(user_obj, obj=None)

Renvoie l’ensemble des chaînes de permissions dont user_obj bénéficie à partir des permissions des groupes auxquels il appartient. Renvoie un ensemble vide si is_anonymous ou si is_active vaut False.

get_all_permissions(user_obj, obj=None)

Renvoie l’ensemble des chaînes de permissions dont user_obj bénéficie, que ce soit en son nom propre ou au travers des groupes auxquels il appartient. Renvoie un ensemble vide si is_anonymous ou si is_active vaut False.

has_perm(user_obj, perm, obj=None)

Utilise get_all_permissions() pour vérifier si user_obj possède la chaîne de permission perm. Renvoie False si l’utilisateur n’est pas is_active.

has_module_perms(self, user_obj, app_label)

Indique si user_obj possède au moins une permission pour l’application app_label.

user_can_authenticate()

New in Django 1.10.

Indique si l’utilisateur est autorisé à s’authentifier. Pour correspondre au comportement de AuthenticationForm qui interdit aux utilisateurs inactifs de se connecter, cette méthode renvoie False pour les utilisateurs ayant is_active=False. Les modèles d’utilisateurs personnalisés n’ayant pas de champ is_active sont autorisés.

class AllowAllUsersModelBackend

New in Django 1.10.

Identique à ModelBackend sauf qu’il ne rejette pas les utilisateurs inactifs parce que user_can_authenticate() renvoie toujours True.

Lorsque ce moteur est utilisé, il vaut probablement mieux adapter le formulaire AuthenticationForm utilisé par la vue login() en surchargeant la méthode confirm_login_allowed() car celle-ci rejette les utilisateurs inactifs.

class RemoteUserBackend

Utilisez ce moteur pour profiter de processus d’authentification externes à Django. Le processus d’authentification utilise les noms d’utilisateur se trouvant dans request.META['REMOTE_USER']. Consultez la documentation sur l’authentification par REMOTE_USER.

Pour plus de flexibilité, vous pouvez créer votre propre moteur d’authentification héritant de cette classe et surcharger ces attributs ou méthodes :

RemoteUserBackend.create_unknown_user

True ou False. Détermine si un objet utilisateur est créé ou pas s’il n’est pas trouvé dans la base de données. La valeur par défaut est True.

RemoteUserBackend.authenticate(remote_user)

Le nom d’utilisateur transmis à remote_user est considéré comme sûr. Cette méthode renvoie simplement l’objet utilisateur ayant le nom d’utilisateur indiqué, créant un nouvel utilisateur si create_unknown_user vaut True.

Renvoie None si create_unknown_user vaut False et un objet User ayant le nom d’utilisateur indiqué si ce dernier n’existe pas encore dans la base de données.

RemoteUserBackend.clean_username(username)

Procède au nettoyage de username (par ex. raccourcissement de l’information DN de LDAP) avant de l’utiliser pour obtenir ou créer un objet utilisateur. Renvoie le nom d’utilisateur nettoyé.

RemoteUserBackend.configure_user(user)

Configure un nouvel utilisateur. Cette méthode est appelée immédiatement après la création d’un nouvel utilisateur et peut être utilisée pour effectuer des actions de configuration personnalisées, comme l’attribution de groupes d’utilisateurs en fonction d’attributs d’un répertoire LDAP. Renvoie l’objet utilisateur.

RemoteUserBackend.user_can_authenticate()

New in Django 1.10.

Indique si l’utilisateur est autorisé à s’authentifier. Cette méthode renvoie False pour les utilisateurs ayant is_active=False. Les modèles d’utilisateurs personnalisés n’ayant pas de champ is_active sont autorisés.

class AllowAllUsersRemoteUserBackend

New in Django 1.10.

Identique à RemoteUserBackend sauf qu’il ne rejette pas les utilisateurs inactifs parce que user_can_authenticate() renvoie toujours True.

Fonctions utilitaires

get_user(request)[source]

Renvoie l’instance de modèle utilisateur associée à la session de la requête request donnée.

Elle contrôle si le moteur d’authentification stocké dans la session est présent dans AUTHENTICATION_BACKENDS. Si oui, elle utilise la méthode get_user() du moteur pour récupérer l’instance de modèle utilisateur puis vérifie la session en appelant la méthode get_session_auth_hash() du modèle utilisateur.

Renvoie une instance de AnonymousUser si le moteur d’authentification stocké dans la session n’est plus dans AUTHENTICATION_BACKENDS, si un utilisateur n’est pas renvoyé par la méthode get_user() du moteur ou si l’empreinte d’authentification de la session n’est pas valide.