Criar plug-ins com o modelo de avaliação de risco do AD FS 2019

Agora você pode criar seus próprios plug-ins para bloquear ou atribuir uma pontuação de risco a solicitações de autenticação durante vários estágios – solicitação recebida, pré-autenticação e pós-autenticação. Isso pode ser feito usando o novo Modelo de Avaliação de Risco introduzido com o AD FS 2019.

O que é o Modelo de Avaliação de Risco?

O Modelo de Avaliação de Risco é um conjunto de interfaces e classes que permitem aos desenvolvedores ler cabeçalhos de solicitação de autenticação e implementar sua própria lógica de avaliação de risco. O código implementado (plug-in) é executado em linha com o processo de autenticação do AD FS. Por exemplo, usando as interfaces e classes incluídas com o modelo, você pode implementar o código para bloquear ou permitir a solicitação de autenticação com base no endereço IP do cliente incluído no cabeçalho da solicitação. O AD FS executará o código para cada solicitação de autenticação e tomará as medidas apropriadas de acordo com a lógica implementada.

O modelo permite conectar o código em qualquer um dos três estágios do pipeline de autenticação do AD FS, conforme mostrado abaixo:

1. Estágio Recebido da Solicitação – permite a criação de plug-ins para permitir ou bloquear a solicitação quando o AD FS recebe a solicitação de autenticação, ou seja, antes que o usuário insira credenciais. Você pode usar o contexto de solicitação (por exemplo: IP do cliente, método Http, DNS do servidor proxy etc.) disponível neste estágio para executar a avaliação de risco. Por exemplo, você pode criar um plug-in para ler o IP no contexto da solicitação e bloquear a solicitação de autenticação se o IP estiver na lista predefinida de IPs arriscados.

2. Estágio de Pré-Autenticação – permite a criação de plug-ins para permitir ou bloquear a solicitação no ponto em que o usuário fornece as credenciais, mas antes que o AD FS as avalie. Neste estágio, além do contexto de solicitação, você também tem informações sobre o contexto de segurança (por exemplo: token de usuário, identificador de usuário etc) e o contexto de protocolo (por exemplo: protocolo de autenticação, clientID, resourceID etc) para usar em sua lógica de avaliação de risco. Por exemplo, você pode criar um plug-in para evitar ataques de pulverização de senha lendo a senha do usuário do token de usuário e bloqueando a solicitação de autenticação se a senha estiver na lista predefinida de senhas arriscadas.

3. Pós-Autenticação – permite que o plug-in de criação avalie o risco depois que o usuário tiver fornecido credenciais e o AD FS tiver realizado a autenticação. Neste estágio, além do contexto de solicitação, contexto de segurança e contexto de protocolo, você também tem informações sobre o resultado da autenticação (Êxito ou Falha). O plug-in pode avaliar a pontuação de risco com base nas informações disponíveis e passar a pontuação de risco para regras de declaração e política para avaliação adicional.

Para entender melhor como criar um plug-in de avaliação de risco e executá-lo de acordo com o processo do AD FS, vamos criar um plug-in de exemplo que bloqueia as solicitações provenientes de determinados IPs de extranet identificados como arriscados, registrar o plug-in com o AD FS e, finalmente, testar a funcionalidade.

Criando um plug-in de exemplo

Pré-requisitos

A seguir está a lista de pré-requisitos necessários para criar este plug-in de exemplo:

• AD FS 2019 instalado e configurado
• .NET Framework 4.7 e versões superiores
• Visual Studio

Criar dll de plug-in

O procedimento a seguir orientará você na criação de uma DLL de plug-in de exemplo.

1. Baixe o plug-in de exemplo, use o Git Bash e digite o seguinte:

git clone https://github.com/Microsoft/adfs-sample-RiskAssessmentModel-RiskyIPBlock

2. Crie um arquivo .csv em qualquer local no servidor do AD FS (no meu caso, criei o arquivo authconfigdb.csv em C:\extensions) e adicionei os IPs que você deseja bloquear a esse arquivo.

O plug-in de exemplo bloqueará todas as solicitações de autenticação provenientes dos IPs da Extranet listados neste arquivo.

3. Abra o projeto ThreatDetectionModule.sln usando o Visual Studio.

4. Remova o Microsoft.IdentityServer.dll do Gerenciador de Soluções, conforme mostrado abaixo:
   

5. Adicione referência ao Microsoft.IdentityServer.dll do seu AD FS, conforme mostrado abaixo:

a. Clique com o botão direito do mouse em Referências no Gerenciador de Soluções e selecione Adicionar Referência....

b. Na janela Do Gerenciador de Referência , selecione Procurar. Na caixa Selecionar os arquivos a serem referenciados... diálogo, selecione Microsoft.IdentityServer.dll na pasta de instalação do AD FS (no meu caso C:\Windows\ADFS) e clique em Adicionar.

c. Clique em OK na janela do Gerenciador de Referências depois de verificar se a Microsoft.IdentityServer.dll caixa de seleção está marcada.

6. Todas as classes e referências agora estão em vigor para fazer um build. No entanto, como a saída deste projeto é uma dll, ele terá que ser instalado no Cache de Assembly Global, ou GAC, do servidor AD FS e a dll precisa ser assinada primeiro. Isso pode ser feito da seguinte maneira:

a. Clique com o botão direito do mouse no nome do projeto, ThreatDetectionModule. No menu, clique em Propriedades.

b. Na página Propriedades, clique em Assinatura, à esquerda, e marque a caixa de seleção Assinar o assembly. No menu suspenso Escolher um arquivo de chave de nome forte:, selecione <Novo...>.

c. No diálogo Criar Chave de Nome Forte, digite um nome (você pode escolher qualquer nome) para a chave, desmarque a caixa de seleção Proteger meu arquivo de chave com senha. Em seguida, clique em OK.

d. Salve o projeto, conforme mostrado abaixo:

7. Crie o projeto clicando em Construir e, em seguida, em Reconstruir Solução, como mostrado abaixo:
   

Verifique a janela Saída na parte inferior da tela para ver se ocorreram erros.

O plug-in (dll) agora está pronto para uso e está na pasta \bin\Debug da pasta do projeto (no meu caso, isso é C:\extensions\ThreatDetectionModule\bin\Debug\ThreatDetectionModule.dll).

A próxima etapa é registrar essa dll com o AD FS, para que ela seja executada de acordo com o processo de autenticação do AD FS.

Registrar a dll de plug-in com o AD FS

Precisamos registrar a dll no AD FS usando o comando do Register-AdfsThreatDetectionModule PowerShell no servidor do AD FS. No entanto, antes de nos registrarmos, precisamos obter o Token de Chave Pública. Esse token de chave pública foi criado quando criamos a chave e assinamos a dll usando essa chave. Para saber o que é o Token de Chave Pública para a dll, você pode usar o SN.exe da seguinte maneira:

1. Copie o arquivo dll da pasta \bin\Debug para outro local (no meu caso, copiando-o para C:\extensions).

2. Inicie o Prompt de Comando do Desenvolvedor para Visual Studio e acesse o diretório que contém o sn.exe (no meu caso, o diretório é C:\Arquivos de Programas (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.7.2 Tools).

3. Execute o comando SN com o parâmetro -T e o local do arquivo (no meu caso SN -T "C:\extensions\ThreatDetectionModule.dll").

O comando fornecerá o token de chave pública (para mim, o Token de Chave Pública é 714697626ef96b35)

4. Adicione a dll ao Cache de Assembly Global do servidor do AD FS Nossa melhor prática seria que você criasse um instalador adequado para seu projeto e use o instalador para adicionar o arquivo ao GAC. Outra solução é usar Gacutil.exe (mais informações sobre Gacutil.exe disponíveis aqui) em seu computador de desenvolvimento. Como tenho meu visual studio no mesmo servidor que o AD FS, usarei Gacutil.exe da seguinte maneira:

a. Abra o Prompt de Comando do Desenvolvedor para o Visual Studio e navegue até o diretório que contém o Gacutil.exe (no meu caso, o diretório é C:\Arquivos de Programas (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.7.2 Tools).

b. Execute o comando Gacutil (no meu caso Gacutil /IF C:\extensions\ThreatDetectionModule.dll):

5. Abra o Windows PowerShell e execute o seguinte comando para registrar a dll:

Register-AdfsThreatDetectionModule -Name "<Add a name>" -TypeName "<class name that implements interface>, <dll name>, Version=10.0.0.0, Culture=neutral, PublicKeyToken=< Add the Public Key Token from Step 2. above>" -ConfigurationFilePath "<path of the .csv file>"

No meu caso, o comando é:

Register-AdfsThreatDetectionModule -Name "IPBlockPlugin" -TypeName "ThreatDetectionModule.UserRiskAnalyzer, ThreatDetectionModule, Version=10.0.0.0, Culture=neutral, PublicKeyToken=714697626ef96b35" -ConfigurationFilePath "C:\extensions\authconfigdb.csv"

6. Reinicie o serviço do AD FS depois de registrar a dll.

É isso, a dll agora está registrada no AD FS e pronta para uso!

UnRegister-AdfsThreatDetectionModule -Name "<name used while registering the dll in 5. above>"

UnRegister-AdfsThreatDetectionModule -Name "IPBlockPlugin"

Testando o plugin

1. Abra o arquivo authconfig.csv que criamos anteriormente (no meu caso, no local C:\extensions) e adicione os IPs da Extranet que você deseja bloquear. Cada IP deve estar em uma linha separada e não deve haver espaços no final.
   

2. Salve e feche o arquivo.

3. Importe o arquivo atualizado no AD FS executando o seguinte comando do PowerShell:

Import-AdfsThreatDetectionModuleConfiguration -name "<name given while registering the dll>" -ConfigurationFilePath "<path of the .csv file>"

No meu caso, o comando é:

Import-AdfsThreatDetectionModuleConfiguration -name "IPBlockPlugin" -ConfigurationFilePath "C:\extensions\authconfigdb.csv")

4. Inicie a solicitação de autenticação do servidor com o mesmo IP adicionado em authconfig.csv.

Insira a instância do servidor de federação e clique no botão Autenticação de Teste .

5. A autenticação está bloqueada, conforme mostrado abaixo.
   

Agora que sabemos como criar e registrar o plug-in, vamos passo a passo sobre o código do plug-in para entender a implementação usando as novas interfaces e classes introduzidas com o modelo.

Explicação detalhada do código do plug-in

Abra o projeto ThreatDetectionModule.sln usando o Visual Studio e abra o arquivo principal UserRiskAnalyzer.cs do Gerenciador de Soluções à direita da tela

O arquivo contém a classe principal UserRiskAnalyzer que implementa a classe abstrata ThreatDetectionModule e a interface IRequestReceivedThreatDetectionModule para ler o IP do contexto da solicitação, comparar o IP obtido com os IPs carregados do AD FS DB e bloquear a solicitação se houver uma correspondência de IP. Vamos examinar esses tipos com mais detalhes

Classe abstrata ThreatDetectionModule

Essa classe abstrata carrega o plug-in no pipeline do AD FS, tornando possível executar o código de plug-in de acordo com o processo do AD FS.

public abstract class ThreatDetectionModule
{
  protected ThreatDetectionModule();

  public abstract string VendorName { get; }
  public abstract string ModuleIdentifier { get; }

  public abstract void OnAuthenticationPipelineLoad(ThreatDetectionLogger logger, ThreatDetectionModuleConfiguration configData);
  public abstract void OnAuthenticationPipelineUnload(ThreatDetectionLogger logger);
  public abstract void OnConfigurationUpdate(ThreatDetectionLogger logger, ThreatDetectionModuleConfiguration configData);
}

A classe inclui os seguintes métodos e propriedades:

Em nosso plug-in de exemplo, estamos usando os métodos OnAuthenticationPipelineLoad e OnConfigurationUpdate para ler os IPs predefinidos do AD FS DB. OnAuthenticationPipelineLoad é chamado quando o plug-in é registrado com o AD FS enquanto OnConfigurationUpdate é chamado quando o .csv é importado usando o Import-AdfsThreatDetectionModuleConfiguration cmdlet.

IRequestReceivedThreatDetectionModule Interface

Essa interface permite implementar a avaliação de risco no ponto em que o AD FS recebe a solicitação de autenticação, mas antes que o usuário insira credenciais, ou seja, no estágio de Solicitação Recebida do processo de autenticação.

public interface IRequestReceivedThreatDetectionModule
{
  Task<ThrottleStatus> EvaluateRequest (
  ThreatDetectionLogger logger,
  RequestContext requestContext );
}

A interface inclui o método EvaluateRequest , que permite que você use o contexto da solicitação de autenticação passada no parâmetro de entrada requestContext para gravar sua lógica de avaliação de risco. O parâmetro requestContext é do tipo RequestContext.

O outro parâmetro de entrada passado é o logger que é do tipo ThreatDetectionLogger. O parâmetro pode ser utilizado para registrar as mensagens de erro, auditoria e/ou depuração nos logs do AD FS.

O método retorna ThrottleStatus (0 se NotEvaluated, 1 para Bloquear e 2 para Permitir) para o AD FS, que bloqueia ou permite a solicitação.

Em nosso plug-in de exemplo, a implementação do método EvaluateRequest analisa o clientIpAddress do parâmetro requestContext e compara-o com todos os IPs carregados do AD FS DB. Se uma correspondência for encontrada, o método retornará 2 para Bloquear, caso contrário, retornará 1 para Permitir. Com base no valor retornado, o AD FS bloqueia ou permite a solicitação.

IPreAuthenticationThreatDetectionModule Interface

Essa interface permite implementar a lógica de avaliação de risco no ponto em que o usuário fornece as credenciais, mas antes do AD FS avaliá-las, ou seja, estágio de pré-autenticação.

public interface IPreAuthenticationThreatDetectionModule
{
  Task<ThrottleStatus> EvaluatePreAuthentication (
  ThreatDetectionLogger logger,
  RequestContext requestContext,
  SecurityContext securityContext,
  ProtocolContext protocolContext,
  IList<Claim> additionalClams
  );
}

A interface inclui o método EvaluatePreAuthentication , que permite usar as informações passadas nos parâmetros de entrada RequestContext requestContext, SecurityContext securityContext, ProtocolContext protocolContext e IList<Claim> additionalClams para gravar sua lógica de avaliação de risco de pré-autenticação.

O outro parâmetro de entrada passado é o logger que é do tipo ThreatDetectionLogger. O parâmetro pode ser utilizado para registrar as mensagens de erro, auditoria e/ou depuração nos logs do AD FS.

O método retorna ThrottleStatus (0 se NotEvaluated, 1 para Bloquear e 2 para Permitir) para o AD FS, que bloqueia ou permite a solicitação.

Interface de IPostAuthenticationThreatDetectionModule

Essa interface permite implementar a lógica de avaliação de risco depois que o usuário tiver fornecido credenciais e o AD FS tiver realizado a autenticação, ou seja, o estágio pós-autenticação.

public interface IPostAuthenticationThreatDetectionModule
{
  Task<RiskScore> EvaluatePostAuthentication (
  ThreatDetectionLogger logger,
  RequestContext requestContext,
  SecurityContext securityContext,
  ProtocolContext protocolContext,
  AuthenticationResult authenticationResult,
  IList<Claim> additionalClams
  );
}

A interface inclui o método EvaluatePostAuthentication , que permite usar as informações passadas nos parâmetros de entrada RequestContext requestContext, SecurityContext securityContext, ProtocolContext protocolContext e IList<Claim> additionalClams para gravar sua lógica de avaliação de risco pós-autenticação.

O outro parâmetro de entrada passado é o logger que é do tipo ThreatDetectionLogger. O parâmetro pode ser utilizado para registrar as mensagens de erro, auditoria e/ou depuração nos logs do AD FS.

O método retorna a Pontuação de Risco que pode ser usada na política e nas regras de declaração do AD FS.

Perguntas frequentes

Por que devo criar esses plug-ins?
Um: Esses plug-ins não apenas fornecem capacidade adicional para proteger seu ambiente contra ataques como ataques de pulverização de senha, mas também oferecem flexibilidade para criar sua própria lógica de avaliação de risco com base em seus requisitos.

Onde os logs são capturados?
A: Você pode gravar logs de erros no log de eventos "AD FS/Admin" usando o método WriteAdminLogErrorMessage, logs de auditoria no log de segurança "AD FS Auditing" usando o método WriteAuditMessage e logs de depuração no log de depuração "AD FS Tracing" usando o método WriteDebugMessage.

A adição desses plug-ins pode aumentar a latência do processo de autenticação do AD FS?
Um: O impacto da latência será determinado pelo tempo necessário para executar a lógica de avaliação de risco implementada. Recomendamos avaliar o impacto da latência antes de implantar o plug-in no ambiente de produção.

Por que o AD FS não pode sugerir a lista de IPs arriscados, usuários etc.?
Um: Embora não esteja disponível no momento, estamos trabalhando na criação da inteligência para sugerir IPs arriscados, usuários etc. no Modelo de Avaliação de Risco Plugável. Compartilharemos as datas de lançamento em breve.

Quais outros plug-ins de exemplo estão disponíveis?
Um: Os seguintes plug-ins de exemplo estão disponíveis: