Configurar a Autenticação do Windows no ASP.NET Core

Por Rick Anderson e Kirk Larkin

A Autenticação do Windows (também conhecida como autenticação Negotiate, Kerberos ou NTLM) pode ser configurada para aplicativos ASP.NET Core hospedados com IIS, Kestrel ou HTTP.sys.

A Autenticação do Windows depende do sistema operacional para autenticar usuários de aplicativos ASP.NET Core. A autenticação do Windows é usada para servidores executados em uma rede corporativa usando identidades de domínio do Active Directory ou contas do Windows para identificar usuários. A Autenticação do Windows é mais adequada para ambientes de intranet em que os usuários, aplicativos cliente e servidores Web pertencem ao mesmo domínio do Windows.

Quando usar a Autenticação do Windows

A Autenticação do Windows é adequada para aplicativos Web que operam dentro da rede interna privada de uma organização, acessível somente para funcionários (e outros usuários autorizados) na mesma rede. O gerenciamento de usuário é feito no Active Directory (AD) e os usuários usam sua conta de domínio existente do Windows para autenticar.

A Autenticação do Windows oferece vários benefícios para aplicativos de intranet:

• Experiência perfeita do usuário – os usuários são autenticados automaticamente com base em sua sessão ativa do Windows ou são solicitados a inserir suas credenciais do Windows por meio de uma caixa de diálogo padrão do navegador.
• Integração com o Active Directory – aproveita as políticas de segurança e infraestrutura existentes do Windows, incluindo grupos de usuários, bloqueios de conta e MFA (autenticação multifator).
• Tratamento seguro de credenciais – a autenticação é tratada por meio de protocolos seguros, como Kerberos, sem a necessidade de gerenciar credenciais de usuário separadas.
• Autorização baseada em função – os aplicativos podem acessar informações de usuário e grupo do Active Directory, habilitando o RBAC (controle de acesso baseado em função) no aplicativo.
• Sobrecarga administrativa reduzida – não é necessário manter um banco de dados de usuário separado ou um sistema de gerenciamento de credenciais.

Isso torna a Autenticação do Windows ideal para organizações que desejam usar sua infraestrutura existente do Windows, como portais de intranet.

Note

Não há suporte para a Autenticação do Windows com HTTP/2. Embora os desafios de autenticação possam ser enviados através de respostas HTTP/2, o cliente deve voltar para HTTP/1.1 para completar a autenticação. Essa é uma limitação de protocolo, não uma depreciação da Autenticação do Windows. Depois de autenticada, a comunicação HTTP/2 normal pode ser retomada para solicitações subsequentes.

Para aplicativos voltados para o público, a Autenticação do Windows não é recomendada devido a questões de segurança e usabilidade. Estes motivos incluem:

• A Autenticação do Windows é melhor mantida interna para proteger o Active Directory, expondo-a fora de uma rede interna apresenta riscos de segurança.
• Usuários externos não têm contas de domínio do Windows.
• É complexo configurar a infraestrutura de rede necessária com segurança, e firewalls ou proxies podem interferir no processo de autenticação.
• Ele não é multiplataforma e não fornece opções de personalização para designs e experiências do usuário.

Alternativas para cenários diferentes

Dependendo dos requisitos do aplicativo, considere estas alternativas:

Para aplicativos voltados para o público:

• OpenID Connect com provedores de identidade externos
• ASP.NET Core Identity com contas de usuário locais (Introdução ao Identity no ASP.NET Core)
• Azure Active Directory (AAD) para ambientes do Microsoft 365

Para ambientes mistos com usuários externos e intranet:

• Serviços de Federação do Active Directory (ADFS) com OpenID Connect
• Azure Active Directory com configuração híbrida

Para ambientes corporativos que usam autenticação moderna:

• Azure Active Directory com logon único
• Soluções baseadas em SAML com provedores de identidade de terceiros

Cenários de proxy e balanceador de carga

A Autenticação do Windows é um cenário com estado usado principalmente em uma intranet, onde um proxy ou balanceador de carga não costuma manipular o tráfego entre clientes e servidores. Se for usado um proxy ou um balanceador de carga, a Autenticação do Windows só funcionará se o proxy ou o balanceador de carga:

• Trata a autenticação.
• Passa as informações de autenticação do usuário para o aplicativo (por exemplo, em um cabeçalho de solicitação), que atua nas informações de autenticação.

Uma alternativa à Autenticação do Windows em ambientes em que proxies e balanceadores de carga são usados é o ADFS (Active Directory Federated Services) com o OIDC (OpenID Connect).

IIS/IIS Express

Adicione o pacote NuGet Microsoft.AspNetCore.Authentication.Negotiate e os serviços de autenticação chamando AddAuthentication em Program.cs:

using Microsoft.AspNetCore.Authentication.Negotiate;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(NegotiateDefaults.AuthenticationScheme)
   .AddNegotiate();

builder.Services.AddAuthorization(options =>
{
    options.FallbackPolicy = options.DefaultPolicy;
});
builder.Services.AddRazorPages();

var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthentication();
app.UseAuthorization();

app.MapRazorPages();

app.Run();

O código anterior foi gerado pelo modelo de Razor Pages do ASP.NET Core com a Autenticação do Windows especificada.

Configurações de inicialização (depurador)

A configuração de inicialização afeta apenas o arquivo Properties/launchSettings.json do IIS Express e não configura o IIS para Autenticação do Windows. A configuração do servidor é explicada na seção IIS.

Os modelos do Aplicativo Web disponíveis por meio do Visual Studio ou da CLI do .NET podem ser configurados para dar suporte à Autenticação do Windows, que atualiza o arquivo Properties/launchSettings.json automaticamente.

Visual Studio

Novo projeto

Crie um novo aplicativo Razor Pages ou MVC. Na caixa de diálogo Informações adicionais, defina o Tipo de autenticação como Windows.

Execute o aplicativo. O nome de usuário aparece na interface do usuário do aplicativo renderizado.

Projeto existente

As propriedades do projeto habilitam a Autenticação do Windows e desabilitam a Autenticação Anônima. Abra a caixa de diálogo de perfis de inicialização:

1. No Gerenciador de Soluções, clique com o botão direito do mouse no projeto e selecione Propriedades.
2. Selecione Depurar > Geral e Abrir depuração dos perfis de inicialização da IU.
3. Desmarque a caixa de seleção Habilitar Autenticação Anônima.
4. Marque a caixa de seleção Habilitar Autenticação do Windows.

Como alternativa, as propriedades podem ser configuradas no nó iisSettings do arquivo launchSettings.json:

"iisSettings": {
    "windowsAuthentication": true,
    "anonymousAuthentication": false,
    "iisExpress": {
        "applicationUrl": "http://localhost:52171/",
        "sslPort": 44308
    }
}

CLI do .NET

Novo projeto

Execute o dotnet new comando com o webapp argumento (ASP.NET Core Aplicativo Web) e --auth Windows opção:

dotnet new webapp --auth Windows

Projeto existente

Atualize o nó iisSettings do arquivo launchSettings.json:

"iisSettings": {
    "windowsAuthentication": true,
    "anonymousAuthentication": false,
    "iisExpress": {
        "applicationUrl": "http://localhost:52171/",
        "sslPort": 44308
    }
}

IIS

O IIS usa o Módulo do ASP.NET Core para hospedar aplicativos ASP.NET Core. A Autenticação do Windows é configurada para o IIS por meio do arquivo web.config. As seções a seguir mostram como:

• Forneça um arquivo web.config local que ativa a Autenticação do Windows no servidor quando o aplicativo é implantado.
• Use o Gerenciador do IIS para configurar o arquivo web.config de um aplicativo ASP.NET Core que já foi implantado no servidor.

Se você ainda não fez isso, habilite o IIS para hospedar aplicativos ASP.NET Core. Para obter mais informações, consulte Hospedar o ASP.NET Core no Windows com o IIS.

Habilite o Serviço de Função do IIS para Autenticação do Windows. Para obter mais informações, confira Habilitar a Autenticação do Windows nos Serviços de Função do IIS (confira a Etapa 2).

O Middleware de Integração do IIS é configurado para autenticar automaticamente as solicitações por padrão. Para obter mais informações, confira Hospedar o ASP.NET Core no Windows com o IIS: opções de IIS (AutomaticAuthentication).

O Módulo ASP.NET Core é configurado para encaminhar o token de Autenticação do Windows para o aplicativo por padrão. Para obter mais informações, confira Referência de configuração do Módulo ASP.NET Core: atributos do elemento aspNetCore.

Use qualquer uma das seguintes abordagens:

• Antes de publicar e implantar o projeto, adicione o seguinte arquivo web.config à raiz do projeto:

  <?xml version="1.0" encoding="utf-8"?>
  <configuration>
    <location path="." inheritInChildApplications="false">
      <system.webServer>
        <security>
          <authentication>
            <anonymousAuthentication enabled="false" />
            <windowsAuthentication enabled="true" />
          </authentication>
        </security>
      </system.webServer>
    </location>
  </configuration>
  

  Quando o projeto é publicado pelo SDK do .NET (sem a <IsTransformWebConfigDisabled> propriedade definida true no arquivo de projeto), o arquivo web.config publicado inclui a <location><system.webServer><security><authentication> seção. Para obter mais informações sobre a <IsTransformWebConfigDisabled> propriedade, consulte web.config arquivo.

• Depois de publicar e implantar o projeto, execute a configuração do lado do servidor com o Gerenciador do IIS:

  1. No Gerenciador do IIS, selecione o site do IIS no nó Sites da barra lateral Conexões.
  2. Clique duas vezes em Autenticação na área do IIS.
  3. Selecione Autenticação Anônima. Selecione Desabilitar na barra lateral Ações.
  4. Selecione Autenticação do Windows. Selecione Habilitar na barra lateral Ações.

  Quando essas ações são executadas, o Gerenciador do IIS modifica o arquivo web.config do aplicativo. Um nó <system.webServer><security><authentication> é adicionado com as configurações atualizadas para anonymousAuthentication e windowsAuthentication:

  <system.webServer>
    <security>
      <authentication>
        <anonymousAuthentication enabled="false" />
        <windowsAuthentication enabled="true" />
      </authentication>
    </security>
  </system.webServer>
  

  A <system.webServer> seção adicionada ao arquivo web.config pelo Gerenciador do IIS está fora da seção do <location> aplicativo adicionada pelo SDK do .NET quando o aplicativo é publicado. Como a seção é adicionada fora do nó <location>, as configurações são herdadas por todos os sub-aplicativos para o aplicativo atual. Para impedir a herança, mova a seção adicionada <security> para dentro da seção <location><system.webServer> fornecida pelo SDK do .NET.

  Quando o Gerenciador do IIS é usado para adicionar a configuração do IIS, ele afeta apenas o arquivo web.config do aplicativo no servidor. Uma implantação seguinte do aplicativo poderá substituir as configurações no servidor se a cópia do servidor de web.config for substituída pelo arquivo web.config do projeto. Use uma das seguintes abordagens para gerenciar as configurações:

  • Use o Gerenciador do IIS para redefinir as configurações no arquivo web.config depois que o arquivo for substituído na implantação.
  • Adicione um arquivo web.config ao aplicativo localmente com as configurações.

Kestrel

O Microsoft.AspNetCore.Authentication.Negotiate pacote NuGet pode ser usado Kestrel para habilitar a Autenticação do Windows usando Negotiate e Kerberos no Windows, Linux e macOS.

Warning

As credenciais podem ser mantidas entre solicitações em uma conexão. A autenticação de negociação não deve ser usada com proxies, a menos que o proxy mantenha uma afinidade de conexão individual (uma conexão persistente) com Kestrel.

Note

O manipulador Negotiate detecta se o servidor subjacente dá suporte à Autenticação do Windows nativamente e se ele está habilitado. Se o servidor der suporte à Autenticação do Windows, mas estiver desabilitado, um erro será gerado solicitando que você habilite a implementação do servidor. Quando a autenticação do Windows está habilitada no servidor, o manipulador Negotiate encaminha as solicitações de autenticação para ele de forma transparente.

A autenticação e uma política de autorização de fallback são habilitadas pelo seguinte código realçado em Program.cs:

using Microsoft.AspNetCore.Authentication.Negotiate;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(NegotiateDefaults.AuthenticationScheme)
   .AddNegotiate();

builder.Services.AddAuthorization(options =>
{
    options.FallbackPolicy = options.DefaultPolicy;
});
builder.Services.AddRazorPages();

var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthentication();
app.UseAuthorization();

app.MapRazorPages();

app.Run();

O código anterior foi gerado pelo modelo de Razor Pages do ASP.NET Core com a Autenticação do Windows especificada.

Linhas realçadas:

• 5 a 6: AddAuthentication e AddNegotiate registre e configure o manipulador de autenticação Negotiate.
• 8 a 11: AddAuthorization com uma política de fallback obriga o uso de usuários autenticados por padrão.
• 26: UseAuthentication executa manipuladores de autenticação para cada solicitação e popula HttpContext.User.
• 27: UseAuthorization avalia as políticas de autorização, incluindo a política de fallback.

Note

Chamar AddAuthentication e AddNegotiate registra e configura o manipulador Negociar; ele não realiza a autenticação por solicitação. O middleware de autenticação (UseAuthentication) invoca o manipulador e popula HttpContext.User e deve aparecer antes de UseAuthorization para que a avaliação da política funcione.

Autenticação Kerberos e RBAC (controle de acesso baseado em função)

A autenticação Kerberos no Linux ou no macOS não fornece nenhuma informação de função para um usuário autenticado. Para adicionar informações de função e grupo a um usuário Kerberos, o manipulador de autenticação deve ser configurado para recuperar as funções de um domínio LDAP. A configuração mais básica especifica apenas um domínio LDAP para consultar e usa o contexto do usuário autenticado para consultar o domínio LDAP:

using Microsoft.AspNetCore.Authentication.Negotiate;
using System.Runtime.InteropServices;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(NegotiateDefaults.AuthenticationScheme)
    .AddNegotiate(options =>
    {
        if (RuntimeInformation.IsOSPlatform(OSPlatform.Linux))
        {
            options.EnableLdap("contoso.com");
        }
    });

Algumas configurações podem exigir credenciais específicas para consultar o domínio LDAP. As credenciais podem ser especificadas nas seguintes opções realçadas:

using Microsoft.AspNetCore.Authentication.Negotiate;
using System.Runtime.InteropServices;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(NegotiateDefaults.AuthenticationScheme)
        .AddNegotiate(options =>
        {
            if (RuntimeInformation.IsOSPlatform(OSPlatform.Linux))
            {
                options.EnableLdap(settings =>
                {
                    settings.Domain = "contoso.com";
                    settings.MachineAccountName = "machineName";
                    settings.MachineAccountPassword =
                                      builder.Configuration["Password"];
                });
            }
        });

builder.Services.AddRazorPages();

Por padrão, o manipulador de autenticação de negociação resolve domínios aninhados. Em um ambiente LDAP grande ou complicado, resolver domínios aninhados pode resultar em uma pesquisa lenta ou muita memória sendo usada para cada usuário. A resolução de domínio aninhada pode ser desabilitada usando a opção IgnoreNestedGroups.

Solicitações anônimas são permitidas. Use a Autorização do ASP.NET Core para desafiar solicitações anônimas de autenticação.

Configuração de ambiente do Windows

A Microsoft.AspNetCore.Authentication.Negotiate API executa a autenticação do Modo de Usuário . Os SPNs (Nomes de Entidade de Serviço) devem ser adicionados à conta de usuário que executa o serviço, não à conta do computador. Execute setspn -S HTTP/myservername.mydomain.com myuser em um shell de comando administrativo.

Kerberos vs NTLM

O pacote Negotiate no Kestrel para ASP.NET Core tenta usar o Kerberos, que é um esquema de autenticação mais seguro e performático do que o NTLM:

using Microsoft.AspNetCore.Authentication.Negotiate;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(NegotiateDefaults.AuthenticationScheme)
   .AddNegotiate();

builder.Services.AddAuthorization(options =>
{
    options.FallbackPolicy = options.DefaultPolicy;
});
builder.Services.AddRazorPages();

var app = builder.Build();

NegotiateDefaults.AuthenticationScheme especifica Kerberos porque é o padrão.

O IIS, o IISExpress e o Kestrel dão suporte a Kerberos e NTLM.

Examinar o cabeçalho WWW-Authenticate: usando o IIS ou o IISExpress com uma ferramenta como o Fiddler mostra o Negotiate e o NTLM.

O Kestrel mostra apenas WWW-Authenticate: Negotiate

O cabeçalho WWW-Authenticate: Negotiate significa que o servidor pode usar NTLM ou Kerberos. O Kestrel requer o prefixo de cabeçalho Negotiate, ele não dá suporte à especificação direta de NTLM nos cabeçalhos de autenticação da solicitação ou da resposta. O NTLM tem suporte no Kestrel, mas deve ser enviado como Negotiate.

Em Kestrel, para ver se NTLM ou Kerberos é usado, o Base64 decodifica o cabeçalho e mostra NTLM ou HTTP. HTTP indica que Kerberos foi usado.

Configuração do ambiente Linux e macOS

As instruções para ingressar em um computaor Linux ou macOS em um domínio Windows estão disponíveis no artigo Conectar o Azure Data Studio ao SQL Server usando a autenticação do Windows – Kerberos. As instruções criam uma conta de computador para o computador Linux no domínio. Os SPNs devem ser adicionados a essa conta de computador.

Note

Ao seguir as diretrizes no artigo Conectar o Azure Data Studio ao SQL Server usando a autenticação do Windows – Kerberos, substitua python-software-properties por python3-software-properties, se necessário.

Depois que o computador Linux ou macOS for ingressado no domínio, etapas adicionais serão necessárias para fornecer um arquivo keytab com os SPNs:

• No controlador de domínio, adicione novos SPNs de serviço Web à conta do computador:
  • setspn -S HTTP/mywebservice.mydomain.com mymachine
  • setspn -S HTTP/mywebservice@MYDOMAIN.COM mymachine
• Use ktpass para gerar um arquivo keytab:
  • ktpass -princ HTTP/mywebservice.mydomain.com@MYDOMAIN.COM -pass myKeyTabFilePassword -mapuser MYDOMAIN\mymachine$ -pType KRB5_NT_PRINCIPAL -out c:\temp\mymachine.HTTP.keytab -crypto AES256-SHA1
  • Alguns campos devem ser especificados em maiúsculas, conforme indicado.
• Copie o arquivo keytab para o computador Linux ou macOS.
• Selecione o arquivo keytab por meio de uma variável de ambiente: export KRB5_KTNAME=/tmp/mymachine.HTTP.keytab
• Invoque klist para mostrar os SPNs disponíveis no momento para uso.

Note

Um arquivo keytab contém credenciais de acesso ao domínio e deve ser protegido adequadamente.

HTTP.sys

O HTTP.sys dá suporte à Autenticação do Windows no Modo Kernel usando a autenticação Negotiate, NTLM ou Básica.

O código a seguir adiciona autenticação e configura o host da Web do aplicativo para usar HTTP.sys com a Autenticação do Windows:

using Microsoft.AspNetCore.Server.HttpSys;
using System.Runtime.InteropServices;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(HttpSysDefaults.AuthenticationScheme);

if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
{
    builder.WebHost.UseHttpSys(options =>
        {
            options.Authentication.Schemes =
                AuthenticationSchemes.NTLM |
                AuthenticationSchemes.Negotiate;
            options.Authentication.AllowAnonymous = false;
        });
}

Note

O HTTP.sys delega à autenticação de Modo Kernel com o protocolo de autenticação Kerberos. Não há suporte para autenticação de Modo de Usuário com o Kerberos e o HTTP.sys. A conta do computador precisa ser usada para descriptografar o token/tíquete do Kerberos que é obtido do Active Directory e encaminhado pelo cliente ao servidor para autenticar o usuário. Registre o SPN (nome da entidade de serviço) do host, não do usuário do aplicativo.

Note

Não há suporte para HTTP.sys no Nano Server versão 1709 ou posterior. Para usar a autenticação do Windows e HTTP.sys com o Nano Server, use um contêiner Server Core (microsoft/windowsservercore) (confira https://hub.docker.com/_/microsoft-windows-servercore). Para obter mais informações sobre o Server Core, confira O que é a opção de instalação do Server Core no Windows Server?.

Autorizar usuários

O estado de configuração do acesso anônimo determina a maneira como os atributos [Authorize] e [AllowAnonymous] são usados no aplicativo. As duas seções a seguir explicam como lidar com os estados de configuração não permitidos e permitidos de acesso anônimo.

Não permitir acesso anônimo

Quando a Autenticação do Windows está habilitada e o acesso anônimo está desabilitado, os atributos [Authorize] e [AllowAnonymous] não têm efeito. Se um site do IIS estiver configurado para não permitir acesso anônimo, a solicitação nunca atingirá o aplicativo. Por esse motivo, o atributo [AllowAnonymous] não é aplicável.

Permitir acesso anônimo

Quando a Autenticação do Windows e o acesso anônimo estiverem habilitados, use os atributos [Authorize] e [AllowAnonymous]. O atributo [Authorize] permite proteger pontos de extremidade do aplicativo que exigem autenticação. O atributo [AllowAnonymous] substitui o atributo [Authorize] em aplicativos que permitem acesso anônimo. Para obter detalhes de uso do atributo, confira Autorização simples no ASP.NET Core.

Note

Por padrão, os usuários que não têm autorização para acessar uma página recebem uma resposta HTTP 403 vazia. O Middleware StatusCodePages pode ser configurado para fornecer aos usuários uma melhor experiência de "Acesso Negado".

Impersonation

O ASP.NET Core não implementa a representação. Os aplicativos são executados com a identidade do aplicativo para todas as solicitações, usando o pool de aplicativos ou a identidade do processo. Se o aplicativo deve executar uma ação em nome de um usuário, use WindowsIdentity.RunImpersonated ou RunImpersonatedAsync em um middleware inline terminal em Program.cs. Execute uma única ação nesse contexto e feche-o.

app.Run(async (context) =>
{
    try
    {
        var user = (WindowsIdentity)context.User.Identity!;

        await context.Response
            .WriteAsync($"User: {user.Name}\tState: {user.ImpersonationLevel}\n");

        await WindowsIdentity.RunImpersonatedAsync(user.AccessToken, async () =>
        {
            var impersonatedUser = WindowsIdentity.GetCurrent();
            var message =
                $"User: {impersonatedUser.Name}\t" +
                $"State: {impersonatedUser.ImpersonationLevel}";

            var bytes = Encoding.UTF8.GetBytes(message);
            await context.Response.Body.WriteAsync(bytes, 0, bytes.Length);
        });
    }
    catch (Exception e)
    {
        await context.Response.WriteAsync(e.ToString());
    }
});

Embora o pacote habilite a autenticação no Windows, Linux e macOS, a impersonação é suportada apenas no Windows.

Transformações de declarações

Ao hospedar com IIS, AuthenticateAsync não é chamado internamente para inicializar um usuário. Portanto, uma implementação IClaimsTransformation usada para transformar as declarações após cada autenticação não é ativada por padrão. Para obter mais informações e um exemplo de código que ativa transformações de declarações, confira Diferenças entre hospedagem em processo e fora do processo.

Recursos adicionais

• dotnet publish
• Hospedar o ASP.NET Core no Windows com o IIS
• Módulo do ASP.NET Core(ANCM) para IIS
• Perfis de publicação do Visual Studio (.pubxml) para a implantação do aplicativo ASP.NET Core