Partilhar via

Criar Plug-ins com o Modelo de Avaliação de Risco do AD FS 2019

  • Artigo

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:

Diagram that shows the three stages of A D F S authentication.

  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.

Observação

Como alternativa, você pode criar o Plug-in de Usuário Suspeito, um plug-in de exemplo que usa o nível de risco do usuário determinado pelo Microsoft Entra Identity Protection para bloquear a autenticação ou impor a MFA (autenticação multifator). As etapas para criar o Plug-in de Usuário Suspeito estão disponíveis aqui.

Como criar um plug-in de exemplo

Observação

Este passo a passo é apenas para mostrar como você pode criar um plug-in de exemplo. A solução que estamos criando não é uma solução pronta para a empresa.

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:
    Screenshot that highlights the Remove menu option.

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

    Screenshot that highlights the Add Reference menu option.

    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.

    Screenshot that shows the file you should copy.

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

    Screenshot that shows the Microsoft dot Identity Server dot d l l checkbox.

  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.

    Screenshot that highlights the Properties menu option.

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

    Screenshot that shows the Sign the assembly checkbox.

    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.

    Screenshot that shows Protect my key file with password checkbox.

    d. Salve o projeto conforme mostrado abaixo:

    Screenshot that shows where to save your project.

  7. Crie o projeto clicando em Criar e Recriar Solução, conforme mostrado abaixo:

    Screenshot that shows the Rebuild Solution menu option.

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

    Screenshot that shows the output from the rebuilt solution.

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

    Screenshot that shows the Developer Command Prompt for Visual Studio.

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

    Screenshot that shows how to run the S N command.

    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):

    Screenshot that shows how to run the Gacutil command.

    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!

Observação

Se alguma alteração for feita no plug-in e o projeto for recriado, a dll atualizada precisará ser registrada novamente. Antes de registrar, você precisará cancelar o registro da dll atual usando o seguinte comando:

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



No meu caso, o comando é:

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.

    Screenshot that shows how to add the extranet I P lines.

  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.

    Screenshot that shows the Test Authentication button.

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

    Screenshot that shows that authentication is blocked.

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

model

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:

Método Type Definição
OnAuthenticationPipelineLoad Void Chamado pelo AD FS quando o plug-in é carregado no pipeline
OnAuthenticationPipelineUnload Void Chamado pelo AD FS quando o plug-in é descarregado do pipeline
OnConfigurationUpdate Void Chamado pelo AD FS na atualização de configuração
Propriedade Tipo Definição
VendorName String Recebe o nome do fornecedor que possui o plug-in
ModuleIdentifier String Recebe o identificador do plug-in

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.

Observação

O plug-in de exemplo discutido acima implementa apenas a interface IRequestReceivedThreatDetectionModule. No entanto, o modelo de avaliação de risco fornece duas interfaces adicionais –IPreAuthenticationThreatDetectionModule (para implementar o estágio de pré-autenticação da lógica de avaliação de risco) e IPostAuthenticationThreatDetectionModule (para implementar a lógica de avaliação de risco durante o estágio pós-autenticação). Os detalhes sobre as duas interfaces são fornecidos abaixo.

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.

Observação

Para obter a lista de propriedades passada com cada tipo de contexto, acesse as definições de classe RequestContext, SecurityContext e ProtocolContext.

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.

Observação

Para obter a lista de propriedades completa passada com cada tipo de contexto, veja as definições de classe RequestContext, SecurityContext e ProtocolContext.

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.

Observação

Para que o plug-in funcione, a classe principal (nesse caso, UserRiskAnalyzer) precisa derivar a classe abstrata ThreatDetectionModule e deve implementar pelo menos uma das três interfaces descritas acima. Depois que a dll é registrada, o AD FS verifica quais das interfaces são implementadas e as chama no estágio apropriado no pipeline.

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:

Nome Descrição
Plug-in de Usuário Suspeito O plug-in de exemplo que bloqueia a autenticação ou impõe a MFA com base no nível de risco do usuário determinado pelo Microsoft Entra Identity Protection.