Usando o sistema de autenticação Django

Este documento explica a utilização do sistema de autenticações do Django em suas configurações padrões. Estas configurações evoluíram para atender as necessidades mais comuns de um projeto, lidando com uma considerável quantidade de tarefas e implementando cuidadosamente, o uso de senhas e permissões. Para projetos onde o sistema de autenticações demande outras necessidades diferentes das padrões, o Django oferece suporte para uma extensiva customização: extension and customization de autenticação.

A autenticação do Django oferece, tanto autenticação como autorização juntos. Estes serviços são referenciados como “sistema de autenticação” uma vez estas funções são, de alguma forma, interligadas.

Objetos “User”

Os objetos do tipo User são o núcleo do sistema de autenticação. Eles tipicamente representam as pessoas interagindo com seu site e são usados para habilitar coisas como restrinção de acesso, registro de perfis de usuários, associar conteúdo com criadores etc. Somente uma classe de usuário existe no “framework” de autenticação do Django, isto é, usuários 'superusers' ou admin 'staff' são somente objetos do tipo “user” com atributos especiais definidos e não classes diferentes de objetos “user”.

Os atributos primários de usuário padrão são:

Veja a :class:` documentação completa da API <django.contrib.auth.models.User>` para maiores detalhes, a documentação em questão é mais orientada a tarefa.

Criando usuários

A forma mais direta para se criar usuários, é utilizando a função de ajuda inclusa create_user() helper function:

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

# At this point, user is a User object that has already been saved
# to the database. You can continue to change its attributes
# if you want to change other fields.
>>> user.last_name = 'Lennon'
>>> user.save()

Se você tiver a administração do Django instalado, você também pode: ref: ` criar usuários de forma interativa < auth -admin >` .

Criando superusuários

Criando superusuários usando o commando createsuperuser

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

Será solicitada então uma senha. Após inserí-la, a conta de usuário será criada imediatamente. Caso seja desligada a opção:--username ou --email, estes valores serão solicitados.

Mudando as senhas

O Django não armazena senha em sua forma bruta (texto limpo) no modelo do usuário, mas somente um “hash” (see documentação de como as senhas são manipuladas para detalhes completos). Por causa disso, não tente manipular diretamente o atributo “password” do usuário. Este é o porque de uma função auxiliar ser usada para criar um usuário.

Para mudar a senha de usuários, você tem várias opções:

manage.py changepassword *username* offers a method of changing a user’s password from the command line. It prompts you to change the password of a given user which you must enter twice. If they both match, the new password will be changed immediately. If you do not supply a user, the command will attempt to change the password whose username matches the current system user.

Você pode também mudar a senha programaticamente, usando set_password():

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

Se você tiver a administração do Django instalado, você também pode alterar a senha do usuário nas : ref: páginas de administração do ` sistema de autenticação < auth -admin >` .

Django também fornece : ref: ` views < built-in -auth- vistas >` e : ref: ` forms < built-in -auth-forms>` que podem ser utilizados para permitir que os usuários alterem suas próprias senhas.

Mudar a senha de um usuário irá “deslogar” todas as suas sessões. Para detalhes veja ref:session-invalidation-on-password-change.

Autenticando usuários

authenticate(**credentials)[código fonte]

Use a authenticate() para verificar um conjunto de credenciais. Ela recebe as credenciais como argumentos nomeados, username e password para o caso padrão, e os checa com todos os backends de autenticação, e retornar um objeto User se as credenciais forem válidas para um dos backends. Se as credenciais não forem válidas para qualquer um dos “backends” ou se um “backend” emitir uma PermissionDenied, ele retorna None. Por exemplo:

from django.contrib.auth import authenticate
user = authenticate(username='john', password='secret')
if user is not None:
    # A backend authenticated the credentials
else:
    # No backend authenticated the credentials

Nota

Esta é a maneira “baixo nível” para autenticar um grupo de credenciais; por exemplo, é utilizado pela RemoteUserMiddleware. À não ser que você esteja escrevendo seu próprio sistema de autenticação, você provavelmente não utlizará isso. Caso esteja procurando por uma maneira de limitar o acesso do usuário logado, veja o login_required() decorator.

Permissões e Autorização

Django vem com um sistema simples de permissões. Ele fornece uma maneira de atribuir permissões a usuários e grupos de usuários específicos.

É usado pelo site admin Django, mas você é livre para usar em seu próprio código.

O site admin Django usa as seguintes permissões:

  • Acesso para visualizar o formulário “adicionar” e adicionar um objeto é limitado para usuários com a permissão “adicionar” para aquele tipo de objeto.

  • Acesso para visualizar o formulário “editar” e editar um objeto é limitado para usuários com a permissão “editar” para aquele tipo de objeto.

  • Acesso para remover um objeto é limitado para usuários com a permissão “remover” para aquele tipo de objeto.

Permissões podem ser definidas não apenas por tipo de objeto, mas também por instâncias específicas de um objeto. Ao utilizar os métodos has_add_permission(), has_change_permission() e has_delete_permission() oferecidos pela classe ModelAdmin, é posível customizar permissões para diferentes instâncias de objetos do mesmo tipo.

Os objetos da User tem dois campos muitos-para-muitos: groups e user_permissions. Os objetos do tipo User podem acessar seus objetos relacionados da mesma maneira que qualquer outro Django model:

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

Permissões padrão

Quando o django.contrib.auth está listado na sua definição de INSTALLED_APPS, ele se assegurará de três permissões padrão – add, change e delete – serão criadas para cada modelo do Django definido em cada uma das suas aplicações instaladas.

Estas permissões serão criadas quando você rodar manage.py migrate; A primeira vez que você executa o migrate depois de adicionar o django.contrib.auth ao INSTALLED_APPS, as permissões padrão serão criadas para todos os modelos pré-instalados, assim como para qualquer novo modelo sendo instalado naquele momento. Ele irá criar permissões padrão para cada novo modelo cada vez que você rodar manage.py migrate (a função que cria as permissões está conectada ao sinal post_migrate).

Assumindo que você tenha uma aplicação com um app_label foo e um modelo chamado Bar, para testar as permissões básicas você deve usar:

  • Adicionar: user.has_perm('foo.add_bar')

  • mudar: user.has_perm('foo.change_bar')

  • deletar: user.has_perm('foo.delete_bar')

A Permission é raramente acessada diretamente.

Grupos

Os modelos django.contrib.auth.models.Group são uma maneira genérica de categorizar usuários então você pode aplicar permissões, ou alguma outra etiqueta, àqueles usuários. Um usuário pode pertencer a qualquer número de grupos.

Um usuário em um grupo tem automaticamente todas as permissões concedidas àquele grup. Por exemplo, se o grupo Site editors tem uma permissão can_edit_home_page,qualquer usuário naquele grupo terá a permissão.

Além de permissões, grupos são uma maneira conveniente de categorizar usuários para dar a eles uma etiqueta, ou uma funcionalidade estendida. Por exemplo, você pode criar um grupo Special users, e você pode escrever código que poderia, por exemplo, dar a eles acesso a uma parte do seu site somente para membros daquele grupo, ou enviar a eles mensagens de email.

Programaticamente criando permissões

Enquanto que as custom permissions podem ser definidas dentro da classe Meta de um modelo, você pode criar permissões diretamente. Por exemplo, você pode criar a permissão can_publish para um modelo BlogPost em myapp:

from myapp.models import BlogPost
from django.contrib.auth.models import Permission
from django.contrib.contenttypes.models import ContentType

content_type = ContentType.objects.get_for_model(BlogPost)
permission = Permission.objects.create(
    codename='can_publish',
    name='Can Publish Posts',
    content_type=content_type,
)

A permissão pode então ser assinalada ao User através do seu atributo user_permissions ou para um Group através de seu atributo permissions.

Cache de permissões

The ModelBackend caches permissions on the user object after the first time they need to be fetched for a permissions check. This is typically fine for the request-response cycle since permissions aren’t typically checked immediately after they are added (in the admin, for example). If you are adding permissions and checking them immediately afterward, in a test or view for example, the easiest solution is to re-fetch the user from the database. For example:

from django.contrib.auth.models import Permission, User
from django.shortcuts import get_object_or_404

def user_gains_perms(request, user_id):
    user = get_object_or_404(User, pk=user_id)
    # any permission check will cache the current set of permissions
    user.has_perm('myapp.change_bar')

    permission = Permission.objects.get(codename='change_bar')
    user.user_permissions.add(permission)

    # Checking the cached permission set
    user.has_perm('myapp.change_bar')  # False

    # Request new instance of User
    # Be aware that user.refresh_from_db() won't clear the cache.
    user = get_object_or_404(User, pk=user_id)

    # Permission cache is repopulated from the database
    user.has_perm('myapp.change_bar')  # True

    ...

Autenticação em requisições Web

O Django usa sessions e o middleware para vincular o sistema de autenticação dentro dos objetos de requisição.

Isso fornece um atributo request.user para cada requisição que representa o usuário atual. Se o usuário não está “logado”, este atributo será definido como uma instância de AnonymousUser, do contrário ele será uma instância de User.

Você pode distinguí-los com is_authenticated, como a seguir:

if request.user.is_authenticated:
    # Do something for authenticated users.
    ...
else:
    # Do something for anonymous users.
    ...

Como autenticar um usuário

Caso queira adicionar um usuário autenticado à sessão atual - isto pode ser feito com a função login().

login(request, user, backend=None)[código fonte]

Para “logar” um usuário, em uma “view”, use login(). Essa função recebe um objeto HttpRequest e um objeto User. A login() salva o ID do usuário na sessão, usando o framework de sessão do Django.

Note que qualquer dado definido durante um sessão anônima, fica retido na sessão após um usuário logar.

Estes exemplos mostram como é possível utilizar ambas as funções authenticate() e login():

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:
        login(request, user)
        # Redirect to a success page.
        ...
    else:
        # Return an 'invalid login' error message.
        ...

Em versões anteriores, quando você “loga” um usuário manualmente, você deve autenticar com sucesso o usuário com a authenticate() antes de chamar a login(). Agora você pode definir o “backend” usando o novo argumento backend.

Selecionando o “backend” de autenticação

Quando um usuário se “loga” no sistema, o ID do usuário e o “backend” que foi usado para autenticação são salvos na sessão. Isso permite que o mesmo “backend” de autenticação seja usado para retornar detalhes do usuário em uma requisição futura. O “backend” de autenticação a ser salvo na sessão é selecionado da seguinte maneira:

  1. Usa o valor do argumento backend opcional, se fornecido.

  2. Use the value of the user.backend attribute, if present. This allows pairing authenticate() and login(): authenticate() sets the user.backend attribute on the user object it returns.
  3. Use o backend no AUTHENTICATION_BACKENDS, se houver somente um.

  4. Caso contrário, gera uma exceção.

Nos casos 1 e 2, o valor do argumento backend ou do atributo user.backend deve ser uma string com o caminho de importação na notação de pontos (como aquela encontrada em AUTHENTICATION_BACKENDS), e não a classe de “backend” atual.

Como finalizar a sessão de um usuário

logout(request)[código fonte]

Para finalizar a sessão de um usuário que tenha se autenticado via django.contrib.auth.login(), use django.contrib.auth.logout() dentro de sua view. Ele recebe um objeto HttpRequest e não tem um valor de retorno. Exemplo:

from django.contrib.auth import logout

def logout_view(request):
    logout(request)
    # Redirect to a success page.

Repare que a logout() não emiti nenhum erro se o usuário não estiver autenticado.

Quando você chama logout(), os dados da sessão para a requisição atual são completamente apagados. Qualquer dado existente é removido. Isso é feito para prevenir que outra pessoa use o mesmo browser para para se autenticar e ter acesso aos dados da sessão do usuário anterior. Se você quer colocar qualquer coisa na sessão que estará disponível para o usuário imediatamente após ele ter finalizado sua sessão, faça isso depois de chamar django.contrib.auth.logout().

Limitando o acesso de usuários authenticados

A maneira padrão

A maneira simples, padrão para limitar o acesso a páginas é verificar request.user.is_authenticated e talvez redirecionar para uma página de login:

from django.conf import settings
from django.shortcuts import redirect

def my_view(request):
    if not request.user.is_authenticated:
        return redirect('%s?next=%s' % (settings.LOGIN_URL, request.path))
    # ...

... ou mostrar uma mensagem de erro:

from django.shortcuts import render

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

O login_required decorator

login_required(redirect_field_name='next', login_url=None)[código fonte]

Como atalho, você pode usar o decorador conveniente login_required()

from django.contrib.auth.decorators import login_required

@login_required
def my_view(request):
    ...

A login_required() faz o seguinte:

  • Se o usuário não registrou seu acesso, redireciona para settings.LOGIN_URL, passando caminho absoluto corrente na “querystring”. Example: /accounts/login/?next=/polls/3/.

  • Se o usuário está autenticado, executa a “view” normalmente. O código da “view” é livre para assumir que o usuário está autenticado.

Por padrão, o caminho para o qual o usuário deve ser redirecionado após a autenticação está armazenado em um parâmetro na “query string” chamado "next". Se preferir usar um outro nome para este parâmetro, a login_required() recebe um parâmetro adicional redirect_field_name:

from django.contrib.auth.decorators import login_required

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

Repare que se você fornecer um valor para redirect_field_name, você deverá também personalizar seus templates de login, já que a variável de contexto do template a qual armazena o caminho de redirecionamento irá usar o valor de redirect_field_name como sua chave ao invés de "next" (o padrão).

A login_required() também receve um parâmetro adicional chamado login_url. Example:

from django.contrib.auth.decorators import login_required

@login_required(login_url='/accounts/login/')
def my_view(request):
    ...

Repare que se você não especificar o parâmetro login_url, terá que ter certeza que o settings.LOGIN_URL e sua “view” de login estão associados corretamente. Por exemplo, usando os padrões, adicione a seguinte linha ao seu URLconf:

from django.contrib.auth import views as auth_views

url(r'^accounts/login/$', auth_views.login),

A settings.LOGIN_URL também aceita nome de funções “view”e named URL patterns. Isso permite a você mapear livremente sua “view” de login dentro do URconf sem ter que atualizar o arquivo de definições.

Nota

O decorador login_required não verifica o indicado is_active no usuário, mas a definição padrão de AUTHENTICATION_BACKENDS rejeita usuários inativos.

Ver também

Se estiver escrevendo “views” personalizadas para o admin do Django ( ou precisa da mesma verificação de autorização que as “views” embutidas usam), talvez ache a função decoradora django.contrib.admin.views.decorators.staff_member_required() uma alternativa útil para o login_required().

O LoginRequired mixin

Quando usar class-based views, você pode ter o mesmo comportamento que o login_required usando o LoginRequiredMixin. Este “mixin” deve estar na última posição mais a esquerda na lista de herança.

class LoginRequiredMixin

Se a “view” estiver usando o “mixin”, todos as requisições de usuário não autenticados serão redirecionadas para a página de login ou mostram um erro de falta de permissão HTTP 403, dependendo da definição do parâmetro raise_exception.

Você pode definir qualquer dos parâmetros da AccessMixin para personalizar a maneira como o sistema lida com usuários não autorizados:

from django.contrib.auth.mixins import LoginRequiredMixin

class MyView(LoginRequiredMixin, View):
    login_url = '/login/'
    redirect_field_name = 'redirect_to'

Nota

Tal como o decorador login_required, este “mixin” não verifica o indicador is_active do usuário, mas o padrão dos AUTHENTICATION_BACKENDS é rejeitar usuário inativos.

Limitando o acesso de usuários autenticados que passam no teste.

Para limitar o acesso baseado em certas permissões ou outros testes, você deve fazer o mesmo que foi descrito na seção anterior.

A maneira mais simples é executar seu teste no request.user diretamente dentro da “view”. Por exemplo, essa “view” assegura que o usuário tem um email no domínio específico e caso contrário, redireciona para a página de autenticação.

from django.shortcuts import redirect

def my_view(request):
    if not request.user.email.endswith('@example.com'):
        return redirect('/login/?next=%s' % request.path)
    # ...
user_passes_test(test_func, login_url=None, redirect_field_name='next')[código fonte]

Como atalho, você pode usar o conveniente decorador user_passes_test o qual executa um redirecionamento quando a função passada retorna False:

from django.contrib.auth.decorators import user_passes_test

def email_check(user):
    return user.email.endswith('@example.com')

@user_passes_test(email_check)
def my_view(request):
    ...

A user_passes_test() recebe um argumento obrigatório: um executável que recebe um objeto do tipo User e retorna True se é permitido ao usuário acessar a página. Note que a user_passes_test() não verifica automaticamente se o User não é anônimo.

A user_passes_test() pode receber dois argumentos opcionais:

login_url

Permite que você especifique a URL para a qual os usuários que não passam no teste sejam redirecionados. Pode ser uma página de autenticação e seu padrão é o que estiver definido em settings.LOGIN_URL se você não especificar nenhum.

redirect_field_name

O mesmo que login_required(). Se definido como None ele será removido da URL, o que você talvez queira que aconteça se você estiver redirecionando usuários que não passem no teste para uma página que não é a de autenticação e que não tenha o “next page”.

Por exemplo:

@user_passes_test(email_check, login_url='/login/')
def my_view(request):
    ...
class UserPassesTestMixin

Quando usar as “views” baseadas em classes, você pode usar o UserPassesTestMixin para isso.

test_func()

Você tem que sobrescrever o método test_func() da classe para fornecer o teste a ser executado. Mais ainda, você pode definir qualquer dos parâmetros da AccessMixin para personalizar a manipulação de usuários não autorizados:

from django.contrib.auth.mixins import UserPassesTestMixin

class MyView(UserPassesTestMixin, View):

    def test_func(self):
        return self.request.user.email.endswith('@example.com')
get_test_func()

Você pode também sobrescrever o método get_test_func() para que seja possível para o “mixin” usar um nome de função diferente para suas verificações (ao invés de test_func()).

Empilhando UserPassesTestMixin

Devido a maneira que o UserPassesTestMixin foi implementado, você não pode empilhá-las na sua lista de heranças. O que está descrito a seguir não funciona:

class TestMixin1(UserPassesTestMixin):
    def test_func(self):
        return self.request.user.email.endswith('@example.com')

class TestMixin2(UserPassesTestMixin):
    def test_func(self):
        return self.request.user.username.startswith('django')

class MyView(TestMixin1, TestMixin2, View):
    ...

Se o TestMixin1 deve chamar o super() e leva o resultado em conta, o TestMixin1 não irá mais funcionar de maneira independente.

O permission_required decorator

permission_required(perm, login_url=None, raise_exception=False)[código fonte]

Verificar se um usuário tem uma permissão é uma tarefa relativamente comum. Por essa razão, o Django fornece um atalho para este caso: o decorador permission_required().:

from django.contrib.auth.decorators import permission_required

@permission_required('polls.can_vote')
def my_view(request):
    ...

Tal como o método has_perm(), os nomes de permissões ficam no formato "<app label>.<permission codename>" (isto é polls.can_vote para uma permissão de um modelo da aplicação polls).

O decorador pode também receber um iterável de permissões, e neste caso o usuário deve ter todas as permissões para acessar a “view”.

Note que a permission_required() também recebe um parâmetro login_url opcional:

from django.contrib.auth.decorators import permission_required

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

Assim como no decorador login_required(), o padrão para login_url é a definição de settings.LOGIN_URL.

Se o parâmetro raise_exception é fornecido, o decorador irá emitir um PermissionDenied, mostrando o the 403 (HTTP Forbidden) view ao invés de redirecionar para uma página de autenticação.

Se quiser usar o raise_exception mas também dar aos usuários a chance de se autenticar, você pode adicionar o decorador login_required():

from django.contrib.auth.decorators import login_required, permission_required

@login_required
@permission_required('polls.can_vote', raise_exception=True)
def my_view(request):
    ...

Nas versões anteriores, o parâmetro permission somente trabalhava com strings, listas e tuplas ao invés de strings e qualquer iterável.

O PermissionRequiredMixin mixin

Para aplicar verificações de permissões a “views” baseadas em classes, você pode usar o PermissionRequiredMixin:

class PermissionRequiredMixin

Este “mixin”, tal como o decorador permission_required, verifica se o usuário que está acessando a “view” tem todas as permissões. Você deve especificar as permissões (ou um iterável de permissões) usando o parâmetro permission_required:

from django.contrib.auth.mixins import PermissionRequiredMixin

class MyView(PermissionRequiredMixin, View):
    permission_required = 'polls.can_vote'
    # Or multiple of permissions:
    permission_required = ('polls.can_open', 'polls.can_edit')

Você pode definir qualquer um dos parâmetros da AccessMixin para personalizar o tratamento de usuários não autorizados.

Você pode também sobrescrever estes métodos:

get_permission_required()

Retorna um iterável de nomes de permissões usados pelo “mixin”. O padrão é o que está definido no atributo permission_required, convertido para uma tupla se necessário.

has_permission()

Retorna um booleano informando se o usuário corrente tem permissão para executar a “view” decorada. Por padrão, ele retorna o resultado da chamado do has_perms() com uma lista de permissões retornada pelo get_permission_required().

Redirecionando requisições não autorizadas em “views” baseadas em classes

Para facilitar o tratamento de restrições de acesso em “views” baseadas em classes, pode ser usado o AccessMixin para redirecionar o usuário para a página de autenticação ou retornar uma resposta HTTP 403 de acesso não autorizado.

class AccessMixin
login_url

O valor padrão retornado pelo get_login_url(). O padrão é None e neste caso o get_login_url() vai retornar o que estiver definido em settings.LOGIN_URL.

permission_denied_message

Valor padrão retornado por get_permission_denied_message(). O padrão original é uma string vazia.

redirect_field_name

Valor padrão retornado por get_redirect_field_name(). Padrão original é "next".

raise_exception

Se o atributo estiver definido como True, uma excessão do tipo PermissionDenied será emitida ao invés de redirecionar. O valor padrão é False.

get_login_url()

Retorna a URL para qual usuários que não passam no teste serão redirecionados. Retorna login_url se estiver definido, ou caso contrário settings.LOGIN_URL.

get_permission_denied_message()

Quando raise_exception for True (verdadeiro), este método poderá ser usado para controlar a mensagem de erro que será enviada ao manipulador de erros (error handler), para que ele a exiba para o usuário. Por padrão, esse método retorna permission_denied_message

get_redirect_field_name()

Retorna o nome do parâmetro de consulta (query) que terá a URL para onde o usuário será redirecionado, depois de ter logado com sucesso. Se você o setar como “None”, o parâmetro de consulta (query) não será adicionado. Retorna redirect_field_name attribute por padrão.

handle_no_permission()

Dependendo do valor de raise_exception, ou o método irá levantar a seguinte exeção: ,:exc:`~django.core.exceptions.PermissionDenied` exception, ou então, o método redirecionará o usuário para a login_url, podendo, opcionalmente, incluir o redirect_field_name, caso ele esteja definido.

Invalidação de Sessão após a Troca de Senha.

A verificação de sessões é habilitada e mandatório no Django 1.10 (não tem como desabilitá-la) independente se o SessionAuthenticationMiddleware está habilitado. Em versões anteriores, esta proteção somente era aplicada se o django.contrib.auth.middleware.SessionAuthenticationMiddleware` estivesse habilitado no MIDDLEWARE.

Se a classe definida em AUTH_USER_MODEL herda de AbstractBaseUser ou implementa seu próprio método get_session_auth_hash(), as sessões que forem autenticadas incluirão o “hash” retornado pelo método. No caso do AbstractBaseUser, o valor do “hash” é um HMAC da senha. O O Django verifica o “hash” na sessão para cada requisição comparando com o “hash” calculado durante a requisição. Isso permite ao usuário cancelar sua autenticação de todas as suas sessões quando altera sua senha.

As “views” padrão para mudança de senha que são fornecidas com o Django, password_change() e a “view” user_change_password no admin django.contrib.auth, atualizam a sessão com o novo “hash” de modo que o usuário que altera sua própria senha não terá sua sessão invalidada. Se você tem uma “view” personalizada para mudança de senha e quer ter um comportamento parecido, use a função update_session_auth_hash(). Neste caso, porém, se um usuário quer também invalidar a sessão que é a mesma está sendo usada para alterar a senha (por exemplo, se ele acredita que o “cookie” de sessão foi roubado), então ele precisa de finalizar aquela sessão.

update_session_auth_hash(request, user)[código fonte]

Essa função pega a requisição atual e, o objeto de usuario atualizado (do qual a o novo hash de sessão será derivado) e atualiza o hash de sessão apropriadamente. Exemplo de uso:

from django.contrib.auth import update_session_auth_hash

def password_change(request):
    if request.method == 'POST':
        form = PasswordChangeForm(user=request.user, data=request.POST)
        if form.is_valid():
            form.save()
            update_session_auth_hash(request, form.user)
    else:
        ...

Nota

get_session_auth_hash() é baseado em SECRET_KEY. Sendo assim, você invalidará todas as sessões existentes, sempre que atualizar seu site para utilizar um novo segredo.

Views de autenticação

O Django disponibiliza várias views que você pode utilizar para lidar com login (autenticação), logout (saída), e alteração de senhas. Essas views fazem uso dos stock auth forms, porém, você pode passar/utilizar seus próprios forms (formulários), caso prefira.

O Django não disponibiliza um template padrão para as views de autenticação. Você deve criar seus próprios templates para as views que quiser uitlizar. O contexto do template está documentado em cada view. veja: Todas as views de autenticação.

Usando as views

Existem formas diferentes de implementar essas views em seu projeto. A mais fácil delas é: incluir a URLconf disponível em django.contrib.auth.urls dentro da sua própria URLconf. Por exemplo:

urlpatterns = [
    url('^', include('django.contrib.auth.urls')),
]

Isto incluirá os seguintes padrões de URL:

^login/$ [name='login']
^logout/$ [name='logout']
^password_change/$ [name='password_change']
^password_change/done/$ [name='password_change_done']
^password_reset/$ [name='password_reset']
^password_reset/done/$ [name='password_reset_done']
^reset/(?P<uidb64>[0-9A-Za-z_\-]+)/(?P<token>[0-9A-Za-z]{1,13}-[0-9A-Za-z]{1,20})/$ [name='password_reset_confirm']
^reset/done/$ [name='password_reset_complete']

As views disponibilizam um nome de URL, para serem referênciadas com mais facilidade. Veja the URL documentation para mais detalhes sobre como usar padrões de URL nomeados.

Caso queira ter mais controle sobre suas URLs, você pode referenciar uma view específica em seu URLconf:

from django.contrib.auth import views as auth_views

urlpatterns = [
    url('^change-password/$', auth_views.password_change),
]

As views tem argumentos opcionais que podem ser utilizados para alterar o comportamento delas. Por exemplo, para mudar o nome do template de uma view, basta passar o argumento template_name. Uma maneira de fazer isso, é colocando **kwargs (argumentos de palvras chave) no seu URLconf. Estes argumentos serão passados para a view. Por exemplo:

urlpatterns = [
    url(
        '^change-password/$',
        auth_views.password_change,
        {'template_name': 'change-password.html'}
    ),
]

Todas as views retornam uma instancia da TemplateResponse. Essa instância te permite customizar, com facilidade, os dados da resposta, antes de serem renderizados. Uma maneira de fazer isso, é empacotando uma view dentro de sua própria view:

from django.contrib.auth import views

def change_password(request):
    template_response = views.password_change(request)
    # Do something with `template_response`
    return template_response

Para mais detalhes, veja o TemplateResponse documentation.

Todas as views de autenticação

Essa é uma lista com todas as views que django.contrib.auth disponibiliza. Para detalhes de implementação, veja Usando as views.

login(request, template_name=`registration/login.html`, redirect_field_name='next', authentication_form=AuthenticationForm, current_app=None, extra_context=None, redirect_authenticated_user=False)

Nome da URL: login

Para detalhes sobre como usar padrões de URLs nomeadas, veja: the URL documentation

Argumentos opcionais:

  • template_name: O nome de um template que será usado para mostrar a view utilizada para logar o usuário. Por padrão é registration/login.html.

  • redirect_field_name: O nome de um campo GET que tem a URL para qual o usuário será redirecionado após o logar. Por padrão é next.

  • authentication_form: Um callable/chamável (geralmente uma classe de formulário) que será usado para a autenticação. Por padrão, é AuthenticationForm.

  • current_app: Uma dica (hint) que diz qual aplicação contém a view atual. Para mais informações, veja: namespaced URL resolution strategy .

  • extra_context: Um dicionário de dados de contexto que serão adicionados aos dados de contexto padrão passados para o template.

  • redirect_authenticated_user: Um booleano (True ou False), que indica se os usuários autenticados, ao acessar a pagina de login, devem ser redirecionados ou não (como se tivessem acabado de logar). Por padrão, é False.

    Aviso

    Se você habilitar o redirect_authenticated_user, outros websites podem ser capazes de determinar se os visitantes estão autenticados no seu site solicitando URLs de redirecionamento para arquivos de imagem no seu site. Para evitar esse vazamento de informações de “impressões digitais em midias sociais”, hospede todas as imagens e seu favicon em um domínio separado.

Obsoleto desde a versão 1.9: O parâmetro current_app está obsoleto, e será removido na versão 2.0 do Django. Os chamadores (callers) agora devem chamar request.current_app no lugar de current_app.

O parâmetro redirect_authenticated_user foi adicionado.

Isto é o que django.contrib.auth.views.login faz:

  • Se for chamado via GET, ele mostrará um formulário de login que enviará um POST para a mesma URL. Explicaremos isso melhor em um instante.

  • Se for chamado via POST, com as credenciais enviadas pelo usuário, ele vai tentar logar o usuário. Se o login der certo, a view irá redirecionar para a URL especificada em next. Se next não tiver sido definido, então a view redirecionará para settings.LOGIN_REDIRECT_URL (which defaults to /accounts/profile/). Se o login não der certo, o formulário de login será exibido novamente.

A responsabilidade de colocar o html, para o template de login, é toda sua. Esse template se chama registration/login.html por padrão. Ele recebe 4 variáveis de contexto de template.

  • form: Um objeto Form que representa a AuthenticationForm.

  • next: A URL para a qual será redirecionado depois de uma autenticação bem sucedida. Esta pode conter também uma “query string”.

  • site: A current Site atual, de acordo com a configuração SITE_ID. Se você não tiver o framework de sites instalado, então site será definido como uma instância da classe of RequestSite, que pegará o nome e o domínio do site da HttpRequest atual.

  • site_name: Um alias/atalho para site.name. Se você não tiver o framework de sites instalado, então site_name receberá o valor de de request.META['SERVER_NAME']. Para mais informações sobre sites, veja The “sites” framework.

Se você preferir não chamar o template registration/login.html, você pode passar o parâmetro template_name como argumento extra para view, no seu URLconf. Por exemplo, essa linha de URLconf usaria myapp/login.html ao invés de registration/login.html:

url(r'^accounts/login/$', auth_views.login, {'template_name': 'myapp/login.html'}),

Você pode também escolher o nome do campo GET que contém a URL para a qual o usuário será redirecionado após logar. Para isso, você deve passar redirect_field_name para a view`. Por padrão, esse campo se chamará next.

Você pode usar o seguinte exemplo de template registration/login.html como ponto de partida. Esse exemplo assume que você tenha um template base.html que defina um bloco content:

{% extends "base.html" %}

{% block content %}

{% if form.errors %}
<p>Your username and password didn't match. Please try again.</p>
{% endif %}

{% if next %}
    {% if user.is_authenticated %}
    <p>Your account doesn't have access to this page. To proceed,
    please login with an account that has access.</p>
    {% else %}
    <p>Please login to see this page.</p>
    {% endif %}
{% endif %}

<form method="post" action="{% url 'login' %}">
{% csrf_token %}
<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>

{# Assumes you setup the password_reset view in your URLconf #}
<p><a href="{% url 'password_reset' %}">Lost password?</a></p>

{% endblock %}

Se você tem uma autenticação personalizada (veja Autenticação Personalizada) você pode passar um formulário de autenticação personalizado para a “view” de login através do parâmetro authentication_form. Este formulário deve aceitar um parâmetro nomeado chamado request no seu método __init__, e fornecer um método get_user() o qual retorna um objeto do tipo User autenticado (este método somente é chamado após a validação bem sucedida do formulário).

logout(request, next_page=None, template_name='registration/logged_out.html', redirect_field_name='next', current_app=None, extra_context=None)

Desloga um usuário.

Nome da URL: logout

Argumentos opcionais:

  • next_page: A URL para a qual o usuário será redirecionado após deslogar. Se não for informada, será definida como settings.LOGOUT_REDIRECT_URL por padrão.

  • template_name: O nome completo de um template que será exibido após deslogar o usuário. Será definido como registration/logged_out.html por padrão, caso nenhum argumento seja enviado.

  • redirect_field_name: O nome de um campo GET que contém a URL para qual o usuário será redirecionado após deslogar. Se esse parâmetro não for passado, então ele utilizará o valor de next por padrão. Caso esse parâmetro seja passado, ele substituirá a URL next_page.

  • current_app: Uma dica (hint) que diz qual aplicação contém a view atual. Para mais informações, veja: namespaced URL resolution strategy .

  • extra_context: Um dicionário de dados de contexto que serão adicionados aos dados de contexto padrão passados para o template.

Obsoleto desde a versão 1.9: O parâmetro current_app está obsoleto, e será removido na versão 2.0 do Django. Os chamadores (callers) agora devem chamar request.current_app no lugar de current_app.

Contexto de Template:

  • title: Versão localizada da string “Logged out” (deslogado). Ou seja, você pode substituir “Logged out” por uma versão traduziada (como deslogado) para o idioma que desejar.

  • site: A current Site atual, de acordo com a configuração SITE_ID. Se você não tiver o framework de sites instalado, então site será definido como uma instância da classe of RequestSite, que pegará o nome e o domínio do site da HttpRequest atual.

  • site_name: Um alias/atalho para site.name. Se você não tiver o framework de sites instalado, então site_name receberá o valor de de request.META['SERVER_NAME']. Para mais informações sobre sites, veja The “sites” framework.

logout_then_login(request, login_url=None, current_app=None, extra_context=None)

Desloga um usuário e redireciona para a página de login.

Nome da URL: não é fornecido uma URL padrão.

Argumentos opcionais:

  • login_url: a URL da página de login, para onde o usuário deve ser redirecionado. Caso esse parâmetro não seja passado, ele irá tomar o o valor settings.LOGIN_URL por padrão.

  • current_app: Uma dica (hint) que diz qual aplicação contém a view atual. Para mais informações, veja: namespaced URL resolution strategy .

  • extra_context: Um dicionário de dados de contexto que serão adicionados aos dados de contexto padrão passados para o template.

Obsoleto desde a versão 1.9: O parâmetro current_app está obsoleto, e será removido na versão 2.0 do Django. Os chamadores (callers) agora devem chamar request.current_app no lugar de current_app.

password_change(request, template_name='registration/password_change_form.html', post_change_redirect=None, password_change_form=PasswordChangeForm, current_app=None, extra_context=None)

Permite a um usuário alterar sua senha.

Nome da URL: password_change

Argumentos opcionais:

  • template_name: O nome completo de um template que será usado para exibir o formulário de alteração de senha. Caso esse parâmetro não seja passado, ele utilizará o valor registration/password_change_form.html por padrão.

  • post_change_redirect: A URL para qual o usuário será redirecionado após ter alterado sua senha com sucesso.

  • password_change_form: Um formulário de alteração de senha personalizado. Ele deverá aceitar um kwarg (argumento de palavra chave) user. O formulário é responsável por, de fato, alterar as senhas dos usuários. Valor padrão: PasswordChangeForm.

  • current_app: Uma dica (hint) que diz qual aplicação contém a view atual. Para mais informações, veja: namespaced URL resolution strategy .

  • extra_context: Um dicionário de dados de contexto que serão adicionados aos dados de contexto padrão passados para o template.

Obsoleto desde a versão 1.9: O parâmetro current_app está obsoleto, e será removido na versão 2.0 do Django. Os chamadores (callers) agora devem chamar request.current_app no lugar de current_app.

Contexto de Template:

  • form: O formulário de alteração de senha. (veja password_change_form, logo acima).

password_change_done(request, template_name='registration/password_change_done.html', current_app=None, extra_context=None)

A pagina que é exibida após um usuário ter alterado sua senha.

Nome da URL: password_change_done

Argumentos opcionais:

  • template_name: O nome completo do template que será utilizado. Por padrão: registration/password_change_done.html

  • current_app: Uma dica (hint) que diz qual aplicação contém a view atual. Para mais informações, veja: namespaced URL resolution strategy .

  • extra_context: Um dicionário de dados de contexto que serão adicionados aos dados de contexto padrão passados para o template.

Obsoleto desde a versão 1.9: O parâmetro current_app está obsoleto, e será removido na versão 2.0 do Django. Os chamadores (callers) agora devem chamar request.current_app no lugar de current_app.

password_reset(request, template_name='registration/password_reset_form.html', email_template_name='registration/password_reset_email.html', subject_template_name='registration/password_reset_subject.txt', password_reset_form=PasswordResetForm, token_generator=default_token_generator, post_reset_redirect=None, from_email=None, current_app=None, extra_context=None, html_email_template_name=None, extra_email_context=None)

Gera um link de uso único, que permite o usuário cadastrar uma nova senha. Esse link será enviado para o e-mail do usuário.

A view não enviará nenhum e-mail, se o endereço de e-mail informado não estiver cadastrado no sistema. Atenção: A view não informará ao usuário que aquele endereço de e-mail não existe! Pois sem essa menssagem de erro, crackers - hackers do mal - terão mais dificuldades de conseguir informações sobre o sistema. Caso você prefira exibir uma menssagem de erro mesmo assim, você criar uma subclasse de PasswordResetForm e utilizar o argumento password_reset_form.

Usuários que estiverem com senhas inutilizáveis (veja set_unusable_password()) não podem solicitar um reset de senha (descrito acima). Pois isso resultaria em um uso inadequado dessa função, quando o usuário estivesse usando uma fonte externa de autenticação, como LDAP. Atenção: O usuário não receberá nenhuma menssagem de erro, pois essa menssagem revelaria a crackers - hackers do mal - que o usuário tem uma conta. Porém, o e-mail para alteração de senha também não será enviado.

Nome da URL: password_reset

Argumentos opcionais:

  • template_name: O nome completo do template que será utilizado para exibir o formulário de redefinição (reset) de senha. Por padrão: registration/password_reset_form.html.

  • email_template_name: O nome completo do template que será utilizado para gerar a menssagem de e-mail com o link de redefinição (reset) de senha. Por padrão: registration/password_reset_email.html

  • subject_template_name: O nome completo do template que será utilizado para definir o assunto do e-mail. (do e-mail com o link para redefinição/reset de senha). Por padrão: registration/password_reset_subject.txt

  • password_reset_form: Formulário que será usado para pegar o e-mail do usuário que quer redefinir/resetar a senha. Por padrão: PasswordResetForm.

  • token_generator: Instância da classe que confere o link de redefinição/reset de senha. Ele é definido como default_token_generator por padrão, que é uma instancia do django.contrib.auth.tokens.PasswordResetTokenGenerator.

  • post_reset_redirect: A URL para a qual o usuário será redirecionado após ter solicitado, com sucesso, a redefinição/reset de sua senha.

  • from_email: Um endereço de e-mail válido (que será utilizado para enviar os e-mails de recuperação de senha para o usuário). Por padrão: setting:DEFAULT_FROM_EMAIL.

  • current_app: Uma dica (hint) que diz qual aplicação contém a view atual. Para mais informações, veja: namespaced URL resolution strategy .

  • extra_context: Um dicionário de dados de contexto que serão adicionados aos dados de contexto padrão passados para o template.

  • html_email_template_name: O nome completo do “template” que será usado para gerar um email do tipo “multipart” text/html com o link para resetar a senha. Por padrão, email no formato HTML não é enviado.

  • extra_email_context: Um dicionário de dados de contexto que estarão disponíveis no “template” do email.

Obsoleto desde a versão 1.9: O parâmetro current_app está obsoleto, e será removido na versão 2.0 do Django. Os chamadores (callers) agora devem chamar request.current_app no lugar de current_app.

O parâmetro extra_email_context` foi adicionado

Contexto de Template:

  • form: O fomuláriohe (veja acima o password_reset_form) para resetar a senha do usuário.

O contexto do template do email:

  • email: um apelido para user.email

  • user: o usuário do tipo User, de acordo com o campo do email do formulário. Somente usuários ativos conseguem resetar suas senhas (User.is_active is True).

  • site_name: Um alias/atalho para site.name. Se você não tiver o framework de sites instalado, então site_name receberá o valor de de request.META['SERVER_NAME']. Para mais informações sobre sites, veja The “sites” framework.

  • domain: um apelido para site.domain. Se você não tem o framework “site” instalado, este parâmetro será setado com o valor do request.get_host().

  • protocol: http ou https

  • uid: a chave primária do usuário codificada em base 64

  • token: o “Token” para verificar se o link de reset é valido.

Exemplo de registration/password_reset_email.html (template do corpo do email):

Someone asked for password reset for email {{ email }}. Follow the link below:
{{ protocol}}://{{ domain }}{% url 'password_reset_confirm' uidb64=uid token=token %}

O mesmo contexto de template é usado para o template do assunto. O assunto de ser uma única em uma string de texto plano.

password_reset_done(request, template_name='registration/password_reset_done.html', current_app=None, extra_context=None)

A página que é mostrada depois de enviado o email com link para resetar a senha. Esta “view” é chamado por padrão se a “view” password_reset() não tiver uma definição explicita para o post_reset_redirect URL.

Nome da URL: password_reset_done

Nota

Se o endereço de email não existir no sistema, ou o usuário for inativo, ou ainda se a senha é inutilizável, o usuário será redirecionado para esta “view” mas nenhum email será enviado.

Argumentos opcionais:

  • template_name: o nome completo do template a ser usado. Se não fornecido, será usado o padrão definido como registration/password_reset_done.html.

  • current_app: Uma dica (hint) que diz qual aplicação contém a view atual. Para mais informações, veja: namespaced URL resolution strategy .

  • extra_context: Um dicionário de dados de contexto que serão adicionados aos dados de contexto padrão passados para o template.

Obsoleto desde a versão 1.9: O parâmetro current_app está obsoleto, e será removido na versão 2.0 do Django. Os chamadores (callers) agora devem chamar request.current_app no lugar de current_app.

password_reset_confirm(request, uidb64=None, token=None, template_name='registration/password_reset_confirm.html', token_generator=default_token_generator, set_password_form=SetPasswordForm, post_reset_redirect=None, current_app=None, extra_context=None)

Apresenta uma formulário para informar uma nova senha.

Nome da URL: password_reset_confirm

Argumentos opcionais:

  • uidb64: O id do usuário é codificado em base 64. O padrão é None.

  • token: “Token”para verificação de senha válida. Padrão é None.

  • template_name: O nome completo do template para mostrar a “view” de confirmação de senha. O valor padrão é registration/password_reset_confirm.html.

  • token_generator: Instância da classe que verifica a senha. O valor padrão é default_token_generator, e este é uma intância de django.contrib.auth.tokens.PasswordResetTokenGenerator.

  • set_password_form: O formulário que será usado para definir a senha. O valor padrão é SetPasswordForm

  • post_reset_redirect: URL para a qual o usuário é redirecionado após resetar a senha. O valor padrão é None.

  • current_app: Uma dica (hint) que diz qual aplicação contém a view atual. Para mais informações, veja: namespaced URL resolution strategy .

  • extra_context: Um dicionário de dados de contexto que serão adicionados aos dados de contexto padrão passados para o template.

Contexto de Template:

  • form: O formulário (veja acima set_password_form) para definir a senha do novo usuário.

  • validlink: Boolenano, verdadeiro se o link (combinação de uidb64 e token) é válido ou ainda não utilizado.

Obsoleto desde a versão 1.9: O parâmetro current_app está obsoleto, e será removido na versão 2.0 do Django. Os chamadores (callers) agora devem chamar request.current_app no lugar de current_app.

password_reset_complete(request, template_name='registration/password_reset_complete.html', current_app=None, extra_context=None)

Apresentando a “view” a qual informa ao usuário que sua senha foi alterada com sucesso.

Nome da URL: password_reset_complete

Argumentos opcionais:

  • template_name: o nome completo do template que mostra a “view”. O valor padrão é registration/password_reset_complete.html.

  • current_app: Uma dica (hint) que diz qual aplicação contém a view atual. Para mais informações, veja: namespaced URL resolution strategy .

  • extra_context: Um dicionário de dados de contexto que serão adicionados aos dados de contexto padrão passados para o template.

Obsoleto desde a versão 1.9: O parâmetro current_app está obsoleto, e será removido na versão 2.0 do Django. Os chamadores (callers) agora devem chamar request.current_app no lugar de current_app.

Funções auxiliares

redirect_to_login(next, login_url=None, redirect_field_name='next')

Redireciona para a página de autenticação, e então retornar a outra URL depois de uma autenticação com sucesso.

Argumentos requeridos:

  • next: URL para a qual é redirecionado depois de uma autenticação bem sucedida.

Argumentos opcionais:

  • login_url: a URL da página de login, para onde o usuário deve ser redirecionado. Caso esse parâmetro não seja passado, ele irá tomar o o valor settings.LOGIN_URL por padrão.

  • redirect_field_name: o nome de um campo GET contendo a URL para a qual é redirecionado depois de finalizar a seção autenticada. Substitui o next se o dado parâmetro do GET for passado.

Formulários embutidos

Caso não queira utilizar a “views” embutidas no Django, mas quer a conveniência de não escrever formulários para esta funcionalidade, o sistema de autenticação fornece vários formulários prontos localizados em django.contrib.auth.forms:

Nota

The built-in authentication forms make certain assumptions about the user model that they are working with. If you’re using a custom user model, it may be necessary to define your own forms for the authentication system. For more information, refer to the documentation about using the built-in authentication forms with custom user models.

class AdminPasswordChangeForm

Um formulário usado na interface do “admin” para alterar a senha do usuário.

Recebe o user como primeiro argumento posicional.

class AuthenticationForm

Um formulário para autenticar o usuário.

Recebe o request como seu primeiro parâmetro posicional, o qual é armazenado na instância do formulário para ser usado pelas sub-classes.

confirm_login_allowed(user)

Por padrão, o AuthenticationForm rejeita usuários que tenham o indicador is_active definido como False. Você pode alterar este comportamento com uma regra personalizada para determinar quais usuários podem se autenticar. Faça isso com um formulário personalizado que herda a AuthenticationForm e sobreescreve o método confirm_login_allowed(). Este método deve emitir uma ValidationError se o usuário fornecido não deve ser autenticado.

Por exemplo, para permitir que todos os usuários se autentiquem independente do status “active”:

from django.contrib.auth.forms import AuthenticationForm

class AuthenticationFormWithInactiveUsersOkay(AuthenticationForm):
    def confirm_login_allowed(self, user):
        pass

(neste caso, você precisa usar também um “backend” de autenticação que permita usuários inativos, tal como o AllowAllUsersModelBackend.)

Ou para permitir somente alguns usuários ativos a se autenticarem:

class PickyAuthenticationForm(AuthenticationForm):
    def confirm_login_allowed(self, user):
        if not user.is_active:
            raise forms.ValidationError(
                _("This account is inactive."),
                code='inactive',
            )
        if user.username.startswith('b'):
            raise forms.ValidationError(
                _("Sorry, accounts starting with 'b' aren't welcome here."),
                code='no_b_users',
            )
class PasswordChangeForm

Um formulário para permitir que o usuário altere sua senha.

class PasswordResetForm

Um formulário para gerar e enviar um email com um link de uso único para resetar a senha do usuário.

send_email(subject_template_name, email_template_name, context, from_email, to_email, html_email_template_name=None)

Usa os argumentos para enviar um EmailMultiAlternatives. Pode ser sobrescrito para personalizar como o email é enviado para o usuário.

Parâmetros:
  • subject_template_name – O template para o assunto.
  • email_template_name – O template para o corpo do email.
  • context – O contexto passado para o subject_template, email_template, e para o html_email_template (se não for None).
  • from_email – O email do remetente.
  • to_email – O email do usuário que requisitou.
  • html_email_template_name – O template para o corpo HTML; o valor padrão é None, neste caso um email com texto plano sem marcação é enviado.

Por padrão, o save() popula o context com as mesmas variáveis que a password_reset() passa para o contexto do seu email.

class SetPasswordForm

Um formulário que permite ao usuário alterar sua senha sem informar a senha antiga.

class UserChangeForm

Um formulário usado na interface de administração para alterar informações e permissões do usuário.

class UserCreationForm

Uma ModelForm para criar um novo usuário.

Ela tem três campos: username (vindo o modelo do usuário), password1, e password2. Ela verifica se o password1 e o password2 combinam, validando a senha usando a validate_password(), e define a senha do usuário usando o set_password().

Dados de autenticação nos templates.

O usuário atualmente autenticado e suas permissões são disponibilizadas no contexto do template quando você usa a RequestContext.

Tecnicidades

Tecnicamente, estas variáveis somente ficam disponíveis no contexto do template quando se usa a RequestContext e o processador de contexto 'django.contrib.auth.context_processors.auth' estiver habilitado. Ele está no arquivo de definições gerado normalmente. Para mais detalhes, veja os documentos de RequestContext.

Usuários

Quando a RequestContext renderiza um template, o usuário autenticado no momento, seja uma instância de User ou uma instância de AnonymousUser, são armazenadas em uma variável de template chamada {{ user }}:

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

Esta variável de template não está disponível se um RequestContext não for usado.

Permissões

As permissões do usuário autenticado são armazenadas na variável {{ perms }} do template. Isso é uma instância de django.contrib.auth.context_processors.PermWrapper, o qual é um “proxy” de permissões amigável ao template.

No objeto {{ perms }}, de atributo único é um “proxy” para o User.has_module_perms. Este exemplo deve mostrar True se o usuário autenticado tiver qualquer permissão foo na aplicação “app”:

{{ perms.foo }}

O filtro do atributo de dois níveis é um proxy para :meth:’User.has_perm<django.contrib.auth.models.User.has_perm>’. Esse exemplo deve mostrar “True” se o usuário autenticado tiver a permissão “foo.can_vote”:

{{ perms.foo.can_vote }}

Logo, você pode conferir as permissões no formato de declaração “{% if %}”:

{% 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 %}

É possível também conferir as permissões através das declarações “{% if in %}”. Por exemplo:

{% if 'foo' in perms %}
    {% if 'foo.can_vote' in perms %}
        <p>In lookup works, too.</p>
    {% endif %}
{% endif %}

Gerenciando usuários no admin

Quando você tem instalados “django.contrib.admin” e “django.contrib.auth”, o admin provides um jeito conveniente de visualizar e gerenciar usuários, grupos e permissões. Usuários podem ser criados e deletados como qualquer modelo Django. Grupos podem ser criados, e permissões podem ser dadas a usuários ou grupos. Um registro das edições dos usuários aos modelos é criado no admin e também é armazenado e exibido.

Criando usuários

Você verá um link para “Usuários” na seção “Autenticação” da página principal do admin. A página “Adicionar usuário” do admin é diferente das outras páginas do admin pois exige que se escolha um nome de usuário e senha antes de permitir que se edite o resto dos campos de usuário.

Também observe: se você quer que uma conta de usuário possa criar usuários usando o site do Django admin, você precisará dar permissão para que essa conta adicione usuários e modifique usuários (por exemplo, as permissões “Adicionar usuário” e “Modificar usuário”). Se uma conta tem a permissão de adicionar usuários, mas não de modificá-los, então a conta não poderá adicionar usuários. Por quê? Porque se você tem permissão de adicionar usuários, você tem poder de criar superusuários, que pode, então, criar outros usuários. Então o Django exige permissões para adicionar e modificar como uma leve medida de segurança.

Seja consciente sobre como você permite aos usuários que gerenciem as permissões. Se você dá a habilidade de editar usuários a um não superusuário, isso, em última instância, é o mesmo que dá-lo a condição de superusuário, já que ele poderá elevar permissões de usuários, inclusive dele mesmo!

Mudando as senhas

Senhas de usuários não são exibidas no admin (nem armazenadas no banco de dados). Mas as :doc:’password storage details </topic/auth/passwords>’ são exibidas. Incluído na exibição dessas informações, há um link para um formulário de modificação de senha que permite que admins mudem a senha de usuários.