Migrar a autenticação do ASP.NET Framework para o ASP.NET Core

A autenticação é um componente crítico dos aplicativos Web, lidando com a verificação de identidade do usuário em solicitações HTTP. Ao migrar do ASP.NET Framework para o ASP.NET Core, a autenticação apresenta desafios exclusivos porque as duas estruturas lidam com a autenticação de forma muito diferente.

Para obter informações gerais sobre autenticação no ASP.NET Core, consulte Visão geral da autenticação ASP.NET Core. Para obter informações sobre autorização, consulte Introdução à autorização no ASP.NET Core.

Por que a migração de autenticação é complexa

ASP.NET Framework e ASP.NET Core têm abordagens fundamentalmente diferentes para autenticação:

• ASP.NET Framework fornece módulos de autenticação integrados com configuração automática e integração total com System.Web
• O ASP.NET Core usa uma abordagem baseada em middleware com configuração explícita e injeção de dependência

Essas diferenças significam que você não pode simplesmente mover seu código de autenticação do Framework para o Core sem alterações.

Tipos de autenticação e desafios de migração

Diferentes tipos de autenticação apresentam diferentes níveis de complexidade de migração:

Autenticação baseada em Cookie

• ASP.NET Framework: usa Microsoft.Owincookie middleware de autenticação
• ASP.NET Core: Usa CookieAuthentication middleware com configuração diferente
• Desafio de migração: Cookie formato, chaves de criptografia e diferenças de configuração

Tokens do tipo Bearer JWT

• ASP.NET Framework: muitas vezes manipulado através de módulos personalizados ou middleware OWIN
• ASP.NET Core: Suporte nativo através de Microsoft.AspNetCore.Authentication.JwtBearer
• Desafio de migração: diferenças de parâmetros de validação de token e registro de middleware

Autenticação do Windows

• ASP.NET Framework: Integração interna do IIS
• ASP.NET Core: Requer configuração explícita e pode precisar de alterações no modelo de hospedagem
• Desafio de migração: diferenças de fluxo de autenticação e configuração do servidor

Autenticação de formulários

• ASP.NET Framework: Incorporado System.Web.Security.FormsAuthentication
• ASP.NET Core: Sem equivalente direto, requer migração para cookie autenticação
• Desafio de migração: é necessária a reescrita completa do sistema de autenticação

Autenticação personalizada

• ASP.NET Framework: Implementação de módulos personalizados IHttpModule
• ASP.NET Core: middleware personalizado ou manipuladores de autenticação
• Desafio de migração: mudança completa da arquitetura de módulos para middleware

Visão geral das estratégias de migração

Você tem três abordagens principais para lidar com a autenticação durante a migração:

1. Reescrita completa - Reescreva todo o código de autenticação para usar a autenticação nativa do ASP.NET Core
2. Autenticação remota - Use adaptadores System.Web para delegar autenticação ao aplicativo ASP.NET Framework
3. Autenticação compartilhada cookie - Compartilhe cookies de autenticação entre aplicativos Framework e Core (para cenários baseados em OWIN)

Para a maioria dos aplicativos, a migração para a autenticação nativa do ASP.NET Core oferece o melhor desempenho e capacidade de manutenção. No entanto, aplicativos maiores ou aqueles com requisitos de autenticação complexos podem se beneficiar de uma abordagem incremental usando os adaptadores System.Web.

Escolha a sua abordagem de migração

Você tem três opções principais para migrar a autenticação do ASP.NET Framework para o ASP.NET Core. Sua escolha depende do tipo de autenticação, do cronograma de migração, se você precisa executar os dois aplicativos simultaneamente e da quantidade de código que está disposto a reescrever.

Guia de decisão rápida

Responda a estas perguntas para escolher a sua abordagem:

1. Você está fazendo uma reescrita completa ou uma migração incremental?

   • Reescrita completa → Reescrita completa na autenticação ASP.NET Core
   • Migração incremental → Continuar para a questão 2

2. Que tipo de autenticação seu aplicativo ASP.NET Framework usa?

   • Autenticação OWIN cookie → continue para a pergunta 3
   • Autenticação de formulários, tokens de portador JWT, autenticação do Windows ou autenticação personalizada → autenticação remota

3. Os aplicativos ASP.NET Framework e ASP.NET Core precisam acessar o mesmo estado de autenticação?

   • Sim, a autenticação partilhada é necessária — Continuar para a pergunta 4
   • Não, a autenticação separada é boa → Reescrita completa para autenticação ASP.NET Core

4. É possível definir definições de proteção de dados correspondentes entre ambas as aplicações?

   • Sim → Autenticação compartilhada cookie (consulte a seção Alternativas, melhor desempenho)
   • Não ou não tenho certeza → autenticação remota

Comparação das abordagens de migração

Reescrita completa para o sistema de autenticação do ASP.NET Core

Escolha essa abordagem quando estiver executando uma migração completa, tiver autenticação não OWIN ou quiser o melhor desempenho e capacidade de manutenção.

ASP.NET Core fornece suporte de autenticação abrangente com alto desempenho e amplas opções de personalização. Essa abordagem requer a reescrita do código de autenticação, mas oferece a maioria dos benefícios a longo prazo.

Prós e contras de uma reescrita completa

Considerações sobre migração

Ao migrar para a autenticação nativa do ASP.NET Core:

Escolha com base no seu tipo de autenticação do Framework:

• Autenticação de formulários → Migrar para Cookie autenticação
• Tokens ao portador JWT → migrar para a autenticação do portador JWT
• Autenticação do Windows → Usar a autenticação do Windows
• Provedores OWIN OAuth → Usar provedores OAuth ASP.NET Core correspondentes
• Autenticação personalizada → Implementar manipuladores de autenticação personalizados

Alterações de código necessárias:

• Substituir HttpContext.User padrões de acesso (em grande parte compatíveis)
• Atualize o registo de middleware de autenticação em Program.cs
• Migrar lógica de autenticação personalizada para padrões ASP.NET Core
• Atualizar atributos e políticas de autorização

Quando escolher esta abordagem:

• Você pode se dar ao luxo de reescrever o código relacionado à autenticação
• O desempenho é uma prioridade máxima
• Você não está compartilhando o estado de autenticação com aplicativos herdados
• Você deseja eliminar completamente as dependências do System.Web
• Seu aplicativo Framework usa autenticação de formulários, módulos personalizados ou tokens JWT

Autenticação remota

Escolha essa abordagem quando precisar compartilhar a autenticação entre o ASP.NET Framework e os aplicativos ASP.NET Core durante a migração incremental ou quando tiver uma autenticação complexa difícil de migrar.

A funcionalidade de autenticação remota dos adaptadores System.Web permite que uma aplicação ASP.NET Core determine a identidade de um utilizador ao delegar para uma aplicação ASP.NET. Isso permite a migração gradual, mantendo um único sistema de autenticação.

Como funciona a autenticação remota

1. Quando as solicitações são processadas pelo aplicativo ASP.NET Core, se a autenticação remota do aplicativo for o esquema padrão ou especificado pelo ponto de extremidade da solicitação, o RemoteAuthenticationAuthHandler tentará autenticar o usuário.
2. O manipulador faz uma solicitação HTTP para o ponto de extremidade autenticado do aplicativo ASP.NET, encaminhando cabeçalhos configurados da solicitação atual (por padrão, Authorization e Cookie cabeçalhos).
3. O aplicativo ASP.NET processa a autenticação e retorna um código de status serializado ClaimsPrincipal ou HTTP indicando falha.
4. O aplicativo ASP.NET Core usa o resultado para estabelecer a identidade do usuário ou lidar com desafios de autenticação.

Prós e contras da autenticação remota

Quando escolher a autenticação remota

Escolha Autenticação remota quando:

• Seu aplicativo ASP.NET não usa Microsoft.Owincookie autenticação
• Você quer uma solução flexível que funcione com vários mecanismos de autenticação
• Você precisa migrar gradualmente a lógica de autenticação para o ASP.NET Core
• Você tem uma autenticação personalizada complexa que é difícil de reescrever
• Você está fazendo uma migração incremental e precisa de um estado de autenticação compartilhada

Configuração de autenticação remota

Há apenas algumas pequenas alterações de código necessárias para ativar a autenticação remota numa solução que já está configurada de acordo com o Primeiros Passos.

Primeiro, siga as instruções da configuração da aplicação remota para conectar as aplicações ASP.NET Core e ASP.NET. Em seguida, há apenas alguns métodos adicionais de extensão a chamar para habilitar a autenticação remota da aplicação.

HttpApplicationHost.RegisterHost(builder =>
{
    builder.AddSystemWebAdapters()
        .AddProxySupport(options => options.UseForwardedHeaders = true)
        .AddRemoteAppServer(options =>
        {
            options.ApiKey = ConfigurationManager.AppSettings["RemoteAppApiKey"];
        })
        .AddAuthenticationServer();
});

builder.Services.AddSystemWebAdapters()
    .AddRemoteAppClient(options =>
    {
        options.RemoteAppUrl = new Uri(builder.Configuration
            ["ReverseProxy:Clusters:fallbackCluster:Destinations:fallbackApp:Address"]);
        options.ApiKey = builder.Configuration["RemoteAppApiKey"];
    })
    .AddAuthenticationClient(true);

...

var coreApp = builder.AddProject<Projects.AuthRemoteIdentityCore>("core")
    .WithHttpHealthCheck()
    .WaitFor(frameworkApp)
    .WithIncrementalMigrationFallback(frameworkApp, options => options.RemoteAuthentication = RemoteAuthentication.DefaultScheme);

...

Autenticação remota com recurso alternativo YARP

pt-PT: Ao usar autenticação remota com recuperação baseada em YARP para a aplicação ASP.NET Framework, certifique-se de que os pedidos de recuperação não invocam autenticação remota. Se a autenticação remota for executada durante o recurso, a aplicação faz chamadas adicionais desnecessárias de volta à aplicação Framework e pode levar a comportamentos confusos.

Para evitar a autenticação remota para pedidos de recurso, utilize uma destas abordagens:

• Use metadados de curto-circuito de roteamento na rota de fallback do YARP para que a rota ignore o resto do pipeline de middleware. Por exemplo, chamar ShortCircuit no endpoint de recurso, conforme mostrado na orientação de configuração remota da aplicação e no middleware de curto-circuito após o encaminhamento.
• Não uses autenticação remota como esquema de autenticação predefinido. Em vez disso, configure a autenticação remota apenas para os endpoints que a necessitem. Por exemplo, passar false para AddAuthenticationClient e especificar explicitamente o esquema de autenticação remota nesses endpoints.

Utilização de autenticação remota com endpoints específicos

Ao definir o esquema padrão como false, você pode especificar a autenticação remota para controladores ou ações específicos:

[Authorize(AuthenticationSchemes = RemoteAppAuthenticationDefaults.AuthenticationScheme)]
public class SecureController : Controller
{
    // This controller uses remote authentication
    public IActionResult Index()
    {
        return View();
    }
}

// Or on specific actions
public class HomeController : Controller
{
    [Authorize(AuthenticationSchemes = RemoteAppAuthenticationDefaults.AuthenticationScheme)]
    public IActionResult SecureAction()
    {
        return View();
    }
}

Implementando processadores de resultados de autenticação personalizados

Você pode implementar processadores personalizados para modificar os resultados da autenticação antes que eles sejam usados:

public class CustomAuthResultProcessor : IRemoteAuthenticationResultProcessor
{
    public Task ProcessAsync(RemoteAuthenticationResult result, HttpContext context)
    {
        // Custom logic to process authentication results
        if (result.Headers.ContainsKey("Location"))
        {
            // Modify redirect URLs or other logic
        }
        
        return Task.CompletedTask;
    }
}

// Register the custom processor
builder.Services.AddScoped<IRemoteAuthenticationResultProcessor, CustomAuthResultProcessor>();

Por fim, se o aplicativo ASP.NET Core não incluir anteriormente middleware de autenticação, isso precisará ser habilitado (após o middleware de roteamento, mas antes do middleware de autorização). Para obter mais informações sobre pedidos de middleware, consulte ASP.NET Core Middleware:

app.UseAuthentication();

Considerações de segurança

Ao implementar a autenticação remota, considere os seguintes aspetos de segurança:

• Segurança da chave de API: a chave de API usada para comunicação entre os aplicativos ASP.NET Core e ASP.NET deve ser armazenada com segurança usando provedores de configuração e não codificada.
• Segurança de rede: A comunicação entre os aplicativos deve ocorrer por canais seguros (HTTPS) em ambientes de produção.
• Reencaminhamento de cabeçalhos: tenha cuidado com os cabeçalhos que encaminha para evitar a exposição de informações confidenciais. Encaminhar apenas cabeçalhos necessários para autenticação.
• Proteção de ponto de extremidade: o ponto de extremidade de autenticação no aplicativo ASP.NET só deve ser acessível ao aplicativo ASP.NET Core, não a clientes externos.

Solução de problemas

Problemas comuns ao configurar a autenticação remota:

• Falhas de autenticação: verifique se as chaves de API correspondem entre ambos os aplicativos e se o caminho do ponto de extremidade de autenticação está configurado corretamente.
• Loops de redirecionamento: verifique se o RedirectUrlProcessor está configurado corretamente para redirecionar para o aplicativo ASP.NET Core em vez do aplicativo ASP.NET.
• Declarações ausentes: verifique se o aplicativo ASP.NET está serializando corretamente o ClaimsPrincipal e se todas as declarações necessárias estão incluídas.

Desenho

1. Quando as solicitações são processadas pelo aplicativo ASP.NET Core, se a autenticação remota do aplicativo for o esquema padrão ou especificado pelo ponto de extremidade da solicitação, o RemoteAuthenticationAuthHandler tentará autenticar o usuário.
   1. O manipulador fará uma solicitação HTTP para o ponto de extremidade autenticado do aplicativo ASP.NET. Ele copiará cabeçalhos configurados da solicitação atual para esta nova, a fim de encaminhar dados relevantes para auth. Como mencionado acima, o comportamento padrão é copiar os cabeçalhos Authorization e Cookie. O cabeçalho da chave da API também é adicionado para fins de segurança.
2. A aplicação ASP.NET irá atender as solicitações enviadas para o endpoint de autenticação. Contanto que as chaves API sejam iguais, a aplicação ASP.NET retornará o ClaimsPrincipal do utilizador atual serializado no corpo da resposta ou retornará um código de status HTTP (como 401 ou 302) e cabeçalhos de resposta indicando falha.
3. Quando o RemoteAuthenticationAuthHandler do aplicativo ASP.NET Core recebe a resposta do aplicativo ASP.NET:
   1. Caso um ClaimsPrincipal seja retornado com sucesso, o manipulador de autenticação irá desserializá-lo e utilizá-lo como identidade do utilizador atual.
   2. Se um ClaimsPrincipal não foi retornado com êxito, o manipulador armazenará o resultado e, se a autenticação for contestada (porque o usuário está acessando um recurso protegido, por exemplo), a resposta da solicitação será atualizada com o código de status e cabeçalhos de resposta selecionados da resposta do ponto de extremidade autenticado. Isso permite que respostas de desafio (como redirecionamentos para uma página de login) sejam propagadas para os usuários finais.
      1. Como os resultados do ponto de extremidade de autenticação do aplicativo ASP.NET podem incluir dados específicos desse ponto, os utilizadores podem registar implementações IRemoteAuthenticationResultProcessor no aplicativo ASP.NET Core, que serão executadas em quaisquer resultados de autenticação antes de serem utilizados. Por exemplo, um IRemoteAuthenticationResultProcessor integrado é RedirectUrlProcessor que procura cabeçalhos de resposta Location retornados do ponto de extremidade de autenticação e garante que eles redirecionem de volta para o host da aplicação ASP.NET Core e não diretamente para a aplicação ASP.NET.

Limitações conhecidas

Essa abordagem de autenticação remota tem algumas limitações conhecidas:

1. Autenticação do Windows: Como a autenticação do Windows depende de um identificador para uma identidade do Windows, a autenticação do Windows não é suportada por esse recurso. Trabalhos futuros estão planejados para explorar como a autenticação compartilhada do Windows pode funcionar. Consulte dotnet/systemweb-adapters#246 para obter mais informações. Para cenários de autenticação do Windows, considere usar Configurar a Autenticação do Windows no ASP.NET Core em seu aplicativo ASP.NET Core.
2. Ações de gerenciamento de usuários: esse recurso permite que o aplicativo ASP.NET Core use uma identidade autenticada pelo aplicativo ASP.NET, mas todas as ações relacionadas aos usuários (logon, logoff, etc.) ainda precisam ser roteadas pelo aplicativo ASP.NET.
3. Considerações sobre desempenho: cada solicitação de autenticação requer uma chamada HTTP para o aplicativo ASP.NET, o que pode afetar o desempenho. Considere o uso da autenticação compartilhada cookie (descrita na seção Alternativas) se o desempenho for crítico.

Autenticação compartilhada cookie

Se a autenticação no aplicativo ASP.NET for feita usando Microsoft.OwinCookie o Middleware de Autenticação, uma solução alternativa à autenticação remota será configurar os aplicativos ASP.NET e ASP.NET Core para que eles possam compartilhar uma autenticação cookie.

Como funcionam os cookies partilhados

O compartilhamento de um cookie de autenticação permite:

• Ambas as aplicações para determinar a identidade do utilizador a partir do mesmo cookie.
• Entrar ou sair de um aplicativo faz com que o usuário entre ou saia do outro aplicativo.

Ambos os aplicativos são configurados para:

• Use o mesmo nome e as mesmas configurações de domínio cookie
• Partilhe chaves de proteção de dados para cookie encriptação/desencriptação
• Use o middleware de autenticação compatível cookie

Isso permite que os usuários autenticados em um aplicativo sejam autenticados automaticamente no outro aplicativo quando fizerem solicitações.

Prós e contras da autenticação compartilhada cookie

Limitações de autenticação com cookies partilhados

Observe que, como o login normalmente depende de um banco de dados específico, nem todas as funcionalidades de autenticação funcionarão em ambos os aplicativos:

• Os utilizadores devem entrar através de apenas uma das aplicações, seja a aplicação ASP.NET ou a aplicação ASP.NET Core, consoante a configuração do banco de dados com que a aplicação está preparada para trabalhar.
• Ambos os aplicativos são capazes de ver a identidade e as declarações dos usuários.
• Ambos os aplicativos são capazes de desconectar o usuário.

Detalhes sobre como configurar cookies de autenticação para partilha entre aplicações ASP.NET e ASP.NET Core estão disponíveis na documentação sobre partilha cookie. Para obter mais informações sobre cookie autenticação no ASP.NET Core, consulte Usar cookie autenticação sem ASP.NET Core Identity. Para orientações sobre a configuração de <machineKey> e a proteção de dados ao partilhar valores protegidos entre aplicações do .NET Framework e do .NET Core, consulte ASP.NET machineKey to ASP.NET Core migration.

Os seguintes exemplos no repositório GitHub adaptadores System.Web demonstram a autenticação de aplicativos remotos através de uma configuração compartilhada que permite que ambos os aplicativos registrem e desregistrem usuários:

• ASP.NET aplicação
• aplicação ASP.NET Core

Quando escolher a autenticação compartilhada cookie

Escolha Autenticação Cookie compartilhada quando:

• Seu aplicativo ASP.NET já usa Microsoft.Owincookie autenticação
• Você pode definir configurações de proteção de dados correspondentes entre ambos os aplicativos
• O desempenho é crítico e você deseja minimizar as solicitações HTTP
• Você deseja que ambos os aplicativos lidem com operações de entrada/saída do usuário
• Sente-se confortável a gerir chaves de encriptação partilhadas

O compartilhamento de autenticação é uma boa opção se ambas as seguintes condições forem verdadeiras:

• O aplicativo ASP.NET já está usando a autenticação Microsoft.Owincookie.
• É possível atualizar o aplicativo ASP.NET e os aplicativos ASP.NET Core para usar as configurações de proteção de dados correspondentes. As configurações de proteção de dados compartilhadas correspondentes incluem um caminho de arquivo compartilhado, cache Redis ou Armazenamento de Blob do Azure para armazenar chaves de proteção de dados. Para obter mais informações, consulte Visão geral da proteção de dados do ASP.NET Core.

Para outros cenários, a abordagem de autenticação remota descrita anteriormente neste documento é mais flexível e provavelmente é mais adequada.

Ver também

• Visão geral do ASP.NET Core Authentication
• Introdução à autorização no ASP.NET Core
• Partilhar cookies de autenticação entre aplicações ASP.NET
• Usar cookie autenticação sem ASP.NET Core Identity
• Middleware do ASP.NET Core
• Migrar do ASP.NET Framework para o ASP.NET Core
• Configuração remota da aplicação