API-Referenz

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, ...]
myuser.user_permissions.clear()

Grundlegende Benutzung

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

# An diesem Punkt ist der Benutzer ein Objekt, das schon in die Datenbank
# gespeichert wurde. Du kannst damit fortfahren seine Attribute zu
# ändern, wenn du andere Felder ändern willst.
>>> 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()

Passwörter

Das password-Attribut eines user-Objektes ist ein String in diesem Format:

hashtype$salt$hash

Das sind hashtype, salt und hash, getrennt durch ein Dollar-Zeichen.

Hashtype ist entweder sha1 (Standard), md5 oder crypt – der Algorithmus wird benutzt, um einen einseitigen Hash eines Passwortes durchzuführen. Salt ist ein zufälliger String, der benutzt wird, um aus dem unverschlüsselten Passwort einen Hash zu erzeugen. Beachte, dass die crypt-Methode nur von Plattformen unterstützt wird, die das Standard-Python crypt-Modul verfügbar haben, und dass crypt nur in der Django-Entwicklerversion verfügbar ist.

Zum Beispiel:

sha1$a1976$a36cc8cbf81742a8fb52e221aaeab48ed7f58ab4

Die User.set_password()- und User.check_password()-Funktionen verwalten die Einstellungen und überprüfen die Werte hinter den Kulissen.

Vorherige Django-Versionen, wie 0.90, benutzten einen einfachen MD5-Hash ohne Passwort-Salt und werden für die Rückwärtskompabilität immer noch unterstützt. Sie werden automatisch in den neuen Stil konvertiert, wenn User.check_password() für einen bestimmten Benutzer zum ersten Mal korrekt arbeitet.

Anonyme Benutzer

django.contrib.auth.models.AnonymousUser ist eine Klasse, die das django.contrib.auth.models.User-Interface implementiert, mit folgenden Unterschieden:

• id ist immer None.
• is_staff und is_superuser sind immer False.
• is_active ist immer True.
• groups und user_permissions sind immer leer.
• is_anonymous() gibt True anstelle von False zurück.
• is_authenticated() gibt False anstelle von True zurück.
• has_perm() gibt immer False zurück.
• set_password(), check_password(), save(), delete(), set_groups() und set_permissions() erzeugen NotImplementedError.

In der Anwendung wirst du wahrscheinlich AnonymousUser-Objekte selber nicht benötigen. Sie werden aber von Web-Anfragen benutzt, wie im nächsten Abschnitt erklärt wird.

Superuser erstellen

manage.py syncdb fordert dich auf, einen Superuser anzulegen, wenn du es zum ersten Mal ausführst, nachdem du 'django.contrib.auth' zu deinen INSTALLED_APPS hinzufügt hast. Wenn du später einen Superuser auf der Kommandozeile erzeugen musst, kannst du das Dienstprogramm create_superuser.py benutzen. Führe einfach diesen Befehl aus:

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

Stelle sicher, dass du /path/to/ mit dem Pfad zum Django-Code in deinem Dateisystem ersetzt.

Zusätzliche Informationen über Benutzer speichern

Wenn du zusätzliche Informationen für deine Benutzer speichern möchtest, bietet Django für diesen Zweck eine Methode an, um ein seitenspezifisches Datenmodell – “Benutzerprofil” genannt – zu spezifizieren.

Um diese Funktion zu nutzen, musst du ein Datenmodell mit Feldern für die zusätzlichen Informationen definieren oder weitere Methoden anlegen, die verfügbar sein sollen. Füge auch einen ForeignKey Feld zu diesem Datenmodell hinzu, dass auf das User-Datenmodell zeigt. Achte darauf, dass du dabei unique=True festlegst, damit nur eine Instanz deines Datenmodells für jeden Benutzer erzeugt werden kann.

Um zu kennzeichnen, dass dieses Datenmodell das Datenmodell des Benutzerprofils für eine bestimmte Seite ist, setze die Einstellung AUTH_PROFILE_MODULE auf eine Zeichenkette, die aus folgenden Teilen, durch einem Punkt getrennt, besteht:

1. Der Name (normalisiert zu Kleinschreibung) der Applikation, in der das Benutzerprofil definiert ist (in anderen Worten, eine kleingeschriebene Version des Namen, der an manage.py startapp weitergegeben wurde, um die Anwendung zu erzeugen).
2. Der Name (normalisiert zu Kleinschreibung) der Datenmodell-Klasse.

Wenn zum Beispiel das Benutzerprofil -Datenmodell durch die Klasse UserProfile repräsentiert wird, die in der Anwendung accounts definiert wurde, würde die dazugehörige Einstellung sein:

AUTH_PROFILE_MODULE = 'accounts.userprofile'

Wenn ein Benutzerprofil-Datenmodell auf diese Art und Weise festgelegt wurde, hat jedes User-Objekt eine Methode – get_profile() – die eine Instanz des Benutzerprofil-Datenmodell zurückgibt, das mit User verknüpft ist.

Für weitere Informationen, siehe Kapitel 12 des Django-Buches.

Wie man einen Benutzer anmeldet

Django bietet zwei Funktionen in django.contrib.auth: authenticate() und login().

Um einen bestimmten Benutzername und ein Passwort zu authentifizieren, benutze authenticate(). Es nimmt zwei Parameter entgegen, username und password, und gibt ein User-Objekt zurück, wenn das Passwort für den Benutzernamen korrekt war. Wenn das Passwort falsch war, gibt authenticate() None zurück. Beispiel:

from django.contrib.auth import authenticate
user = authenticate(username='john', password='secret')
if user is not None:
    if user.is_active:
        print "Korrekter Benutzername und Passwort!"
    else:
        print "Dein Account wurde deaktiviert!!"
else:
    print "Dein Benutzername und Passwort waren falsch."

Um einen Benutzer in einer View anzumelden, benutze login(). Es nimmt ein HttpRequest-Objekt und ein User-Objekt entgegen. login() speichert, mit Hilfe Djangos Session-Framework, die ID des Benutzers in der Session. Deswegen musst du sicherstellen, dass die Session-Middleware installiert wurde (siehe oben).

Dieses Beispiel zeigt, wie du authenticate() und login benutzen könntest:

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)
            # Weiterleiten auf Erfolgsseite.
        else:
            # Gibt eine 'Deaktivierter Account' Fehlermeldung aus.
    else:
        # Gibt eine 'Fehlerhafte Anmeldung' Fehlermeldung aus.

Ein Benutzerpasswort manuell prüfen

Wenn du einen Benutzer manuell authentifizieren willst, indem du ein Passwort in Klartext mit dem Hash-Passwort in der Datenbank vergleichst, benutze die fertige Funktion django.contrib.auth.models.check_password. Sie nimmt zwei Argumente entgegen: das Passwort in Klartext, das überprüft werden soll und den vollen Wert vom password-Feld des Benutzers in der Datenbank. Sie gibt True zurück, wenn die Passwörter übereinstimmen und False, wenn nicht.

Wie man einen Benutzer abmeldet

Um einen Benutzer, der mit django.contrib.auth.login() angemeldet wurde wieder abzumelden, benutze django.contrib.auth.logout() in deiner View. Sie nimmt ein HttpRequest-Objekt entgegen und gibt keinen Wert zurück. Beispiel:

from django.contrib.auth import logout

def logout_view(request):
    logout(request)
    # Weiterleiten an eine Erfolgsseite.

Beachte, dass logout() keine Fehler ausgibt, wenn der Benutzer nicht angemeldet war.

Zugriff für angemeldete Benutzer beschränken

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.has_errors %}
<p>Dein Benutzername und Passwort stimmen nicht. Versuche es noch einmal.</p>
{% endif %}

<form method="post" action=".">
<table>
<tr><td><label for="id_username">Benutzername:</label></td><td>{{ form.username }}</td></tr>
<tr><td><label for="id_password">Passwort:</label></td><td>{{ form.password }}</td></tr>
</table>

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

{% endblock %}

Andere eingebaute Views

Zusätzlich zur login-View enthält das Authentifizierungssystem ein paar andere nützliche eingebaute Views:

Eingebaute Manipulatoren

Wenn du nicht die eingebauten Views benutzen möchtest, aber dennoch den Vorteil behalten möchtest, keine Manipulatoren für diese Funktionalität schreiben zu müssen, bietet das Authentifizierungssystem verschiedene eingebaute Manipulatoren:

• django.contrib.auth.forms.AdminPasswordChangeForm: Ein Manipulator, der im Admin-Interface benutzt wird, um das Passwort des Benutzers zu ändern.
• django.contrib.auth.forms.AuthenticationForm: Ein Manipulator, um den Benutzer anzumelden.
• django.contrib.auth.forms.PasswordChangeForm: Ein Manipulator, der dem Benutzer erlaubt, sein Passwort zu ändern.
• django.contrib.auth.forms.PasswordResetForm: Ein Manipulator, um das Passwort des Benutzers zurückzusetzen und ihm ein neues Passwort per E-Mail zu schicken.
• django.contrib.auth.forms.UserCreationForm: Ein Manipulator, zum Erstellen eines neuen Benutzers.

Zugriff für angemeldete Benutzer beschränken, die einen Test bestehen

Um den Zugriff anhand bestimmter Berechtigungen oder anderer Tests zu beschränken, würdest du im Wesentlichen das Gleiche machen, was im vorherigen Abschnitt beschrieben wurde.

Am einfachsten ist es, die Überprüfung des request.user direkt in der View durchzuführen. So prüft die folgende View z. B., ob der Benutzer angemeldet ist und die Berechtigung polls.can_vote hat:

def my_view(request):
    if not (request.user.is_authenticated() and request.user.has_perm('polls.can_vote')):
        return HttpResponse("Du kannst für diese Abstimmung nicht wählen.")
    # ...

Zur Abkürzung kannst du den komfortablen Decorator user_passes_test benutzen:

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)

Wir benutzen diesen bestimmten Test als relativ einfaches Beispiel. Dennoch kannst du den permission_required()-Decorator benutzen, wenn du nur prüfen willst, ob ein Benutzer eine bestimmte Berechtigung besitzt, wie später in diesem Dokumente beschrieben.

Hier ist das Gleiche unter Benutzung der Python 2.4-Decorator-Syntax:

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 erfordert ein Argument: Eine ausführbare Funktion (Callable), die ein User-Objekt entgegennimmt und True zurückgibt, wenn der Benutzer die Seite ansehen darf. Beachte, dass user_passes_test nicht automatisch prüft, ob User nicht anonym ist.

user_passes_test() nimmt ein optionales login_url-Argument, mit der du die URL für deine Anmeldeseite (standardmäßig settings.LOGIN_URL) festlegen kannst.

Beispiel in Python 2.3-Syntax:

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)

Beispiel in Python 2.4-Syntax:

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)

Zugriff auf Generic Views beschränken

Um den Zugriff auf eine Generic View zu beschränken, musst du einen einfachen Wrapper um die View schreiben und in deiner URLconf auf den Wrapper, statt auf die Generische View, verweisen. Zum Beispiel:

from django.views.generic.date_based import object_detail

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

Standard-Berechtigungen

Drei grundlegende Berechtigungen – Hinzufügen, Ändern und Löschen – werden automatisch für jedes Django-Datenmodell erzeugt, das class Admin enthält. Im Hintergrund werden diese Berechtigungen zur auth_permission-Datenbanktabelle hinzugefügt, sobald du manage.py syncdb ausführst.

Beachte, dass die Berechtigungen nicht erzeugt werden, wenn dein Datenmodell nicht class Admin enthält. Wenn du deine Datenbank initialisierst und erst danach class Admin zu deinen Datenmodellen hinzufügst, musst du manage.py syncdb erneut ausführen. Dadurch werden alle fehlenden Berechtigungen für deine installierten Anwendungen hinzugefügt.

Eigene Berechtigungen

Um eigene Berechtigungen für ein gegebenes Datenmodell-Objekt zu erstellen, benutze das permissions-Datenmodell-Meta-Attribut.

Dieses Beispiel-Datenmodell erzeugt drei eigene Berechtigungen:

class USCitizen(models.Model):
    # ...
    class Meta:
        permissions = (
            ("can_drive", "Darf fahren"),
            ("can_vote", "Darf wählen"),
            ("can_drink", "Darf Alkohol trinken"),
        )

Dadurch werden einfach diese extra Berechtigungen erzeugt, sobald du syncdb ausführst.

API-Referenz

Genau wie Benutzer sind Berechtigungen in einem Django-Datenmodell implementiert, das in django/contrib/auth/models.py zu finden ist.

Benutzer

Der zur Zeit angemeldete Benutzer, entweder eine User-Instanz oder eine AnonymousUser-Instanz, wird in der Template-Variable {{ user }} abgelegt:

{% if user.is_authenticated %}
    <p>Willkommen, {{ user.username }}. Vielen Dank für die Anmeldung.</p>
{% else %}
    <p>Willkommen, neuer Benutzer. Bitte melde dich an.</p>
{% endif %}

Berechtigungen

Die Berechtigungen des zur Zeit angemeldeten Benutzers werden in der Template-Variable {{ perms}} abgelegt. Dies ist eine Instanz von django.core.context_processors.PermWrapper, der einen templatefreundlichen Zugriff auf die Berechtigungen ermöglicht.

Beim {{ perms }}-Objekt ruft eine einzelne Attribut-Abfrage im Hintergrund User.has_module_perms auf. Dieses Beispiel würde True anzeigen, wenn der angemeldete Benutzer irgendwelche Rechte auf die foo-Anwendung hätte:

{{ perms.foo }}

Eine Attribut-Abfrage auf zwei Ebenen ruft im Hintergrund User.has_perm auf. Dieses Beispiel würde True anzeigen, wenn der angemeldete Benutzer irgendwelche Rechte auf foo.can_vote hätte:

{{ perms.foo.can_vote }}

Daher kannst du die Berechtigungen im Template mit {% if %}-Statements abfragen:

{% if perms.foo %}
    <p>Du hast die Rechte, etwas in der Anwendung zu machen.</p>
    {% if perms.foo.can_vote %}
        <p>Du darfst wählen!</p>
    {% endif %}
    {% if perms.foo.can_drive %}
        <p>Du darfst fahren!</p>
    {% endif %}
{% else %}
    <p>Du hast keine Berechtigungen, irgendetwas in der Anwendung zu machen.</p>
{% endif %}

Authentifizierungs-Backends festlegen

Im Hintergrund führt Django eine Liste mit “Authentifizierungs-Backends”, die es während der Authentifizierung benutzt. Wenn – wie in “Wie man einen Benutzer abmeldet” oben beschrieben – django.contrib.auth.authenticate() aufgerufen wird, versucht Django alle Authentifizierungs-Backends zu benutzen. Wenn also die erste Authentifizierungs-Methode fehlschlägt, versucht Django die zweite (und so weiter), solange bis alle ausprobiert wurden.

Die Liste der zu benutzenden Authentifizierungs-Backends wird in den AUTHENTICATION_BACKENDS-Einstellungen näher definiert. Dies sollte ein Tuple von Python-Pfaden sein, die auf Python-Klassen zeigen, die wissen, wie authentifiziert wird. Diese Klassen können irgendwo auf dem Python-Pfad liegen.

Standardmäßig ist AUTHENTICATION_BACKENDS eingestellt auf:

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

Dieses grundlegende Authentifizierungs-Schema benutzt die Benutzerdatenbank von Django.

Die Reihenfolge der AUTHENTICATION_BACKENDS ist wichtig, wenn also der gleiche Benutzername und das gleiche Password in verschiedenen Backends vorhanden ist, hört Django mit der Überprüfung beim ersten positiven Treffer auf.

Ein Authentifizierungs-Backend schreiben

Eine Authentifizierungs-Backend ist eine Klasse, die zwei Methoden implementiert: get_user(user_id) und authenticate(**credentials).

Die get_user-Methode nimmt ein user_id entgegen – was ein Benutzername, eine Datenbank-ID oder was auch immer sein kann – und gibt ein User-Objekt zurück.

Die authenticate-Methode nimmt Berechtigungen als Schlagwort-Argumente entgegen. Normalerweise sieht das so aus:

class MyBackend:
    def authenticate(self, username=None, password=None):
        # Prüfe Benutzername/Passwort und gibt einen User zurück.

Aber es könnte auch als Token authentifizieren, etwa so:

class MyBackend:
    def authenticate(self, token=None):
        # Prüfe den Token und gibt einen User zurück.

So oder so, authenticate sollte die übergebenen Anmeldedaten überprüfen und ein User-Objekt zurückgeben, das mit den Berechtigungen übereinstimmt, wenn sie korrekt sind. Wenn sie nicht korrekt sind, sollte es None zurückgeben.

Die Django-Administrationsoberfläche ist eng mit dem Django-User-Objekt gekoppelt, das wir am Anfang dieses Dokumentes beschrieben haben. Der beste Weg damit umzugehen, ist im Moment, ein Django-User-Objekt für jeden Benutzer zu erzeugen, der in deinem Backend existiert (z. B. in deinem LDAP-Verzeichnis, deiner externen SQL-Datenbank, usw.). Du kannst entweder ein Skript schreiben, um dies im Voraus zu machen, oder deine authenticate-Methode erledigt es, wenn sich ein Benutzer das erste Mal anmeldet.

Hier ist ein Beispiel-Backend, das die Variablen username und password, die in deiner settings.py-Datei definiert sind, für die Authentifizierung benutzt. Es erzeugt ein Django-User-Objekt, wenn sich ein Benutzer das erste Mal authentifiziert:

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

class SettingsBackend:
    """
    Authentifizierung mit den Einstellungen ADMIN_LOGIN und ADMIN_PASSWORD.

    Benutze den Anmeldenamen und einen Hash des Passworts. Zum Beispiel:

    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:
                # Erzeuge einen neuen Benutzer. Beachte, dass wir das
                # Passwort beliebig vergeben können, weil es nicht
                # geprüft wird; das Passwort aus settings.py wird hingegen
                # geprüft.
                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

Autorisierung an benutzerdefinierten Backends

Benutzerdefinierte Authentifizierungs-Backends stellen ihre eigenen Berechtigungen bereit.

Das User-Datenmodell überträgt Funktionen zur Abfrage von Berechtigungen (get_group_permissions(), get_all_permissions(), has_perm() und has_module_perms()) an jedes Authentifizierungs-Backend, das diese Funktionen implementiert.

Die Berechtigungen, die ein Benutzer erhält, sind alle Berechtigungen, die von allen Backends zurückgegeben wurden. Das bedeutet, Django erteilt alle Berechtigungen, die irgendeines der Backends erteilt.

Das einfache Backend oben, könnte Berechtigungen für das magische Admin relativ einfach implementieren:

class SettingsBackend:

    # ...

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

Dies erteilt dem Benutzer im Beispiel oben volle Berechtigungen. Beachte, dass die Backend-Authentifizierungsfunktionen alle ein User-Objekt als Argument entgegennehmen, und sie akzeptieren auch die gleichen Argumente die an die zugehörigen User-Funktionen gegeben werden.

Eine vollständige Implementierung der Autorisierung findest du in django/contrib/auth/backends.py, das das standardmäßige Backend ist und hauptsächlich die auth_permission-Tabelle abfragt.