Tutorial: Autenticar usuários com o Django no Visual Studio

2025-06-12

Este artigo apresenta a Etapa 5 da série de tutoriais Trabalhar com a estrutura web do Django no Visual Studio.

A autenticação é um requisito comum para aplicativos Web. O modelo do Projeto Web Django no Visual Studio fornece todos os módulos necessários para autenticação no arquivo settings.py do projeto Django. A etapa 4 desta série de tutoriais cria um aplicativo Web Django usando este modelo. Na Etapa 5, você explora os recursos de autenticação do modelo e trabalha com os recursos no aplicativo em execução.

Na Etapa 5 do tutorial, você aprenderá a:

Explorar o fluxo de autenticação no modelo do Projeto Web do Django no Visual Studio
Examinar o código que dá suporte ao processo de autenticação
Modificar código para habilitar o acesso às interfaces de administrador do Django
Executar o aplicativo Web django e usar recursos de autenticação

Pré-requisitos

Uma solução do Visual Studio e um aplicativo Web Django baseado no modelo do Projeto Web do Django (DjangoWeb). Etapa 4: Use o modelo completo do Projeto Web do Django descreve como criar este aplicativo.
O aplicativo Web Django deve ter uma conta de superusuário (administrador). Etapa 4 (Criar superusuário do Django) descreve como criar as credenciais do superusuário.
Examine a seção pré-requisitos na Etapa 1 desta série de tutoriais para obter detalhes sobre versões de modelo do Django, projetos do Visual Studio versus projetos do Django e desenvolvimento do Python no Mac.

Explorar o fluxo de autenticação

Esta seção explica o fluxo de autenticação padrão fornecido pelo modelo de Projeto Web do Django para um aplicativo Web do Django.

No Visual Studio, selecione Depuração>Iniciar Depuração (F5) para iniciar o aplicativo Web do Django (DjangoWeb).
Quando o aplicativo estiver aberto no navegador, observe à direita, na barra de navegação, a opção Entrar:

O aplicativo Django em operação tem uma barra de navegação com três opções de página: Início, Sobree Contato, além de uma opção Entrar. A configuração de autenticação permite que qualquer usuário veja o conteúdo nas páginas "Página Inicial", "Sobre" e "Contato".
Para acesso autenticado ao aplicativo Web Django, um superusuário designado pode usar a opção Fazer Login, que abre a página "Fazer Login":
Depois que o superusuário entrar, ele poderá acessar exibições de página restritas para o site e concluir tarefas de administração:
O superusuário pode usar a opção Fazer logoff para sair do aplicativo Django e retornar à página inicial como usuário não autenticado.

Nas seções a seguir, você modifica a configuração de autenticação para dar suporte ao acesso ao site administrativo do Django para o superusuário.

Examinar o código de autenticação

Agora que você entende os recursos gerais de autenticação de um aplicativo Web Django, está pronto para examinar o código subjacente fornecido pelo modelo Projeto Web do Django:

No Gerenciador de Soluções, expanda a pasta app/templates/app do projeto. As etapas a seguir analisam vários arquivos nesta pasta.
Abra o arquivo de modelo base, layout.html. Role até o elemento <div class="navbar ...> e localize a marca {% include app/loginpartial.html %}.

A marca {% include %} instrui o sistema de modelos do Django a efetuar pull do conteúdo do arquivo incluído neste momento no modelo que o contém.

Abra o arquivo loginpartial.html. Observe como esse modelo usa a marca condicional {% if user.is_authenticated %} junto com uma marca {% else %} para renderizar diferentes elementos da interface do usuário, dependendo se o usuário está autenticado:

{% if user.is_authenticated %}
<form id="logoutForm" action="/logout" method="post" class="navbar-right">
    {% csrf_token %}
    <ul class="nav navbar-nav navbar-right">
        <li><span class="navbar-brand">Hello {{ user.username }}!</span></li>
        <li><a href="javascript:document.getElementById('logoutForm').submit()">Log off</a></li>
    </ul>
</form>

{% else %}

<ul class="nav navbar-nav navbar-right">
    <li><a href="{% url 'login' %}">Log in</a></li>
</ul>

{% endif %}

Quando você inicia o aplicativo, não há um superusuário autenticado e o código do modelo renderiza apenas o link Entrar. O link tem como destino o caminho de "logon" relativo do site especificado no arquivo de URL do projeto django (DjangoWeb/DjangoWeb/urls.py), conforme descrito na etapa 4 do (examinar padrões de rota de URL). A rota de "logon" é mapeada para a exibição django.contrib.auth.views.login e a exibição recebe os seguintes dados:
```
{
    'template_name': 'app/login.html',
    'authentication_form': app.forms.BootstrapAuthenticationForm,
    'extra_context':
    {
        'title': 'Log in',
        'year': datetime.now().year,
    }
}
```
Esse código define três propriedades:
- template_name identifica o modelo para a página "Login" definida no arquivo do aplicativo/login.html. Lembre-se de que este link é relativo ao site. O caminho completo da pasta é app/templates/app/login.html.
- extra_context adiciona informações aos dados de contexto padrão fornecidos ao modelo. Nesse caso, as informações incluem um título de "Entrar", juntamente com a data, hora e ano.
- authentication_form especifica uma classe de formulário a ser usada com o procedimento de logon. No modelo, esse valor de propriedade aparece como o objeto form. O valor padrão é AuthenticationForm (de django.contrib.auth.views), mas o modelo de projeto do Visual Studio usa o formulário definido no arquivo aplicativo/forms.py do projeto:
```
from django import forms
from django.contrib.auth.forms import AuthenticationForm
from django.utils.translation import ugettext_lazy as _

class BootstrapAuthenticationForm(AuthenticationForm):
    """Authentication form which uses bootstrap CSS."""
    username = forms.CharField(max_length=254,
                            widget=forms.TextInput({
                                'class': 'form-control',
                                'placeholder': 'User name'}))
    password = forms.CharField(label=_("Password"),
                            widget=forms.PasswordInput({
                                'class': 'form-control',
                                'placeholder':'Password'}))
```
  A classe de formulário deriva de AuthenticationForm e, especificamente, substitui os campos de nome de usuário e senha para adicionar texto de espaço reservado. O modelo do Visual Studio inclui esse código explícito na suposição de que você provavelmente deseja personalizar o formulário, como adicionar validação de força de senha.

Quando a interação do usuário com o aplicativo abre a página de "Entrar", o aplicativo renderiza o modelo de login.html. As variáveis {{ form.username }} e {{ form.password }} renderizam os formulários CharField da classe BootstrapAuthenticationForm. Há também uma seção interna para mostrar erros de validação e um elemento pronto para logons sociais se você optar por adicionar esses serviços:

{% extends "app/layout.html" %}

{% block content %}

<h2>{{ title }}</h2>
<div class="row">
    <div class="col-md-8">
        <section id="loginForm">
            <form action="." method="post" class="form-horizontal">
                {% csrf_token %}
                <h4>Use a local account to log in.</h4>
                <hr />
                <div class="form-group">
                    <label for="id_username" class="col-md-2 control-label">User name</label>
                    <div class="col-md-10">
                        {{ form.username }}
                    </div>
                </div>
                <div class="form-group">
                    <label for="id_password" class="col-md-2 control-label">Password</label>
                    <div class="col-md-10">
                        {{ form.password }}
                    </div>
                </div>
                <div class="form-group">
                    <div class="col-md-offset-2 col-md-10">
                        <input type="hidden" name="next" value="/" />
                        <input type="submit" value="Log in" class="btn btn-default" />
                    </div>
                </div>
                {% if form.errors %}
                <p class="validation-summary-errors">Please enter a correct user name and password.</p>
                {% endif %}
            </form>
        </section>
    </div>
    <div class="col-md-4">
        <section id="socialLoginForm"></section>
    </div>
</div>

{% endblock %}

Quando o usuário seleciona Entrar no formulário de página, o Django tenta autenticar as credenciais, como as credenciais do superusuário:
- Se a autenticação falhar, o usuário permanecerá na página "Entrar" e a marca form.errors será definida como true:
- Se a autenticação for bem-sucedida, o Django abrirá a URL relativa no campo next, <input type="hidden" name="next" value="/" />, que nesse caso é a página "Página Inicial" (/).
Quando o aplicativo renderiza a página "Página Inicial" depois que o usuário é autenticado, a propriedade user.is_authenticated é verdadeira quando o modelo de loginpartial.html é renderizado. Nesse caso, a barra de navegação mostra uma mensagem Hello (nome de usuário) e a opção Fazer logoff substitui a opção Entrar.

Você pode usar a propriedade user.is_authenticated em outras partes do código do aplicativo para verificar a autenticação.

Acessar interfaces de administrador do Django

Para verificar se o usuário autenticado está autorizado a acessar recursos específicos, você precisa recuperar permissões específicas do usuário do banco de dados.

O superusuário ou administrador, em particular, está autorizado a acessar as interfaces de administrador internas do Django usando as URLs relativas do site /admin/ e /admin/doc/. Para obter mais informações, consulte Usando o sistema de autenticação do Django (documentos do Django).

Para habilitar o acesso às interfaces de administrador do Django, siga estas etapas:

Instale o pacote docutils Python em seu ambiente. Para obter instruções, consulte Instalar pacotes para o ambiente do Python.
No Gerenciador de Soluções, expanda a pasta de projeto do Django, DjangoWeb/DjangoWeb/. As etapas a seguir atualizam vários arquivos nesta pasta.
Abra o arquivo urls.py do projeto django e modifique o conteúdo da seguinte maneira:
1. Na parte superior do arquivo, adicione a seguinte importação de pacote para URLs ao final da lista atual:
```
from django.conf.urls import include
```
2. Após a lista de importação, adicione a seguinte instrução:
```
admin.autodiscover()
```
3. Localize a definição de urlpatterns e adicione a seguinte entrada de caminho antes da entrada 'admin/':
```
path('admin/doc/', include('django.contrib.admindocs.urls')),
```
Abra o arquivo de settings.py do projeto django e localize a coleção INSTALLED_APPS. Adicione a seguinte entrada imediatamente após a entrada app.
```
'django.contrib.admindocs',
```
Interrompa e reinicie o aplicativo Web Django.
No campo de endereço de URL do navegador, altere o modo de exibição de página do aplicativo para a rota /admin/ ou /admin/doc/. Essas páginas fornecem ao superusuário acesso a tarefas administrativas do Django, como criar contas de usuário ou grupo, alterar a senha e exibir a documentação do Django:

Explorar o comportamento de logoff

Há duas maneiras de o superusuário fazer logoff e encerrar a sessão autenticada. O aplicativo Web do Django inclui a opção Fazer logoff na barra de navegação e o site administrativo do Django fornece a opção Sair.

Sair do site administrativo do Django

Se o superusuário estiver exibindo páginas no site administrativo do Django, ele poderá selecionar Sair na barra de navegação do site. O navegador é atualizado para mostrar a página "Desconectado" do site:

Nesta página, o usuário tem duas opções, Home e Entrar novamente. Ambas as opções retornam o usuário para a página "Página Inicial" do site administrativo do Django (/admin), em que o usuário é solicitado a recuar novamente suas credenciais.

Sair do aplicativo Django na web

Se o superusuário estiver exibindo páginas no aplicativo Web do Django, como "Sobre" ou "Contato", ele poderá selecionar Fazer logoff na barra de navegação do aplicativo Web do Django. O comportamento de logoff é mínimo. Ele simplesmente encerra a sessão autenticada e navega o usuário de volta para a página "Página Inicial" do aplicativo.

Você pode retrabalhar o comportamento de logout para que seja mais informativo para o usuário:

No Gerenciador de Soluções, expanda a pasta app/templates/app do projeto e abra o arquivo loginpartial.html.
No arquivo de modelo, observe que o link Log off simplesmente realiza uma operação HTTP POST (action="/logout" method="post") para o caminho de URL relativo do site "/login" (href="{% url 'login' %}").
```
{% if user.is_authenticated %}
<form id="logoutForm" action="/logout" method="post" class="navbar-right">
   {% csrf_token %}
   <ul class="nav navbar-nav navbar-right">
      <li><span class="navbar-brand">Hello {{ user.username }}!</span></li>
      <li><a href="javascript:document.getElementById('logoutForm').submit()">Log off</a></li>
   </ul>
</form>

{% else %}

<ul class="nav navbar-nav navbar-right">
   <li><a href="{% url 'login' %}">Log in</a></li>
</ul>

{% endif %}
```
A função django.contrib.auth.views.logout da exibição embutida manipula esse processo de saída.

O comportamento atual não exibe nenhuma interface que permita aos usuários saberem que estão desconectados. O processo simplesmente navega o usuário de volta para a página "Página Inicial" do aplicativo Web Django de acordo com o padrão de caminho 'logout/' definido no arquivo de URL do projeto django (DjangoWeb/DjangoWeb/urls.py):
```
 path('logout/', LogoutView.as_view(next_page='/'), name='logout'),
```
Para exibir uma confirmação de logon mais informativa, você pode criar uma página de "Logoff" para o aplicativo.
Na pasta app/templates/app, crie um novo arquivo de modelo HTML chamado loggedoff.html.

Adicione o seguinte conteúdo ao novo arquivo de modelo:

{% extends "app/layout.html" %}
{% block content %}
<h3>You have been logged off</h3>
{% endblock %}

No arquivo de URL do projeto django, DjangoWeb/DjangoWeb/urls.py, altere o padrão de URL do caminho 'logout/' da seguinte maneira:
```
path('logout/', LogoutView.as_view(template_name='app/loggedoff.html'), name='logout'),
```
O código atualizado adiciona uma propriedade template_name para trabalhar com o novo modelo HTML para a página "Log off".
Interrompa e reinicie o aplicativo Web Django. Entre novamente e selecione Fazer logoff. Desta vez, o aplicativo mostra uma mensagem mais informativa para o usuário confirmar que ele está desconectado.
Interrompa o servidor e feche as janelas do navegador do aplicativo.

Salvar o projeto no controle do código-fonte

Se você tiver confirmando sua solução do Visual Studio para controle de origem ao longo desta série de tutoriais, agora será um bom momento para fazer outra confirmação. Siga as instruções na Etapa 2 (confirmar alterações no controle do código-fonte) nesta série de tutoriais.

Sua solução deve corresponder ao código-fonte do tutorial no GitHub: microsoft/python-sample-vs-learning-django.

Usar a tag {% csrf_token %} em elementos de formulário

A tag {% csrf_token %} inclui a proteção interna contra CSRF (solicitação intersite forjada) do Django (documentação do Django). Normalmente, você adiciona essa marca a qualquer elemento que envolva métodos de solicitação POST, PUT ou DELETE, como um formulário. A função de renderização de modelo (render) insere a proteção necessária.

Revisão do tutorial

Parabéns por concluir este tutorial sobre o Django no Visual Studio.

Neste tutorial, você aprendeu a:

Criar diferentes tipos de projetos do Django usando vários modelos no Visual Studio
Criar um aplicativo Web Django com várias páginas
Usar modelos para criar rotas e exibições de página diferentes
Fornecer arquivos estáticos, adicionar páginas e usar a herança do modelo
Fornecer acesso autenticado a páginas e recursos de aplicativos restritos e interfaces administrativas do Django

autenticação de usuário no Django (docs.djangoproject.com)
Código-fonte do Tutorial no GitHub (Microsoft/python-sample-vs-learning-django)

Compartilhar via