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.

Observação

Não há suporte para a Autenticação do Windows com HTTP/2. Os desafios de autenticação podem ser enviados em respostas HTTP/2, mas o cliente deve fazer downgrade para HTTP/1.1 antes de autenticar.

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 comando dotnet new com o webapp argumento (Aplicativo Web ASP.NET Core) e alterne --auth Windows:

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 Core (sem a propriedade <IsTransformWebConfigDisabled> definida como true no arquivo de projeto), o arquivo web.config publicado inclui a seção <location><system.webServer><security><authentication>. Para obter mais informações sobre a propriedade <IsTransformWebConfigDisabled>, confira Hospedar o ASP.NET Core no Windows com o IIS.

• 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 seção <system.webServer> adicionada ao arquivo web.config pelo Gerenciador do IIS está fora da seção do aplicativo <location> adicionada pelo SDK do .NET Core 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 evitar a herança, mova a seção <security> adicionada dentro da seção <location><system.webServer> fornecida pelo SDK do .NET Core.

  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 pacote NuGet Microsoft.AspNetCore.Authentication.Negotiate pode ser usado com Kestrel para dar suporte à Autenticação do Windows usando Negotiate e Kerberos no Windows, Linux e macOS.

Aviso

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.

Observação

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 é habilitada pelo seguinte código realçado para 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. As seguintes APIs são usadas no código anterior:

• AddAuthentication
• AddNegotiate
• UseAuthentication

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

O componente Microsoft.AspNetCore.Authentication.Negotiate 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();

O NegotiateDefaults.AuthenticationScheme especifica o 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.

Observação

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.

Observação

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;
        });
}

Observação

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.

Observação

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.

Observação

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".

Representação

O ASP.NET Core não implementa a representação. Os aplicativos são executados com a identity do aplicativo para todas as solicitações, usando o pool de aplicativos ou a identity do processo. Se o aplicativo tiver que executar uma ação em nome de um usuário, use WindowsIdentity.RunImpersonated ou RunImpersonatedAsync em um middleware embutido de 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 Microsoft.AspNetCore.Authentication.Negotiate habilite a autenticação no Windows, Linux e macOS, a representação só tem suporte 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