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 que os desenvolvedores leiam cabeçalhos de solicitação de autenticação e implementem sua própria lógica de avaliação de risco. O código implementado (plug-in) é executado de acordo 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 de Solicitação Recebida – Habilita 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 as 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 do contexto de solicitação e bloquear a solicitação de autenticação, se o IP estiver na lista predefinida de IPs suspeitos.

2. Estágio de pré-autenticação – Habilita 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. Nesse 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 na 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 suspeitas.

3. Pós-autenticação – Habilita a criação do plug-in para avaliar 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 as regras de declaração e política para avaliação posterior.

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 da extranet identificados como arriscados, registrar o plug-in com o AD FS e, finalmente, testar a funcionalidade.

Como criar um plug-in de exemplo

Pré-requisitos

Veja a seguir 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 posteriores
• 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 adicione os IPs que você deseja bloquear para esse arquivo.

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

   Observação

   Se você tiver um Farm do AD FS, poderá criar o arquivo em todos os servidores do AD FS. Qualquer um dos arquivos pode ser usado para importar os IPs suspeitos para o AD FS. Discutiremos o processo de importação em detalhes na seção Registrar a dll de plug-in com o AD FS abaixo.

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 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 Gerenciador de Referências, selecione Procurar. Na caixa de diálogo Selecionar os arquivos a serem referenciados..., selecione Microsoft.IdentityServer.dll na pasta de instalação do AD FS (no meu caso C:\Windows\ADFS) e clique em Adicionar.

   Observação

   No meu caso, estou criando o plug-in no próprio servidor do AD FS. Se o ambiente de desenvolvimento estiver em um servidor diferente, copie o Microsoft.IdentityServer.dll da pasta de instalação do AD FS no servidor do AD FS para a caixa de desenvolvimento.
   

   

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

   

6. Todas as classes e referências agora estão em vigor para fazer um build. No entanto, como a saída desse projeto é uma dll, ele precisará ser instalado no Cache de Assembly Global, ou GAC, do servidor do 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. Na caixa de 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 Criar e Recriar Solução, conforme 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, é 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 PowerShell Register-AdfsThreatDetectionModule no servidor do AD FS. No entanto, antes de 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 qual é o Token de Chave Pública da dll, você pode usar o SN.exe da seguinte maneira:

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

2. Inicie o Prompt de Comando do Desenvolvedor do Visual Studio e acesse o diretório que contém o sn.exe (no meu caso, o diretório é C:\Program Files (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 criar um instalador adequado para seu projeto e usar o instalador para adicionar o arquivo ao GAC. Outra solução é usar o Gacutil.exe (mais informações sobre o Gacutil.exe estão disponíveis aqui) no seu computador de desenvolvimento. Como tenho meu Visual Studio no mesmo servidor que o AD FS, usarei o Gacutil.exe da seguinte maneira:

   a. No Prompt de Comando do Desenvolvedor do Visual Studio, acesse o diretório que contém o Gacutil.exe (no meu caso, o diretório é C:\Program Files (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):

   

   Observação

   Se você tiver um farm do AD FS, o procedimento acima precisará ser executado em cada servidor do AD FS no farm.

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"
   

   Observação

   Você precisa registrar a dll apenas uma vez, mesmo que tenha um farm do AD FS.

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

É isso aí, 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"

Como testar o plug-in

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.

   Para esta demonstração, usarei a ferramenta de Raio-X de Declarações de Ajuda do AD FS para iniciar uma solicitação. Se você quiser usar a ferramenta de Raio-X, siga as instruções

   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 explicar o código de plug-in para entender a implementação usando as novas interfaces e classes introduzidas com o modelo.

Passo a passo do código de plug-in

Abra o projeto ThreatDetectionModule.sln usando o Visual Studio e abra o arquivo principal UserRiskAnalyzer.cs no 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 de 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, possibilitando a execução do código 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 escrever sua lógica de avaliação de risco. O parâmetro requestContext é do tipo RequestContext.

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

O método retorna ThrottleStatus (0 para 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 o compara com todos os IPs carregados no 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 que o AD FS as avalie, 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 agente que é do tipo ThreatDetectionLogger. O parâmetro pode ser usado para gravar as mensagens de erro, auditoria e/ou depuração nos logs do AD FS.

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

IPostAuthenticationThreatDetectionModule Interface

Essa interface permite implementar a lógica de avaliação de risco depois que o usuário fornecer as 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 de pós-autenticação.

O outro parâmetro de entrada passado é o agente que é do tipo ThreatDetectionLogger. O parâmetro pode ser usado para gravar 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 nas regras de declaração e política do AD FS.

Perguntas frequentes

Por que devo criar esses plug-ins?
R: 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 a flexibilidade de criar sua própria lógica de avaliação de risco com base nos seus requisitos.

Onde os logs são capturados?
R: você pode gravar logs de erros no log de eventos "AD FS/Administração" usando o método WriteAdminLogErrorMessage, auditar logs no log de segurança "Auditoria do AD FS" usando o método WriteAuditMessage e depurar logs para o log de depuração "Rastreamento do AD FS" usando o método WriteDebugMessage.

A adição desses plug-ins pode aumentar a latência do processo de autenticação do AD FS?
R: o impacto na 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 suspeitos, usuários etc.?
R: embora não esteja disponível no momento, estamos trabalhando na criação da inteligência para sugerir IPs suspeitos, usuários etc. no Modelo de Avaliação de Risco Conectável. Compartilharemos as datas de lançamento em breve.

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