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
¶
-
class
models.
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 codageutf8mb4
(recommandé pour une prise en charge intégrale d’Unicode), indiquez au maximummax_length=191
parce que MySQL ne peut créer d’index unique que jusqu’à une longueur de 191 caractères dans ce cas.
-
first_name
¶ Facultatif (
blank=True
). 150 caractères ou moins.Changed in Django 3.1:La longueur maximale
max_length
a passé de 30 à 150 caractères.
-
last_name
¶ Facultatif (
blank=True
). 150 caractères ou moins.
-
email
¶ Facultatif (
blank=True
). 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.
-
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 moteurRemoteUserBackend
le font. Vous pouvez utiliserAllowAllUsersModelBackend
ouAllowAllUsersRemoteUserBackend
si vous voulez autoriser les utilisateurs inactifs à se connecter. Dans ce cas, vous devrez aussi adapter le formulaireAuthenticationForm
utilisé par la vueLoginView
car il rejette les utilisateurs inactifs. Soyez conscient que les méthodes de contrôle des permissions telles quehas_perm()
ainsi que l’authentification dans le site d’administration de Django renvoient toutesFalse
pour les utilisateurs inactifs.
-
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 toujoursFalse
). 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 drapeauis_active
de l’utilisateur ou sur la validité de la session. Même si cet attribut est généralement consulté pourrequest.user
afin de déterminer s’il a été défini parAuthenticationMiddleware
(représentant l’utilisateur actuellement connecté), vous devez savoir que cet attribut vautTrue
pour toute instance deUser
.
-
is_anonymous
¶ Attribut en lecture seule qui vaut toujours
False
. C’est une façon de différencier les objetsUser
des objetsAnonymousUser
. Généralement, il vaut mieux utiliseris_authenticated
que cet attribut.
-
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’attributusername
.
-
get_full_name
()¶ Renvoie
first_name
etlast_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
vautNone
, 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 jamaisTrue
pour cet utilisateur. L’objetUser
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
siset_unusable_password()
a été appelée pour cet utilisateur.
-
get_user_permissions
(obj=None)¶ 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.
-
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 toujoursFalse
. Pour un superutilisateur actif, cette méthode renvoie toujoursTrue
.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 toujoursFalse
. Pour un superutilisateur actif, cette méthode renvoie toujoursTrue
.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 toujoursFalse
. Pour un superutilisateur actif, cette méthode renvoie toujoursTrue
.
-
email_user
(subject, message, from_email=None, **kwargs)¶ Envoie un courriel à l’utilisateur. Si
from_email
vautNone
, Django utiliseDEFAULT_FROM_EMAIL
. Tout paramètre**kwargs
sera transmis à l’appel sous-jacentsend_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 parBaseUserManager
) :-
create_user
(username, email=None, password=None, **extra_fields)¶ Crée, enregistre et renvoie un objet
User
.Les attributs
username
etpassword
sont définis en fonction des paramètres transmis. La partie domaine deemail
est automatiquement convertie en minuscules et l’attributis_active
de l’objetUser
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 classeUser
, 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=None, password=None, **extra_fields)¶ Identique à
create_user()
, mais définitis_staff
etis_superuser
àTrue
.
-
with_perm
(perm, is_active=True, include_superusers=True, backend=None, obj=None)¶ Renvoie les utilisateurs ayant la permission
perm
donnée soit dans le format"<nom_app>.<code_de_permission>"
, soit comme instance dePermission
. Un jeu de requête vide est renvoyé si aucun utilisateur ne possède la permissionperm
.Si
is_active
vautTrue
(par défaut), ne renvoie que des utilisateurs actifs. Avec la valeurFalse
, ne renvoie que des utilisateurs inactifs. IndiquezNone
pour ne pas tenir compte de l’état actif des utilisateurs dans la recherche.Si
include_superusers
vautTrue
(par défaut), le résultat contiendra aussi les superutilisateurs.Si
backend
est transmis et qu’il est défini dansAUTHENTICATION_BACKENDS
, alors cette méthode va l’utiliser. Sinon, elle utilisera la valeurbackend
dansAUTHENTICATION_BACKENDS
, s’il y en a qu’une, ou générer une exception.
-
L’objet AnonymousUser
¶
-
class
models.
AnonymousUser
¶ django.contrib.auth.models.AnonymousUser
est une classe qui implémente l’interfacedjango.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
vautTrue
au lieu deFalse
.is_authenticated
vautFalse
au lieu deTrue
.is_staff
etis_superuser
sont toujoursFalse
.is_active
est toujoursFalse
.groups
etuser_permissions
sont toujours vides.set_password()
,check_password()
,save()
etdelete()
génèrent l’exceptionNotImplementedError
.
- id est toujours
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. 150 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
¶ Un validateur de champ n’autorisant que les caractères ASCII en plus de
@
,.
,+
,-
et_
.
-
class
validators.
UnicodeUsernameValidator
¶ Un validateur de champ autorisant les caractères Unicode en plus de
@
,.
,+
,-
et_
. Il s’agit du validateur par défaut pourUser.username
.
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. request
- L’objet
HttpRequest
pour autant qu’il ait été fourni àauthenticate()
.
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
BaseBackend
¶ 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.
-
get_user_permissions
(user_obj, obj=None)¶ Renvoie un ensemble vide.
-
get_group_permissions
(user_obj, obj=None)¶ Renvoie un ensemble vide.
-
get_all_permissions
(user_obj, obj=None)¶ Utilise
get_user_permissions()
etget_group_permissions()
pour obtenir l’ensemble des chaînes de permission dont disposeuser_obj
.
-
has_perm
(user_obj, perm, obj=None)¶ Utilise
get_all_permissions()
pour vérifier siuser_obj
possède la chaîne de permissionperm
.
-
-
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 dansUSERNAME_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
etPermissionsMixin
.has_perm()
,get_all_permissions()
,get_user_permissions()
etget_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 siwith_perm()
peut aussi recevoir un objet en paramètre, mais au contraire des autres méthodes, elle renvoie un jeu de requête vide siobj is not None
.-
authenticate
(request, username=None, password=None, **kwargs)¶ Essaie d’authentifier
username
avecpassword
en appelantUser.check_password
. Si aucunusername
n’est fourni, elle essaie d’obtenir un nom d’utilisateur à partir dekwargs
avec la cléCustomUser.USERNAME_FIELD
. Renvoie soit un utilisateur authentifié, soitNone
.request
est un objetHttpRequest
et peut valoirNone
s’il n’a pas été fourni àauthenticate()
(laquelle le transmet au moteur d’authentification).
-
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 siis_anonymous
ou siis_active
vautFalse
.
-
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 siis_anonymous
ou siis_active
vautFalse
.
-
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 siis_anonymous
ou siis_active
vautFalse
.
-
has_perm
(user_obj, perm, obj=None)¶ Utilise
get_all_permissions()
pour vérifier siuser_obj
possède la chaîne de permissionperm
. RenvoieFalse
si l’utilisateur n’est pasis_active
.
-
has_module_perms
(user_obj, app_label)¶ Indique si
user_obj
possède au moins une permission pour l’applicationapp_label
.
-
user_can_authenticate
()¶ Indique si l’utilisateur est autorisé à s’authentifier. Pour correspondre au comportement de
AuthenticationForm
quiinterdit aux utilisateurs inactifs de se connecter
, cette méthode renvoieFalse
pour les utilisateurs ayantis_active=False
. Les modèles d’utilisateurs personnalisés n’ayant pas de champis_active
sont autorisés.
-
with_perm
(perm, is_active=True, include_superusers=True, obj=None)¶ Renvoie tous les utilisateurs actifs ayant la permission
perm
soit sous la forme"<nom_app>.<code_de_permission>"
, soit comme instance dePermission
. Un jeu de requête vide est renvoyé si aucun utilisateur ne possède la permissionperm
.Si
is_active
vautTrue
(par défaut), ne renvoie que des utilisateurs actifs. Avec la valeurFalse
, ne renvoie que des utilisateurs inactifs. IndiquezNone
pour ne pas tenir compte de l’état actif des utilisateurs dans la recherche.Si
include_superusers
vautTrue
(par défaut), le résultat contiendra aussi les superutilisateurs.
-
-
class
AllowAllUsersModelBackend
¶ Identique à
ModelBackend
sauf qu’il ne rejette pas les utilisateurs inactifs parce queuser_can_authenticate()
renvoie toujoursTrue
.Lorsque ce moteur est utilisé, il vaut probablement mieux adapter le formulaire
AuthenticationForm
utilisé par la vueLoginView
en surchargeant la méthodeconfirm_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 :
-
create_unknown_user
¶ True
ouFalse
. 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 estTrue
.
-
authenticate
(request, remote_user)¶ 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 sicreate_unknown_user
vautTrue
.Renvoie
None
sicreate_unknown_user
vautFalse
et un objetUser
ayant le nom d’utilisateur indiqué si ce dernier n’existe pas encore dans la base de données.request
est un objetHttpRequest
et peut valoirNone
s’il n’a pas été fourni àauthenticate()
(laquelle le transmet au moteur d’authentification).
-
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é.
-
configure_user
(request, 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.
request
est un objetHttpRequest
et peut valoirNone
s’il n’a pas été fourni àauthenticate()
(laquelle le transmet au moteur d’authentification).
-
user_can_authenticate
()¶ Indique si l’utilisateur est autorisé à s’authentifier. Cette méthode renvoie
False
pour les utilisateurs ayantis_active=False
. Les modèles d’utilisateurs personnalisés n’ayant pas de champis_active
sont autorisés.
-
-
class
AllowAllUsersRemoteUserBackend
¶ Identique à
RemoteUserBackend
sauf qu’il ne rejette pas les utilisateurs inactifs parce queuser_can_authenticate
renvoie toujoursTrue
.
Fonctions utilitaires¶
-
get_user
(request)¶ 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éthodeget_user()
du moteur pour récupérer l’instance de modèle utilisateur puis vérifie la session en appelant la méthodeget_session_auth_hash()
du modèle utilisateur.Renvoie une instance de
AnonymousUser
si le moteur d’authentification stocké dans la session n’est plus dansAUTHENTICATION_BACKENDS
, si un utilisateur n’est pas renvoyé par la méthodeget_user()
du moteur ou si l’empreinte d’authentification de la session n’est pas valide.