django.contrib.auth

Detta dokument tillhandahåller API-referensmaterial för komponenterna i Djangos autentiseringssystem. För mer information om användningen av dessa komponenter eller hur du anpassar autentisering och auktorisering, se autentisering ämnesguide.

User modell

class models.User

Fält

class models.User

User-objekt har följande fält:

username

Krävs. 150 tecken eller färre. Användarnamn kan innehålla alfanumeriska tecken, _, @, +, . och -.

Den maximala längden bör vara tillräcklig för många användningsfall. Om du behöver en längre längd, använd en custom user model.

first_name

Valfritt (blank=True). 150 tecken eller färre.

last_name

Valfritt (blank=True). 150 tecken eller färre.

email

Valfritt (blank=True). E-post adress.

password

Obligatoriskt. En hash av, och metadata om, lösenordet. (Django lagrar inte det råa lösenordet.) Råa lösenord kan vara godtyckligt långa och kan innehålla alla tecken. Metadata i detta fält kan markera lösenordet som oanvändbart. Se dokumentation om lösenord.

groups

Många-till-många-relation till Group

user_permissions

Många-till-många-relation till Permission

is_staff

Boolesk. Tillåter att den här användaren får åtkomst till administratörsplatsen.

is_active

Boolesk. Markerar detta användarkonto som aktivt. Vi rekommenderar att du sätter den här flaggan till False istället för att radera konton. På så sätt går inte de utländska nycklarna sönder om dina applikationer har några utländska nycklar till användare.

Detta kontrollerar inte nödvändigtvis om användaren kan logga in eller inte. Autentiseringsbackends är inte skyldiga att kontrollera flaggan is_active men standardbackend (ModelBackend) och RemoteUserBackend gör det. Du kan använda AllowAllUsersModelBackend eller AllowAllUsersRemoteUserBackend om du vill tillåta inaktiva användare att logga in. I det här fallet vill du också anpassa AuthenticationForm som används av LoginView eftersom den avvisar inaktiva användare. Tänk på att metoderna för behörighetskontroll som has_perm() och autentiseringen i Django admin alla returnerar False för inaktiva användare.

is_superuser

Booleansk. Behandlar den här användaren som om den har alla behörigheter utan att tilldela någon särskild behörighet till den.

last_login

En datatid för användarens senaste inloggning.

date_joined

Datum/tid då kontot skapades.

Attribut

class models.User

is_authenticated

Skrivskyddat attribut som alltid är True (i motsats till AnonymousUser.is_authenticated som alltid är False). Det här är ett sätt att se om användaren har autentiserats. Det innebär inte några behörigheter och kontrollerar inte om användaren är aktiv eller har en giltig session. Även om du normalt kommer att kontrollera detta attribut på request.user för att ta reda på om det har fyllts i av AuthenticationMiddleware (som representerar den för närvarande inloggade användaren), bör du veta att detta attribut är True för alla User-instanser.

is_anonymous

Skrivskyddat attribut som alltid är False. Detta är ett sätt att skilja mellan objekten User och AnonymousUser. Generellt sett bör du föredra att använda is_authenticated framför detta attribut.

Metoder

class models.User

get_username()

Returnerar användarnamnet för användaren. Eftersom User-modellen kan bytas ut bör du använda den här metoden istället för att referera till användarnamnsattributet direkt.

get_full_name()

Returnerar first_name plus last_name, med ett mellanslag emellan.

get_short_name()

Returnerar first_name.

set_password(raw_password)

Ställer in användarens lösenord till den angivna råsträngen och tar hand om lösenordets hashing. Sparar inte User-objektet.

När raw_password är None, kommer lösenordet att sättas till ett oanvändbart lösenord, som om set_unusable_password() användes.

check_password(raw_password)

acheck_password(raw_password)

Asynkron version: acheck_password()

Returnerar True om den angivna råsträngen är rätt lösenord för användaren. (Detta tar hand om lösenordets hashing vid jämförelsen.)

set_unusable_password()

Markerar användaren som att inget lösenord har angetts genom att uppdatera metadata i fältet password. Detta är inte samma sak som att ha en tom sträng som lösenord. check_password() för den här användaren kommer aldrig att returnera True. Sparar inte objektet User.

Du kan behöva detta om autentiseringen för din applikation sker mot en befintlig extern källa, t.ex. en LDAP-katalog.

Begränsning av återställning av lösenord

Användare som har ett oanvändbart lösenord kommer inte att kunna begära ett e-postmeddelande om återställning av lösenord via PasswordResetView.

has_usable_password()

Returnerar False om set_unusable_password() har anropats för den här användaren.

get_user_permissions(obj=None)

aget_user_permissions(obj=None)

Asynkron version: aget_user_permissions()

Returnerar en uppsättning behörighetssträngar som användaren har direkt.

Om obj anges returneras endast användarrättigheterna för detta specifika objekt.

Changed in Django 5.2:

metoden aget_user_permissions() har lagts till.

get_group_permissions(obj=None)

aget_group_permissions(obj=None)

Asynkron version: aget_group_permissions()

Returnerar en uppsättning behörighetssträngar som användaren har via sina grupper.

Om obj anges returneras endast gruppbehörigheterna för detta specifika objekt.

Changed in Django 5.2:

metoden aget_group_permissions() har lagts till.

get_all_permissions(obj=None)

aget_all_permissions(obj=None)

Asynkron version: aget_all_permissions()

Returnerar en uppsättning behörighetssträngar som användaren har, både genom grupp- och användarbehörigheter.

Om obj anges returneras endast behörigheterna för detta specifika objekt.

Changed in Django 5.2:

metoden aget_all_permissions() har lagts till.

has_perm(perm, obj=None)

ahas_perm(perm, obj=None)

Asynkron version: ahas_perm()

Returnerar True om användaren har den angivna behörigheten, där perm är i formatet "<app label>.<permission codename>". (se dokumentation om permissions). Om användaren är inaktiv kommer denna metod alltid att returnera False. För en aktiv superanvändare kommer denna metod alltid att returnera True.

Om obj skickas in kommer denna metod inte att söka efter en behörighet för modellen, utan för detta specifika objekt.

Changed in Django 5.2:

metoden ahas_perm() har lagts till.

has_perms(perm_list, obj=None)

ahas_perms(perm_list, obj=None)

Asynkron version: ahas_perms()

Returnerar True om användaren har var och en av de angivna behörigheterna, där varje behörighet är i formatet "<app label>.<permission codename>". Om användaren är inaktiv returnerar denna metod alltid False. För en aktiv superanvändare kommer denna metod alltid att returnera True.

Om obj anges kommer den här metoden inte att kontrollera behörigheter för modellen, utan för det specifika objektet.

Changed in Django 5.2:

metoden ahas_perms() har lagts till.

has_module_perms(package_name)

ahas_module_perms(package_name)

Asynkron version: ahas_module_perms()

Returnerar True om användaren har några behörigheter i det angivna paketet (Django-appens etikett). Om användaren är inaktiv kommer denna metod alltid att returnera False. För en aktiv superanvändare kommer denna metod alltid att returnera True.

Changed in Django 5.2:

metoden ahas_module_perms() har lagts till.

email_user(subject, message, from_email=None, **kwargs)

Skickar ett e-postmeddelande till användaren. Om from_email är None använder Django DEFAULT_FROM_EMAIL. Alla **kwargs skickas till det underliggande send_mail()-anropet.

Metoder för chefer

class models.UserManager

Modellen User har en anpassad manager som har följande hjälpmetoder (utöver de metoder som tillhandahålls av BaseUserManager):

create_user(username, email=None, password=None, **extra_fields)

acreate_user(username, email=None, password=None, **extra_fields)

Asynkron version: acreate_user()

Skapar, sparar och returnerar en User.

username och password är inställda som angivet. Domändelen av email konverteras automatiskt till gemener, och det returnerade User-objektet kommer att ha is_active satt till True.

Om inget lösenord anges kommer set_unusable_password() att anropas.

Om ingen e-postadress anges kommer email att sättas till en tom sträng.

Nyckelordsargumenten extra_fields skickas till User’s __init__ metod för att tillåta inställning av godtyckliga fält på en custom user model.

Se Skapa användare för exempel på användning.

Changed in Django 5.2:

metoden acreate_user() har lagts till.

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

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

Asynkron version: acreate_superuser()

Samma som create_user(), men sätter is_staff och is_superuser till True.

Changed in Django 5.2:

metoden acreate_superuser() har lagts till.

with_perm(perm, is_active=True, include_superusers=True, backend=None, obj=None)

Returnerar användare som har den givna behörigheten perm antingen i formatet "<app label>.<permission codename>" eller som en Permission-instans. Returnerar en tom frågeuppsättning om inga användare som har perm hittas.

Om is_active är True (standard) returneras endast aktiva användare, eller om False returneras endast inaktiva användare. Använd None för att returnera alla användare oavsett aktivt tillstånd.

Om include_superusers är True (standard) kommer resultatet att inkludera superanvändare.

Om backend skickas in och det är definierat i AUTHENTICATION_BACKENDS, så kommer denna metod att använda det. Annars kommer den att använda backend i AUTHENTICATION_BACKENDS, om det bara finns en, eller skapa ett undantag.

objektet AnonymUser

class models.AnonymousUser

django.contrib.auth.models.AnonymousUser är en klass som implementerar gränssnittet django.contrib.auth.models.User, med dessa skillnader:

• id är alltid None.

• username är alltid en tom sträng.

• get_username() returnerar alltid den tomma strängen.

• is_anonymous är True istället för False.

• is_authenticated är False istället för True.

• is_staff och is_superuser är alltid False.

• is_active är alltid False.

• groups och user_permissions är alltid tomma.

• set_password(), check_password(), save() och delete() ger upphov till NotImplementedError.

I praktiken kommer du förmodligen inte att behöva använda AnonymousUser-objekt på egen hand, men de används av webbförfrågningar, vilket förklaras i nästa avsnitt.

Bemyndigande modell

class models.Permission

Fält

Permission-objekt har följande fält:

class models.Permission

name

Obligatoriskt. 255 tecken eller färre. Exempel: 'Kan rösta'.

content_type

Krävs. En främmande nyckel till modellen ContentType.

codename

Krävs. 100 tecken eller färre. Exempel: 'can_vote'.

Metoder

Permission-objekt har standardmetoder för dataåtkomst som alla andra Django-modeller.

Grupp modell

class models.Group

Fält

Group-objekt har följande fält:

class models.Group

name

Krävs. 150 tecken eller färre. Alla tecken är tillåtna. Exempel: 'Fantastiska användare'.

permissions

Många-till-många-fält till Permission:

group.permissions.set([permission_list])
group.permissions.add(permission, permission, ...)
group.permissions.remove(permission, permission, ...)
group.permissions.clear()

Validerare

class validators.ASCIIUsernameValidator

En fältvalidator som endast tillåter ASCII-bokstäver och siffror, förutom @, ., +, - och _.

class validators.UnicodeUsernameValidator

En fältvalidator som tillåter Unicode-tecken, utöver @, ., +, - och _. Standardvalideraren för User.username.

Signaler för inloggning och utloggning

Auth-ramverket använder följande signals som kan användas för att meddela när en användare loggar in eller ut.

user_logged_in

Skickas när en användare loggar in framgångsrikt.

Argument som skickas med denna signal:

avsändare

Klassen för den användare som just loggade in.

begäran

Den aktuella HttpRequest-instansen.

användare

Den användarinstans som just loggade in.

user_logged_out

Skickas när utloggningsmetoden anropas.

avsändare

Som ovan: klassen för den användare som just loggade ut eller None om användaren inte var autentiserad.

begäran

Den aktuella HttpRequest-instansen.

användare

Den användarinstans som just loggade ut eller None om användaren inte var autentiserad.

user_login_failed

Skickas när användaren misslyckats med att logga in

avsändare

Namnet på den modul som används för autentisering.

referenser

En ordbok med nyckelordsargument som innehåller de användaruppgifter som skickades till authenticate() eller din egen anpassade autentiseringsbackend. Autentiseringsuppgifter som matchar en uppsättning ”känsliga” mönster (inklusive lösenord) kommer inte att skickas i klartext som en del av signalen.

begäran

Objektet HttpRequest, om ett sådant tillhandahölls till authenticate().

Backend för autentisering

Detta avsnitt beskriver de autentiseringsbackends som levereras med Django. För information om hur du använder dem och hur du skriver dina egna autentiseringsbackends, se Andra autentiseringskällor avsnitt i User authentication guide.

Tillgängliga backends för autentisering

Följande backends finns tillgängliga i django.contrib.auth.backends:

class BaseBackend[source]

En basklass som tillhandahåller standardimplementationer för alla nödvändiga metoder. Som standard kommer den att avvisa alla användare och inte ge några behörigheter.

get_user_permissions(user_obj, obj=None)[source]

aget_user_permissions(user_obj, obj=None)

Asynkron version: aget_user_permissions()

Returnerar en tom uppsättning.

Changed in Django 5.2:

funktionen aget_user_permissions() har lagts till.

get_group_permissions(user_obj, obj=None)[source]

aget_group_permissions(user_obj, obj=None)

Asynkron version: aget_group_permissions()

Returnerar en tom uppsättning.

Changed in Django 5.2:

funktionen aget_group_permissions() har lagts till.

get_all_permissions(user_obj, obj=None)[source]

aget_all_permissions(user_obj, obj=None)

Asynkron version: aget_all_permissions()

Använder get_user_permissions() och get_group_permissions() för att hämta den uppsättning behörighetssträngar som user_obj har.

Changed in Django 5.2:

funktionen aget_all_permissions() har lagts till.

has_perm(user_obj, perm, obj=None)[source]

ahas_perm(user_obj, perm, obj=None)

Asynkron version: ahas_perm()

Använder get_all_permissions() för att kontrollera om user_obj har behörighetssträngen perm.

Changed in Django 5.2:

funktionen ahas_perm() har lagts till.

class ModelBackend[source]

Detta är den standardautentiseringsbackend som används av Django. Den autentiserar med hjälp av referenser som består av en användaridentifierare och ett lösenord. För Djangos standardanvändarmodell är användaridentifieraren användarnamnet, för anpassade användarmodeller är det fältet som anges av USERNAME_FIELD (se Anpassa användare och autentisering).

Den hanterar också standardbehörighetsmodellen enligt definitionen för User och PermissionsMixin.

has_perm(), get_all_permissions(), get_user_permissions(), och get_group_permissions() tillåter att ett objekt skickas som en parameter för objektspecifika behörigheter, men denna backend implementerar dem inte annat än att returnera en tom uppsättning behörigheter om obj är inte None.

with_perm() tillåter också att ett objekt skickas som en parameter, men till skillnad från andra metoder returnerar den en tom frågeuppsättning om obj är inte None.

authenticate(request, username=None, password=None, **kwargs)[source]

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

Asynkron version: aauthenticate()

Försöker autentisera username med password genom att anropa User.check_password. Om inget username anges försöker den hämta ett användarnamn från kwargs med hjälp av nyckeln CustomUser.USERNAME_FIELD. Returnerar en autentiserad användare eller None.

request är en HttpRequest och kan vara None om den inte tillhandahölls till authenticate() (som skickar den vidare till backend).

Changed in Django 5.2:

funktionen aauthenticate() har lagts till.

get_user_permissions(user_obj, obj=None)[source]

aget_user_permissions(user_obj, obj=None)

Asynkron version: aget_user_permissions()

Returnerar den uppsättning behörighetssträngar som user_obj har från sina egna användarbehörigheter. Returnerar en tom uppsättning om is_anonymous eller is_active är False.

Changed in Django 5.2:

funktionen aget_user_permissions() har lagts till.

get_group_permissions(user_obj, obj=None)[source]

aget_group_permissions(user_obj, obj=None)

Asynkron version: aget_group_permissions()

Returnerar den uppsättning behörighetssträngar som user_obj har från behörigheterna för de grupper de tillhör. Returnerar en tom uppsättning om is_anonymous eller is_active är False.

Changed in Django 5.2:

funktionen aget_group_permissions() har lagts till.

get_all_permissions(user_obj, obj=None)[source]

aget_all_permissions(user_obj, obj=None)

Asynkron version: aget_all_permissions()

Returnerar den uppsättning behörighetssträngar som user_obj har, inklusive både användar- och gruppbehörigheter. Returnerar en tom uppsättning om is_anonymous eller is_active är False.

Changed in Django 5.2:

funktionen aget_all_permissions() har lagts till.

has_perm(user_obj, perm, obj=None)[source]

ahas_perm(user_obj, perm, obj=None)

Asynkron version: ahas_perm()

Använder get_all_permissions() för att kontrollera om user_obj har behörighetssträngen perm. Returnerar False om användaren inte är is_active.

Changed in Django 5.2:

funktionen ahas_perm() har lagts till.

has_module_perms(user_obj, app_label)[source]

ahas_module_perms(user_obj, app_label)

Asynkron version: ahas_module_perms()

Returnerar om user_obj har några behörigheter för appen app_label.

Changed in Django 5.2:

funktionen ahas_module_perms() har lagts till.

user_can_authenticate()[source]

Returnerar om användaren tillåts att autentisera sig. För att matcha beteendet hos AuthenticationForm som förbjuder inaktiva användare från att logga in, returnerar denna metod False för användare med is_active=False. Anpassade användarmodeller som inte har ett fält is_active är tillåtna.

with_perm(perm, is_active=True, include_superusers=True, obj=None)[source]

Returnerar alla aktiva användare som har behörigheten perm antingen i form av "<app label>.<permission codename>" eller en Permission-instans. Returnerar en tom frågeuppsättning om inga användare som har perm hittas.

Om is_active är True (standard) returneras endast aktiva användare, eller om False returneras endast inaktiva användare. Använd None för att returnera alla användare oavsett aktivt tillstånd.

Om include_superusers är True (standard) kommer resultatet att inkludera superanvändare.

class AllowAllUsersModelBackend[source]

Samma som ModelBackend förutom att den inte avvisar inaktiva användare eftersom user_can_authenticate() alltid returnerar True.

När du använder den här backend kommer du sannolikt att vilja anpassa AuthenticationForm som används av LoginView genom att åsidosätta confirm_login_allowed()-metoden eftersom den avvisar inaktiva användare.

class RemoteUserBackend[source]

Använd denna backend för att dra nytta av autentisering som hanteras externt till Django. Den autentiserar med användarnamn som skickas i request.META['REMOTE_USER']. Se dokumentationen Autenticering mot REMOTE_USER.

Om du behöver mer kontroll kan du skapa din egen autentiseringsbackend som ärver från den här klassen och åsidosätta dessa attribut eller metoder:

create_unknown_user

True eller False. Bestämmer om ett användarobjekt skapas eller inte om det inte redan finns i databasen Standardvärdet är True.

authenticate(request, remote_user)[source]

aauthenticate(request, remote_user)

Asynkron version: aauthenticate()

Det användarnamn som anges som remote_user anses vara betrott. Denna metod returnerar användarobjektet med det angivna användarnamnet och skapar ett nytt användarobjekt om create_unknown_user är True.

Returnerar None om create_unknown_user` är False och ett User-objekt med det angivna användarnamnet inte finns i databasen.

request är en HttpRequest och kan vara None om den inte tillhandahölls till authenticate() (som skickar den vidare till backend).

Changed in Django 5.2:

funktionen aauthenticate() har lagts till.

clean_username(username)[source]

Utför eventuell rensning av username (t.ex. borttagning av LDAP DN-information) innan det används för att hämta eller skapa ett användarobjekt. Returnerar det rensade användarnamnet.

configure_user(request, user, created=True)[source]

aconfigure_user(request, user, created=True)

Asynkron version: aconfigure_user()

Konfigurerar användaren vid varje autentiseringsförsök. Den här metoden anropas omedelbart efter att användaren som autentiseras har hämtats eller skapats och kan användas för att utföra anpassade konfigurationsåtgärder, t.ex. att ange användarens grupper baserat på attribut i en LDAP-katalog. Returnerar användarobjektet. När hämtning eller skapande av en användare anropas från en synkron kontext anropas configure_user, aconfigure_user anropas från asynkrona kontexter.

Inställningen kan utföras antingen en gång när användaren skapas (created är True) eller på befintliga användare (created är False) som ett sätt att synkronisera attribut mellan fjärrsystemet och det lokala systemet.

request är en HttpRequest och kan vara None om den inte tillhandahölls till authenticate() (som skickar den vidare till backend).

Changed in Django 5.2:

funktionen aconfigure_user() har lagts till.

user_can_authenticate()

Returnerar om användaren får autentisera sig. Denna metod returnerar False för användare med is_active=False. Anpassade användarmodeller som inte har ett fält is_active är tillåtna.

class AllowAllUsersRemoteUserBackend[source]

Samma som RemoteUserBackend förutom att den inte avvisar inaktiva användare eftersom user_can_authenticate alltid returnerar True.

Verktygsfunktioner

get_user(request)[source]

aget_user(request)

Asynkron version: aget_user()

Returnerar den användarmodellinstans som är associerad med den givna request-sessionen.

Den kontrollerar om den autentiseringsbackend som lagrats i sessionen finns i AUTHENTICATION_BACKENDS. Om så är fallet använder den backendets metod get_user() för att hämta användarmodellens instans och verifierar sedan sessionen genom att anropa användarmodellens metod get_session_auth_hash(). Om verifieringen misslyckas och SECRET_KEY_FALLBACKS tillhandahålls, verifieras sessionen mot varje reservnyckel med get_session_auth_fallback_hash().

Returnerar en instans av AnonymousUser om den autentiseringsbackend som lagras i sessionen inte längre finns i AUTHENTICATION_BACKENDS, om en användare inte returneras av backendets get_user()-metod, eller om sessionens autentiseringshash inte valideras.