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.
User
¶Les objets User
possèdent les champs suivants :
Obligatoire. Au maximum 150 caractères. Les noms d’utilisateur peuvent contenir des caractères alphanumériques (_
, @
, +
, .
et -
).
The max_length
should be sufficient for many use cases. If you need
a longer length, please use a custom user model.
Facultatif (blank=True
). 150 caractères ou moins.
Facultatif (blank=True
). 150 caractères ou moins.
Facultatif (blank=True
). Adresse électronique.
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. Les métadonnées de ce champ peuvent aussi marquer le mot de passe comme inutilisable. Voir la documentation sur les mots de passe.
Une relation plusieurs-à-plusieurs vers Permission
.
Valeur booléenne. Permet à cet utilisateur d’accéder au site d’administration.
Valeur booléenne. Marque ce compte utilisateur 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 LoginView
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.
Valeur booléenne. Considère cet utilisateur comme ayant toutes les permissions sans devoir lui en attribuer aucune en particulier.
Horodatage de la dernière connexion de l’utilisateur.
L’horodatage de la création du compte.
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
.
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.
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
.
Renvoie first_name
et last_name
séparés par une espace.
Renvoie le prénom (first_name
).
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()
.
Version asynchrone: acheck_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).
Marque l’utilisateur comme n’ayant pas de mot de passe défini en mettant à jour les métadonnées dans le champ password
. 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.
Restriction sur la réinitialisation du mot de passe
Les utilisateurs ayant un mot de passe inutilisable ne pourront pas demander une réinitialisation du mot de passe par courriel via PasswordResetView
.
Renvoie False
si set_unusable_password()
a été appelée pour cet utilisateur.
Asynchronous version: aget_user_permissions()
Renvoie l’ensemble des permissions (chaînes) que l’utilisateur obtient directement.
Si obj
est transmis, ne renvoie que les permissions d’utilisateur liées à cet objet spécifique.
aget_user_permissions()
method was added.
Asynchronous version: aget_group_permissions()
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.
aget_group_permissions()
method was added.
Asynchronous version: aget_all_permissions()
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.
aget_all_permissions()
method was added.
Asynchronous version: ahas_perm()
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
. Pour un superutilisateur actif, cette méthode renvoie toujours True
.
Si obj
est transmis, cette méthode ne contrôle pas la permission au niveau du modèle, mais pour l’objet indiqué.
ahas_perm()
method was added.
Asynchronous version: ahas_perms()
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
. Pour un superutilisateur actif, cette méthode renvoie toujours True
.
Si obj
est transmis, cette méthode ne contrôle pas les permissions au niveau du modèle, mais pour l’objet indiqué.
ahas_perms()
method was added.
Asynchronous version: ahas_module_perms()
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
. Pour un superutilisateur actif, cette méthode renvoie toujours True
.
ahas_module_perms()
method was added.
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()
.
Le modèle User
possède un gestionnaire personnalisé comportant les méthodes utilitaires suivantes (en plus de celles fournies par BaseUserManager
) :
Asynchronous version: acreate_user()
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.
Si aucune adresse de courriel n’est indiquée, email
sera défini à une chaîne vide.
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.
acreate_user()
method was added.
Asynchronous version: acreate_superuser()
Identique à create_user()
, mais définit is_staff
et is_superuser
à True
.
acreate_superuser()
method was added.
Renvoie les utilisateurs ayant la permission perm
donnée soit dans le format "<nom_app>.<code_de_permission>"
, soit comme instance de Permission
. Un jeu de requête vide est renvoyé si aucun utilisateur ne possède la permission perm
.
Si is_active
vaut True
(par défaut), ne renvoie que des utilisateurs actifs. Avec la valeur False
, ne renvoie que des utilisateurs inactifs. Indiquez None
pour ne pas tenir compte de l’état actif des utilisateurs dans la recherche.
Si include_superusers
vaut True
(par défaut), le résultat contiendra aussi les superutilisateurs.
Si backend
est transmis et qu’il est défini dans AUTHENTICATION_BACKENDS
, alors cette méthode va l’utiliser. Sinon, elle utilisera la valeur backend
dans AUTHENTICATION_BACKENDS
, s’il y en a qu’une, ou générer une exception.
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.
Permission
¶Les objets Permission
possèdent les champs suivants :
Obligatoire. 255 caractères au maximum. Exemple : 'Can vote'
.
Required. A foreign key to the
ContentType
model.
Obligatoire. 100 caractères au maximum. Exemple : 'can_vote'
.
Les objets Permission
possèdent les mêmes méthodes d’accès aux données que tout autre modèle Django.
Group
¶Les objets Group
possèdent les champs suivants :
Obligatoire. 150 caractères au maximum. Tous les caractères sont autorisés. Exemple : 'Utilisateurs fantastiques'
.
Une relation plusieurs-à-plusieurs vers Permission
.
group.permissions.set([permission_list])
group.permissions.add(permission, permission, ...)
group.permissions.remove(permission, permission, ...)
group.permissions.clear()
Un validateur de champ n’autorisant que les caractères ASCII en plus de @
, .
, +
, -
et _
.
Un validateur de champ autorisant les caractères Unicode en plus de @
, .
, +
, -
et _
. Il s’agit du validateur par défaut pour User.username
.
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.
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.
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é.
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.
request
L’objet HttpRequest
pour autant qu’il ait été fourni à authenticate()
.
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.
Les moteurs suivants sont disponibles dans django.contrib.auth.backends
:
Une classe de base fournissant des implémentations par défaut pour toutes les méthodes obligatoires. Par défaut, elle rejette tout utilisateur et ne fournit aucune permission.
Asynchronous version: aget_user_permissions()
Renvoie un ensemble vide.
aget_user_permissions()
function was added.
Asynchronous version: aget_group_permissions()
Renvoie un ensemble vide.
aget_group_permissions()
function was added.
Asynchronous version: aget_all_permissions()
Utilise get_user_permissions()
et get_group_permissions()
pour obtenir l’ensemble des chaînes de permission dont dispose user_obj
.
aget_all_permissions()
function was added.
Asynchronous version: ahas_perm()
Utilise get_all_permissions()
pour vérifier si user_obj
possède la chaîne de permission perm
.
ahas_perm()
function was added.
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
with_perm()
peut aussi recevoir un objet en paramètre, mais au contraire des autres méthodes, elle renvoie un jeu de requête vide si obj is not None
.
Asynchronous version: aauthenticate()
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
.
request
est un objet HttpRequest
et peut valoir None
s’il n’a pas été fourni à authenticate()
(laquelle le transmet au moteur d’authentification).
aauthenticate()
function was added.
Asynchronous version: aget_user_permissions()
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
.
aget_user_permissions()
function was added.
Asynchronous version: aget_group_permissions()
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
.
aget_group_permissions()
function was added.
Asynchronous version: aget_all_permissions()
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
.
aget_all_permissions()
function was added.
Asynchronous version: ahas_perm()
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
.
ahas_perm()
function was added.
Asynchronous version: ahas_module_perms()
Indique si user_obj
possède au moins une permission pour l’application app_label
.
ahas_module_perms()
function was added.
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.
Renvoie tous les utilisateurs actifs ayant la permission perm
soit sous la forme "<nom_app>.<code_de_permission>"
, soit comme instance de Permission
. Un jeu de requête vide est renvoyé si aucun utilisateur ne possède la permission perm
.
Si is_active
vaut True
(par défaut), ne renvoie que des utilisateurs actifs. Avec la valeur False
, ne renvoie que des utilisateurs inactifs. Indiquez None
pour ne pas tenir compte de l’état actif des utilisateurs dans la recherche.
Si include_superusers
vaut True
(par défaut), le résultat contiendra aussi les superutilisateurs.
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 LoginView
en surchargeant la méthode confirm_login_allowed()
car celle-ci rejette les utilisateurs inactifs.
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 :
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
.
Asynchronous version: aauthenticate()
Le nom d’utilisateur transmis à remote_user
est considéré comme sûr. Cette méthode renvoie 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.
request
est un objet HttpRequest
et peut valoir None
s’il n’a pas été fourni à authenticate()
(laquelle le transmet au moteur d’authentification).
aauthenticate()
function was added.
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é.
Asynchronous version: aconfigure_user()
Configures the user on each authentication attempt. This method is
called immediately after fetching or creating the user being
authenticated, and can be used to perform custom setup actions, such as
setting the user’s groups based on attributes in an LDAP directory.
Returns the user object. When fetching or creating an user is called
from a synchronous context, configure_user
is called,
aconfigure_user
is called from async contexts.
La configuration peut être effectuée soit une fois lorsque l’utilisateur est créé (created
vaut True
), soit sur les utilisateurs existants (created
vaut False
) comme une manière de synchroniser les attributs entre les systèmes distants et locaux.
request
est un objet HttpRequest
et peut valoir None
s’il n’a pas été fourni à authenticate()
(laquelle le transmet au moteur d’authentification).
aconfigure_user()
function was added.
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.
Identique à RemoteUserBackend
sauf qu’il ne rejette pas les utilisateurs inactifs parce que user_can_authenticate
renvoie toujours True
.
Version asynchrone : aget_user()
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. Si la vérification échoue et que SECRET_KEY_FALLBACKS
est défini, elle vérifie la session en fonction de chaque clé mentionnée en utilisant get_session_auth_fallback_hash()
.
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.
avr. 05, 2025