# Documentation Django 6.0.7

# `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 pour la plupart des cas. Si vous avez besoin d’une plus grande longueur, utilisez un modèle utilisateur personnalisé.

  first_name

    Facultatif (`blank=True`). 150 caractères ou moins.

  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. Les métadonnées de ce champ peuvent aussi marquer le mot de passe comme inutilisable. 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. Permet à cet utilisateur d’accéder au site d’administration.

  is_active

    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.

  is_superuser

    Valeur booléenne. Considère cet utilisateur comme ayant toutes les permissions sans devoir lui en attribuer aucune en particulier.

  last_login

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

  date_joined

    L’horodatage de la création du compte.

### 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`.

  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.

### 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)
  acheck_password(raw_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).

  set_unusable_password()

    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`.

  has_usable_password()

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

  get_user_permissions(obj=None)
  aget_user_permissions(obj=None)

    Version asynchrone : `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.

  get_group_permissions(obj=None)
  aget_group_permissions(obj=None)

    Version asynchrone : `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.

  get_all_permissions(obj=None)
  aget_all_permissions(obj=None)

    Version asynchrone : `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.

  has_perm(perm, obj=None)
  ahas_perm(perm, obj=None)

    Version asynchrone: `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é.

  has_perms(perm_list, obj=None)
  ahas_perms(perm_list, obj=None)

    Version asynchrone: `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é.

  has_module_perms(package_name)
  ahas_module_perms(package_name)

    Version asynchrone: `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`.

  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)
  acreate_user(username, email=None, password=None, **extra_fields)

    Version asynchrone : `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.

  create_superuser(username, email=None, password=None, **extra_fields)
  acreate_superuser(username, email=None, password=None, **extra_fields)

    Version asynchrone : `acreate_superuser()`

    Identique à `create_user()`, mais définit `is_staff` et `is_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 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.

## 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 clé étrangère vers le modèle `ContentType`.

  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.

class models.Permission
  user_perm_str
    New in Django 6.1.

    Returns the string representation for use in `has_perm`.

## 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 pour `User.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)
  aget_user_permissions(user_obj, obj=None)

    Version asynchrone : `aget_user_permissions()`

    Renvoie un ensemble vide.

  get_group_permissions(user_obj, obj=None)
  aget_group_permissions(user_obj, obj=None)

    Version asynchrone : `aget_group_permissions()`

    Renvoie un ensemble vide.

  get_all_permissions(user_obj, obj=None)
  aget_all_permissions(user_obj, obj=None)

    Version asynchrone : `aget_all_permissions()`

    Utilise `get_user_permissions()` et `get_group_permissions()` pour obtenir l’ensemble des chaînes de permission dont dispose `user_obj`.

  has_perm(user_obj, perm, obj=None)
  ahas_perm(user_obj, perm, obj=None)

    Version asynchrone: `ahas_perm()`

    Utilise `get_all_permissions()` pour vérifier si `user_obj` possède la chaîne de permission `perm`.

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

  `with_perm()` also allows an object to be passed as a parameter, but unlike other methods it returns an empty queryset if `obj is not None`.

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

    Version asynchrone: `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).

  get_user_permissions(user_obj, obj=None)
  aget_user_permissions(user_obj, obj=None)

    Version asynchrone : `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`.

  get_group_permissions(user_obj, obj=None)
  aget_group_permissions(user_obj, obj=None)

    Version asynchrone : `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`.

  get_all_permissions(user_obj, obj=None)
  aget_all_permissions(user_obj, obj=None)

    Version asynchrone : `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`.

  has_perm(user_obj, perm, obj=None)
  ahas_perm(user_obj, perm, obj=None)

    Version asynchrone: `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`.

  has_module_perms(user_obj, app_label)
  ahas_module_perms(user_obj, app_label)

    Version asynchrone: `ahas_module_perms()`

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

  user_can_authenticate()

    Returns whether the user is allowed to authenticate. To match the behavior of `AuthenticationForm.confirm_login_allowed()`, this method returns `False` for users with `is_active=False`. Custom user models that don’t have an `is_active` field are allowed.

  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 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.

class AllowAllUsersModelBackend

  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.

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` 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`.

  authenticate(request, remote_user)
  aauthenticate(request, remote_user)

    Version asynchrone: `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).

  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, created=True)
  aconfigure_user(request, user, created=True)

    Version asynchrone : `aconfigure_user()`

    Configure l’utilisateur lors de chaque tentative d’authentification. Cette méthode est appelée immédiatement après la création ou l’obtention de l’utilisateur en cours d’authentification et elle 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. Lorsque l’obtention ou la création d’un utilisateur est appelée à partir d’un contexte synchrone, `configure_user` est appelée, et dans le cas d’un contexte asynchrone, c’est `aconfigure_user` qui sera appelée.

    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).

  user_can_authenticate()

    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

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

## Fonctions utilitaires

get_user(request)

aget_user(request)

  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.