Référence de l'API

myuser.groups = [group_list]
myuser.groups.add(group, group, ...)
myuser.groups.remove(group, group, ...)
myuser.groups.clear()
myuser.user_permissions = [permission_list]
myuser.user_permissions.add(permission, permission, ...)
myuser.user_permissions.remove(permission, permission, ...r)
myuser.user_permissions.clear()

Utilisation de base

>>> from django.contrib.auth.models import User
>>> user = User.objects.create_user('john', 'lennon@thebeatles.com', 'johnpassword')

# user est maintenant un objet User déjà sauvegardé
# dans la base de données. Vous pouvez continuer à changer ses
# attributs si vous voulez changer la valeur d'autres champs.
>>> user.is_staff = True
>>> user.save()

>>> from django.contrib.auth.models import User
>>> u = User.objects.get(username__exact='john')
>>> u.set_password('new password')
>>> u.save()

Mots de passe

L'attribut password d'un objet User est une chaîne au format:

hashtype$salt$hash

C'est-à-dire le type de chiffrement (hashtype), la graine (salt) et le mot de passé chiffré (hash), séparés par des dollars.

Le type de chiffrement est sha1 (par défaut), md5 ou crypt -- l'algorithme utilisé pour faire le chiffrage à sens unique du mot de passe. La graine est une chaîne aléatoire utilisée dans la création du mot de passe chiffré. Notez que la méthode crypt n'est supportée que sur les plateformes sur lesquelles le module Python crypt est disponible, et le support de crypt n'existe que dans la version de développement de Django.

Exemple:

sha1$a1976$a36cc8cbf81742a8fb52e221aaeab48ed7f58ab4

Les fonctions User.set_password() et User.check_password() gèrent la mise en place et la vérification de ces valeurs pour vous.

Certaines versions antérieures de Django, comme la 0.90, utilisaient de simples chiffres MD5 sans utiliser de graine (salt). Pour assurer la compatibilité ascendante, ils sont toujours supportés mais seront automatiquement convertis en chiffres utilisant la nouvelle méthode la première fois que User.check_password() fonctionnera correctement pour un utilisateur donné.

Utilisateurs anonymes

La classe django.contrib.auth.models.AnonymousUser implémente l'interface django.contrib.auth.models.User, mais avec ces différences :

• id vaut toujours None.

  • is_staff et is_superuser sont toujours False.
  • is_active est toujours False.
  • groups et user_permissions sont toujours vides.

• is_anonymous() renvoie True au lieu de False.

• is_authenticated() renvoie False au lieu de True.

• has_perm() renvoie toujours False.

• set_password(), check_password(), save(), delete(), set_groups() et set_permissions() lèvent l'exception NotImplementedError.

En pratique, vous n'aurez probablement pas à utiliser les objets AnonymousUser directement, mais ils sont utilisés par les requêtes web, comme il est expliqué dans la section suivante.

Création de superutilisateurs

manage.py syncdb vous propose de créer un superutilisateur la première fois que vous l'utilisez après avoir ajouté 'django.contrib.auth' à vos INSTALLED_APPS. Mais si vous avez besoin de créer un superutilisateur après cela, vous pouvez utiliser un utilitaire en ligne de commande.

Nouveau dans la version de développement de Django:

manage.py createsuperuser --username=joe --email=joe@example.com

Il vous sera demandé un mot de passe. Après que vous en ayez fourni un, l'utilisateur sera créé immédiatement. Si vous n'utilisez pas les options --username et --email, ces valeurs vous seront demandées.

Si vous utilisez toujours une version plus ancienne de Django, la façon traditionnelle de créer un superutilisateur en ligne de commande fonctionne toujours:

python /path/to/django/contrib/auth/create_superuser.py

...où /path/to est le chemin de la base de code de Django sur votre système de fichiers. La commande manage.py est préférable parce qu'elle détermine les chemins et l'environnement corrects pour vous.

Ajout d'informations supplémentaires sur les utilisateurs

Si vous souhaitez stocker des informations supplémentaires a propos de vos utilisateurs, Django fournit une technique pour spécifier un modèle propre à votre site, en relation avec le modèle User, à cet effet. Ces modèles sont appelés "profils utilisateurs".

Pour utiliser cette fonctionnalité, définissez un modèle contenant les champs nécessaires pour les informations supplémentaires que vous souhaitez conserver, ainsi que les méthodes additionnelles dont vous voulez disposer. Ajoutez également une ForeignKey de votre modèle vers le modèle User, en spécifiant unique=True pour être certain qu'il n'y aura qu'une seule instance de votre modèle pour chaque User.

Pour indiquer que ce modèle est le profil utilisateur pour un site donné, renseignez la variable de réglage AUTH_PROFILE_MODULE avec une chaîne formée des éléments suivant, séparés par des points :

1. Le nom de l'application (en minuscules) dans laquelle le modèle de profil utilisateur est défini (en d'autres termes, une version tout en minuscule du nom qui a été passé à manage.py startapp pour créer l'application).
2. Le nom de la classe du modèle, en minuscules également.

Par exemple, si le modèle de profil est une classe appelée UserProfile et est défini dans une application appelée comptes, la variable appropriée dans votre fichier de réglages serait:

AUTH_PROFILE_MODULE = 'comptes.userprofile'

Quand un profil utilisateur a été défini et spécifié de cette façon, chaque objet User aura une méthode -- get_profile() -- qui renverra l'instance du modèle de profil utilisateur associée à ce User.

Pour plus d'informations, voir le chapitre 12 du livre de Django.

Comment authentifier un utilisateur

Django fournit deux fonctions dans django.contrib.auth : authenticate() et login().

Pour authentifier un couple utilisateur-mot de passe donné, utilisez authenticate(). La fonction prend deux arguments, username et password, et renvoie un objet User si le mot de passe est valide pour l'utilisateur donné. Si le mot de passe est invalide, authenticate() renvoie None. Exemple:

from django.contrib.auth import authenticate
user = authenticate(username='john', password='secret')
if user is not None:
    if user.is_active:
        print "You provided a correct username and password!"
    else:
        print "Your account has been disabled!"
else:
    print "Your username and password were incorrect."

Pour authentifier un utilisateur dans une vue, utilisez login(). Cette fonction prend un objet HttpRequest et un objet User. login() sauve l'ID de l'utilisateur dans la session courante en utilisant la gestion des sessions de Django, donc, il faut que le module intermédiaire de gestion des sessions soit installé comme indiqué ci-dessus.

Cet exemple montre comment utiliser authenticate() et login() pour authentifier un utilisateur:

from django.contrib.auth import authenticate, login

def my_view(request):
    username = request.POST['username']
    password = request.POST['password']
    user = authenticate(username=username, password=password)
    if user is not None:
        if user.is_active:
            login(request, user)
            # Redirection vers une page de succès.
        else:
            # Renvoyer un message d'erreur 'compte inactif'.
    else:
        # Renvoyer un message d'erreur 'login invalide'.

Vérification manuelle du mot de passe d'un utilisateur

Si vous souhaitez authentifier manuellement un utilisateur en comparant un mot de passe clair à la version chiffrée stockée dans la base de données, utilisez la fonction django.contrib.auth.models.check_password. Elle prend deux arguments : le mot de passe en clair à vérifier, et la valeur du champ password de l'utilisateur concerné dans la base de données, et renvoie True s'ils correspondent, False sinon.

Comment déconnecter un utilisateur

Pour déconnecter un utilisateur qui a été authentifié via django.contrib.auth.login(), utilisez django.contrib.auth.logout() dans votre vue. Cette fonction prend un objet HttpRequest et n'a pas de valeur de retour. Exemple:

from django.contrib.auth import logout

def logout_view(request):
    logout(request)
    # Redirection vers une autre page.

Notez que logout() ne renvoie aucune erreur si l'utilisateur n'était pas authentifié.

Limiter l'accès aux utilisateurs authentifiés

from django.http import HttpResponseRedirect

def my_view(request):
    if not request.user.is_authenticated():
        return HttpResponseRedirect('/login/?next=%s' % request.path)
    # ...

def my_view(request):
    if not request.user.is_authenticated():
        return render_to_response('myapp/login_error.html')
    # ...

from django.contrib.auth.decorators import login_required

def my_view(request):
    # ...
my_view = login_required(my_view)

from django.contrib.auth.decorators import login_required

@login_required
def my_view(request):
    # ...

from django.contrib.auth.decorators import login_required

    def my_view(request):
        # ...
    my_view = login_required(redirect_field_name='redirect_to')(my_view)

from django.contrib.auth.decorators import login_required

@login_required(redirect_field_name='redirect_to')
    def my_view(request):
        # ...

(r'^accounts/login/$', 'django.contrib.auth.views.login'),

(r'^accounts/login/$', 'django.contrib.auth.views.login', {'template_name': 'myapp/login.html'}),

{% extends "base.html" %}

{% block content %}

{% if form.errors %}
<p>Utilisateur et mot de passe incorrects. Essayez à nouveau s'il vous plaît.</p>
{% endif %}

<form method="post" action=".">
<table>
<tr><td>{{ form.username.label_tag }}</td><td>{{ form.username }}</td></tr>
<tr><td>{{ form.password.label_tag }}</td><td>{{ form.password }}</td></tr>
</table>

<input type="submit" value="login" />
<input type="hidden" name="next" value="{{ next }}" />
</form>

{% endblock %}

Autres vues prêtes à l'emploi

En plus de la vue login, le système d'authentification contient quelques vues prêtes à l'emploi utiles :

Formulaires par défaut

Nouveau dans la version de développement de Django

Si vous ne souhaitez pas utiliser les vues prêtes à l'emploi, mais voulez conserver l'avantage de ne pas avoir à écrire de formulaires pour cette fonctionnalité, le système d'authentification vous fournit plusieurs formulaires :

• django.contrib.auth.forms.AdminPasswordChangeForm: Un formulaire utilisé dans l'interface d'administration pour changer le mot de passe d'un utilisateur.
• django.contrib.auth.forms.AuthenticationForm: Un formulaire pour authentifier un utilisateur
• django.contrib.auth.forms.PasswordChangeForm: Un formulaire pour permettre à un utilisateur de changer de mot de passe.
• django.contrib.auth.forms.PasswordResetForm: Un formulaire pour réinitialiser le mot de passe d'un utilisateur et lui envoyer le nouveau mot de passe par courriel.
• django.contrib.auth.forms.UserCreationForm: Un formulaire pour créer un nouvel utilisateur.

Limiter l'accès aux utilisateurs authentifiés qui satisfont une autre condition

Pour limiter l'accès sur la base de certaines permissions ou d'autres conditions, le principe est le même que celui décrit dans la section précédente.

La façon la plus simple est de tester votre condition sur request.user directement dans la vue. Par exemple, cette vue vérifie que l'utilisateur est authentifié et a la permission polls.can_vote:

def my_view(request):
    if not (request.user.is_authenticated() and request.user.has_perm('polls.can_vote')):
        return HttpResponse("Vous ne pouvez pas voter dans ce sondage.")
    # ...

Vous pouvez utiliser le decorator user_passes_test qui est un raccourci bien pratique:

from django.contrib.auth.decorators import user_passes_test

def my_view(request):
    # ...
my_view = user_passes_test(lambda u: u.has_perm('polls.can_vote'))(my_view)

On utilise ce test en particulier pour faire un exemple relativement simple. Si toutefois vous voulez simplement savoir si un utilisateur a une permission donnée, utilisez le decorator permission_required() qui est décrit plus loin dans ce document.

Voici la même chose en utilisant la syntaxe de decorator de Python 2.4:

from django.contrib.auth.decorators import user_passes_test

@user_passes_test(lambda u: u.has_perm('polls.can_vote'))
def my_view(request):
    # ...

user_passes_test a un paramètre obligatoire : un objet appelable qui prend un objet User et renvoie True si l'utilisateur est autorisé à voir la page. Notez que user_passes_test ne vérifie pas automatiquement si l'utilisateur est anonyme ou non.

user_passes_test() a également un paramètre optionnel, login_url, qui vous permet de préciser l'URL de votre page d'authentification (settings.LOGIN_URL par défaut).

Exemple avec la syntaxe de Python 2.3:

from django.contrib.auth.decorators import user_passes_test

def my_view(request):
    # ...
my_view = user_passes_test(lambda u: u.has_perm('polls.can_vote'), login_url='/login/')(my_view)

Exemple avec la syntaxe de Python 2.4:

from django.contrib.auth.decorators import user_passes_test

@user_passes_test(lambda u: u.has_perm('polls.can_vote'), login_url='/login/')
def my_view(request):
    # ...

from django.contrib.auth.decorators import permission_required

def my_view(request):
    # ...
my_view = permission_required('polls.can_vote')(my_view)

from django.contrib.auth.decorators import permission_required

def my_view(request):
    # ...
my_view = permission_required('polls.can_vote', login_url='/loginpage/')(my_view)

Limiter l'accès aux vues génériques

Pour limiter l'accès aux vues génériques, encapsulez la vue et faites pointer l'URLconf vers le code qui l'encapsule plutôt que vers la vue elle-même. Par exemple:

from django.views.generic.date_based import object_detail

@login_required
def limited_object_detail(*args, **kwargs):
    return object_detail(*args, **kwargs)

Permissions par défaut

Quand django.contrib.auth est listé dans votre réglage INSTALLED_APPS, vous êtes sûrs que trois permissions par défaut -- "add", "change" et "delete" -- sont créées pour chaque modèle Django défini dans vos applications installées.

Ces permissions seront créées lorsque vous lancez manage.py syncdb ; la première fois que vous utilisez syncdb après avoir ajouté django.contrib.auth à INSTALLED_APPS, les permissions par défaut seront créées pour tous les modèles installés précédemment, comme pour tous les nouveaux modèles installés cette fois là. Par la suite, les permissions par défaut seront créées pour les nouveaux modèles chaque fois que vous lancerez manage.py syncdb.

Permissions personnalisées

Pour créer des permissions personnalisées pour un modèle, utilisez l'attribut Meta des modèles permissions.

Ce modèle d'exemple crée trois permissions personnalisées:

class USCitizen(models.Model):
    # ...
    class Meta:
        permissions = (
            ("can_drive", "Can drive"),
            ("can_vote", "Can vote in elections"),
            ("can_drink", "Can drink alcohol"),
        )

La seule chose que cela fait en pratique est de créer ces permissions supplémentaires lorsque vous lancez syncdb.

Référence de l'API

Comme les utilisateurs, les permissions sont implémentées dans un modèle Django qui se trouve dans django/contrib/auth/models.py.

Utilisateurs

L'utilisateur actuellement en ligne, soit une instance de User, soit une instance de AnonymousUser, est stocké dans la variable de template {{ user }}:

{% if user.is_authenticated %}
    <p>Welcome, {{ user.username }}. Thanks for logging in.</p>
{% else %}
    <p>Welcome, new user. Please log in.</p>
{% endif %}

Permissions

Les permissions de l'utilisateur actuellement en ligne sont stockées dans la variable de template {{ perms }}. C'est une instance de django.core.context_processors.PermWrapper, qui est un proxy de permissions destiné aux templates.

Dans l'objet {{ perms }}, la recherche d'attributs simples est un proxy de User.has_module_perms. Cet exemple afficherait True si l'utilisateur en ligne avait une permission quelconque de l'application foo:

{{ perms.foo }}

La recherche d'attributs à deux niveaux est un proxy de User.has_perm. Cet exemple afficherait True si l'utilisateur en ligne avait la permission foo.can_vote:

{{ perms.foo.can_vote }}

Donc, vous pouvez vérifier les permissions dans des structures {% if %} de templates:

{% if perms.foo %}
    <p>You have permission to do something in the foo app.</p>
    {% if perms.foo.can_vote %}
        <p>You can vote!</p>
    {% endif %}
    {% if perms.foo.can_drive %}
        <p>You can drive!</p>
    {% endif %}
{% else %}
    <p>You don't have permission to do anything in the foo app.</p>
{% endif %}

Spécifier de nouveaux backends d'authentification

Django gère en coulisses une liste de "backends d'authentification" qu'il utilise pour l'authentification. Lorsque django.contrib.auth.authenticate() est appelé -- comme il est expliqué dans "Comment authentifier un utilisateur" ci-dessus --, Django essaie tous les backends d'authentification de la liste. Si la première méthode d'authentification échoue, Django essaie la seconde, et ainsi de suite, jusqu'à ce qu'il ait essayé tous les backends.

La liste des backends d'authentification à utiliser est précisée dans la variable AUTHENTICATION_BACKENDS. Cette variable est un tuple de chemins Python qui pointent vers des classes Python chargées de l'authentification. Ces classes peuvent se trouver où vous voulez dans votre chemin Python.

Par défaut, la valeur de AUTHENTICATION_BACKENDS est:

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

C'est-à-dire le système de base d'authentification, fondé sur la base d'utilisateurs Django.

L'ordre des backends dans le tuple AUTHENTICATION_BACKENDS a une importance dans la mesure où si un couple utilisateur et mot de passe est valide dans plusieurs backends, Django s'arrêtera au premier qui permet de le vérifier.

Comment écrire un backend d'authentification

Un backend d'authentification est une classe qui implémente deux méthodes: get_user(user_id) et authenticate(**credentials).

La méthode get_user prend une user_id -- qui peut être un nom d'utilisateur, une ID dans une base de données ou autre -- et renvoie un objet User.

La méthode authenticate prend en argument les valeurs d'authentification. La plupart du temps, ce sera simplement quelque chose du genre:

class MyBackend:
    def authenticate(self, username=None, password=None):
        # Vérifie le couple username/password et renvoie un objet User.

Mais elle peut aussi authentifier à partir d'un jeton, comme dans:

class MyBackend:
    def authenticate(self, token=None):
        # Vérifie la validité du jeton, et renvoie un objet User.

Dans tous les cas, authenticate doit vérifier la validité des données d'authentification fournies, et doit renvoyer un objet User qui correspond à ces données si elles sont valides. Si elles ne sont pas valides, la méthode doit renvoyer None.

Le système d'administration de Django est très fortement lié à l'objet Django User décrit au début de ce document. Pour le moment, la meilleure façon de gérer cette contrainte est de créer un objet User Django pour chacun des objets de votre backend (par exemple votre annuaire LDAP, votre base SQL externe, etc.). Vous pouvez soit écrire un script qui le fait à l'avance, soit prévoir que votre méthode authenticate le fasse la première fois que votre utilisateur se connecte.

Voici un exemple de backend qui authentifie à partir d'un nom d'utilisateur et d'un mot de passe définis dans votre fichier settings.py et crée un objet Django User la première fois que l'utilisateur cherche à se connecter:

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

class SettingsBackend:
    """
    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

Gérer les autorisations dans les backends personnalisés

Les backends d'authentification personnalisés peuvent fournir leurs propres permissions.

Le modèle utilisateur déléguera les fonctions de recherche de permissions (get_group_permissions(), get_all_permissions(), has_perm(), et has_module_perms()) a tout backend d'authentification qui implémente ces fonctions.

Les permissions de l'objet User seront un surensemble de toutes les permissions retournées par tous les backends. Django accordera a un utilisateur toute permission accordée par un quelconque des backends.

Le backend d'exemple ci-dessus pourrait mettre en place des permissions pour l'administrateur de façon très simple:

class SettingsBackend:

    # ...

    def has_perm(self, user_obj, perm):
        if user_obj.username == settings.ADMIN_LOGIN:
            return True
        else:
            return False

Ce code donne toutes les permissions à l'utilisateur qui a obtenu l'accès dans l'exemple précédent. Notez que les fonctions d'authentification des backends prennent toutes l'objet User comme argument, et qu'elles acceptent également les mêmes arguments que ceux qui sont fournis aux fonctions associées du User.

Une implémentation complète de système d'autorisation est fournie dans django/contrib/auth/backends.py, qui est le backend par défaut et interroge la table auth_permission la plupart du temps.