Compilación de complementos con el modelo de evaluación de riesgos 2019 de AD FS

• Se aplica a:

  ✅ Windows Server 2025, ✅ Windows Server 2022, ✅ Windows Server 2019, ✅ Windows Server 2016

Ahora puede crear sus propios complementos para bloquear o asignar una puntuación de riesgo a las solicitudes de autenticación durante varias fases: solicitud recibida, autenticación previa y autenticación posterior. Esto se puede lograr con el nuevo modelo de evaluación de riesgos introducido en AD FS 2019.

¿Qué es el modelo de evaluación de riesgos?

El modelo de evaluación de riesgos es un conjunto de interfaces y clases que permiten a los desarrolladores leer encabezados de solicitudes de autenticación e implementar su propia lógica de evaluación de riesgos. A continuación, el código (complemento) implementado se ejecuta en línea con el proceso de autenticación de AD FS. Por ejemplo, con las interfaces y clases incluidas en el modelo, puede implementar código para bloquear o permitir solicitudes de autenticación en función de la dirección IP del cliente incluida en el encabezado de cada solicitud. AD FS ejecuta el código para cada solicitud de autenticación y realiza las acciones adecuadas según la lógica implementada.

El modelo permite agregar código en forma de complemento en cualquiera de las tres fases de la canalización de autenticación de AD FS, como se muestra a continuación:

1. Fase Solicitud recibida: permite crear complementos para permitir o bloquear una solicitud de autenticación cuando la recibe AD FS, es decir, antes de que el usuario escriba las credenciales. Puede usar el contexto de solicitud (por ejemplo: IP de cliente, método HTTP, DNS del servidor proxy, etc.) disponible en esta fase para hacer una evaluación de riesgos. Por ejemplo, puede crear un complemento para leer la dirección IP del contexto de solicitud y bloquear la solicitud de autenticación si la dirección IP está en la lista predefinida de direcciones IP de riesgo.

2. Fase Autenticación previa: permite crear complementos para permitir o bloquear una solicitud en el momento en el que el usuario proporciona las credenciales, pero antes de que AD FS las evalúe. En esta fase, además del contexto de solicitud, también tiene información sobre el contexto de seguridad (por ejemplo: token de usuario, identificador de usuario, etc.) y el contexto de protocolo (por ejemplo: protocolo de autenticación, clientID, resourceID, etc.) para usarla en la lógica de evaluación de riesgos. Por ejemplo, puede crear un complemento para evitar ataques de difusión de contraseñas leyendo la contraseña de usuario del token de usuario y bloqueando la solicitud de autenticación si la contraseña está en la lista predefinida de contraseñas de riesgo.

3. Autenticación posterior: permite crear un complemento para evaluar el riesgo después de que el usuario ha proporcionado las credenciales y AD FS ha realizado la autenticación. En esta fase, además del contexto de solicitud, el contexto de seguridad y el contexto de protocolo, también tiene información sobre el resultado de la autenticación (correcta o incorrecta). El complemento puede evaluar la puntuación de riesgo en función de la información disponible y pasar la puntuación de riesgo a las reglas de notificación y directiva para su posterior evaluación.

Para comprender mejor cómo crear un complemento de evaluación de riesgos y ejecutarlo en línea con el proceso de AD FS, vamos a crear un complemento de ejemplo que bloquee las solicitudes procedentes de determinadas direcciones IP de la extranet identificadas como arriesgadas, registre el complemento en AD FS y, finalmente, pruebe la funcionalidad.

Nota:

Como alternativa, puede crear un complemento de usuario de riesgo, un complemento de ejemplo que aproveche el nivel de riesgo del usuario determinado por Protección de id. de Microsoft Entra para bloquear la autenticación o aplicar la autenticación multifactor (MFA). Los pasos para crear un complemento de usuario de riesgo están disponibles aquí.

Creación de un complemento de ejemplo

Nota

Este tutorial solo muestra cómo crear un complemento de ejemplo. La solución que vamos a crear no está preparada para empresas en absoluto.

Requisitos previos

A continuación se indican los requisitos previos para crear este complemento de ejemplo:

• AD FS 2019 instalado y configurado.
• .NET Framework 4.7 o posterior.
• Visual Studio

Compilación del archivo .dll del complemento

El siguiente procedimiento le guiará en la creación de un archivo .dll de complemento de ejemplo:

1. Descargue el complemento de ejemplo, use Git Bash y escriba lo siguiente:

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

2. Cree un archivo .csv en cualquier ubicación del servidor de AD FS (en mi caso, he creado el archivo authconfigdb.csv en C:\extensions) y agregue las direcciones IP que desea bloquear en este archivo.

   El complemento de ejemplo bloqueará las solicitudes de autenticación procedentes de las direcciones IP de la extranet enumeradas en este archivo.

   Nota

   Si tiene una granja de AD FS, puede crear el archivo en cualquiera o en todos los servidores de AD FS. Cualquiera de los archivos se puede usar para importar las direcciones IP de riesgo en AD FS. Analizaremos el proceso de importación en detalle en la sección Registro del archivo .dll del complemento en AD FS a continuación.

3. Abra el archivo ThreatDetectionModule.sln del proyecto con Visual Studio.

4. Quite el archivo Microsoft.IdentityServer.dll del Explorador de soluciones como se muestra a continuación:
   

5. Agregue una referencia al archivo Microsoft.IdentityServer.dll de su instancia de AD FS, como se muestra a continuación:

   a. Haga clic con el botón derecho en Referencias en el Explorador de soluciones y elija Agregar referencia....
   

   

   b. En la ventana Administrador de referencias, seleccione Examinar. En el cuadro de diálogo Seleccionar archivos para referencia..., seleccione Microsoft.IdentityServer.dll en la carpeta de instalación de AD FS (en mi caso C:\Windows\ADFS) y haga clic en Agregar.

   Nota

   En mi caso, voy a compilar el complemento en el propio servidor de AD FS. Si su entorno de desarrollo está en otro servidor, copie Microsoft.IdentityServer.dll desde la carpeta de instalación de AD FS en el servidor de AD FS al equipo de desarrollo
   .

   

   c. Haga clic en Aceptar en la ventana Administrador de referencias después de asegurarse de que la casilla Microsoft.IdentityServer.dll está seleccionada.
   

   

6. Todas las clases y referencias están ya listas para llevar a cabo una compilación. Sin embargo, dado que la salida de este proyecto es un archivo .dll, debe instalarse en la caché global de ensamblados, o GAC, del servidor de AD FS y el archivo .dll debe firmarse primero. Se puede hacer de la forma siguiente:

   a. Haga clic con el botón derecho en el nombre del proyecto, ThreatDetectionModule. En el menú, haga clic en Propiedades.
   

   

   b. En la página Propiedades, haga clic en Firma, a la izquierda y seleccione la casilla Firmar el ensamblado. En el menú desplegable Seleccione un archivo de clave de nombre seguro, elija <Nuevo...>.
   

   

   c. En el cuadro de diálogo Crear clave de nombre seguro, escriba un nombre (cualquiera) para la clave y desactive la casilla Proteger mi archivo de clave mediante contraseña. A continuación, haga clic en Aceptar.
   

   

   d. Guarde el proyecto como se muestra a continuación:
   

   

7. Haga clic en Compilar para compilar el proyecto y, a continuación, elija Recompilar solución, como se muestra a continuación:
   

   

   Compruebe la ventana Salida en la parte inferior de la pantalla para ver si se ha producido algún error.
   

   

El complemento (dll) ya está listo para usarlo y se encuentra en la carpeta \bin\Debug de la carpeta del proyecto (en mi caso, C:\extensions\ThreatDetectionModule\bin\Debug\ThreatDetectionModule.dll).

El siguiente paso es registrar este archivo .dll en AD FS para que se ejecute en línea con el proceso de autenticación de AD FS.

Registro del archivo .dll del complemento en AD FS

Es necesario registrar el archivo .dll en AD FS usando el comando Register-AdfsThreatDetectionModule de PowerShell en el servidor de AD FS. Sin embargo, antes del registro, es necesario obtener el token de clave pública. Este token de clave pública se creó cuando creamos la clave y firmamos el archivo .dll con esa clave. Para saber cuál es el token de clave pública del archivo .dll, utilice SN.exe como se indica a continuación:

1. Copie el archivo .dll de la carpeta \bin\Debug en otra ubicación (en mi caso, C:\extensions).

2. Inicie el Símbolo del sistema para desarrolladores de Visual Studio y vaya al directorio que contiene sn.exe (en mi caso, el directorio es C:\Archivos de programa (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.7.2 Tools).

   

3. Ejecute el comando SN con el parámetro -T y la ubicación del archivo (en mi caso, SN -T "C:\extensions\ThreatDetectionModule.dll").

   
   

   El comando le proporciona el token de clave pública (en mi caso, el token de clave pública es 714697626ef96b35).

4. Agregue el archivo .dll a la caché global de ensamblados del servidor de AD FS. El procedimiento recomendado sería crear un instalador adecuado para el proyecto y usarlo para agregar el archivo a la GAC. Otra solución consiste en usar Gacutil.exe en la máquina de desarrollo. Aquí puede consultar más información sobre Gacutil.exe. Puesto que tengo Visual Studio en el mismo servidor que AD FS, usaré Gacutil.exe de la siguiente manera:

   a. En el Símbolo del sistema para desarrolladores de Visual Studio, vaya al directorio que contiene Gacutil.exe (en mi caso, el directorio es C:\Archivos de programa (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.7.2 Tools).

   b. Ejecute el comando Gacutil (en mi caso, Gacutil /IF C:\extensions\ThreatDetectionModule.dll):

   

   Nota:

   Si tiene una granja de AD FS, debe ejecutar lo anterior en cada servidor de AD FS de la granja.

5. Abra Windows PowerShell y ejecute el siguiente comando para registrar el archivo .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>"
   

   En mi caso, el comando es:

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

   Nota

   Solo tiene que registrar el archivo .dll una vez, incluso si tiene una granja de AD FS.

6. Reinicie el servicio AD FS después de registrar el archivo .dll.

Es decir, el archivo .dll ahora está registrado en AD FS y listo para usarlo.

Nota

Si se realizan cambios en el complemento y se recompila el proyecto, es necesario volver a registrar el archivo .dll. Antes del registro, debe anular el registro del archivo .dll actual con el siguiente comando:

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

En mi caso, el comando es:

UnRegister-AdfsThreatDetectionModule -Name "IPBlockPlugin"

Prueba del complemento

1. Abra el archivo authconfig.csv que creamos antes (en mi caso en C:\extensions) y agregue las direcciones IP de la extranet que desea bloquear. Cada dirección IP debe estar en una línea diferente y no debe haber espacios al final.
   

   

2. Guarde y cierre el archivo.

3. Importe el archivo actualizado en AD FS ejecutando el siguiente comando de PowerShell:

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

   En mi caso, el comando es:

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

4. Inicie la solicitud de autenticación desde el servidor con la misma dirección IP que agregó en authconfig.csv.

   Para esta demostración, voy a usar la herramienta Claims X-Ray de la ayuda de AD FS para iniciar una solicitud. Si desea utilizar la herramienta X-Ray, siga las instrucciones.

   Escriba la instancia del servidor de federación y presione el botón Probar autenticación.
   

   

5. La autenticación se bloquea como se muestra a continuación.
   

   

Ahora que sabemos cómo compilar y registrar el complemento, veamos su código para comprender la implementación con las nuevas interfaces y clases introducidas en el modelo.

Tutorial sobre el código del complemento

Abra el proyecto ThreatDetectionModule.sln con Visual Studio y, después, abra el archivo principal UserRiskAnalyzer.cs desde el Explorador de soluciones, a la derecha de la pantalla.

El archivo contiene la clase principal UserRiskAnalyzer que implementa la clase abstracta ThreatDetectionModule y la interfaz IRequestReceivedThreatDetectionModule para leer la dirección IP del contexto de solicitud, comparar la dirección IP obtenida con las direcciones IP cargadas de la base de datos de AD FS y bloquear la solicitud si hay una coincidencia de IP. Veamos estos tipos con más detalle.

Clase abstracta ThreatDetectionModule

Esta clase abstracta carga el complemento en la canalización de AD FS, lo que permite ejecutar el código del complemento en línea con el proceso de 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);
}

La clase incluye los siguientes métodos y propiedades:

Método	Tipo	Definición
OnAuthenticationPipelineLoad	Void	AD FS llama a este método cuando se carga el complemento en su canalización.
OnAuthenticationPipelineUnload	Void	AD FS llama a este método cuando se descarga el complemento de su canalización.
OnConfigurationUpdate	Void	AD FS llama a este método cuando se actualiza la configuración.
Property	Type	Definición
VendorName	String	Obtiene el nombre del proveedor (propietario) del complemento.
ModuleIdentifier	String	Obtiene el identificador del complemento.

En nuestro complemento de ejemplo, usamos los métodos OnAuthenticationPipelineLoad y OnConfigurationUpdate para leer las direcciones IP predefinidas de la base de datos de AD FS. Se llama a OnAuthenticationPipelineLoad cuando se registra el complemento en AD FS, mientras que se llama a OnConfigurationUpdate cuando se importa el archivo .csv con el cmdlet Import-AdfsThreatDetectionModuleConfiguration.

Interfaz IRequestReceivedThreatDetectionModule

Esta interfaz permite implementar la evaluación de riesgos en el momento en el que AD FS recibe la solicitud de autenticación, pero antes de que el usuario escriba las credenciales, es decir, en la fase Solicitud recibida del proceso de autenticación.

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

La interfaz incluye el método EvaluateRequest, que permite usar el contexto de la solicitud de autenticación pasado en el parámetro de entrada requestContext para escribir la lógica de evaluación de riesgos. El parámetro requestContext es de tipo RequestContext.

El otro parámetro de entrada pasado es el registrador, que es del tipo ThreatDetectionLogger. El parámetro se puede usar para escribir los mensajes de error, auditoría o depuración en los registros de AD FS.

El método devuelve ThrottleStatus (0 para NotEvaluated, 1 para Block y 2 para Allow) a AD FS, que bloquea o permite la solicitud.

En nuestro complemento de ejemplo, la implementación del método EvaluateRequest analiza el valor de clientIpAddress del parámetro requestContext y lo compara con todas las direcciones IP cargadas de la base de datos de AD FS. Si encuentra una coincidencia, el método devuelve 2 para Bloquear; de lo contrario, devuelve 1 para Permitir. En función del valor devuelto, AD FS bloquea o permite la solicitud.

Nota

El complemento de ejemplo que hemos descrito antes implementa solo la interfaz IRequestReceivedThreatDetectionModule. Sin embargo, el modelo de evaluación de riesgos proporciona dos interfaces más: IPreAuthenticationThreatDetectionModule (para implementar la lógica de evaluación de riesgos en la fase Autenticación previa) y IPostAuthenticationThreatDetectionModule (para implementar la lógica de evaluación de riesgos durante la fase Autenticación posterior). A continuación, se proporcionan los detalles de las dos interfaces.

Interfaz IPreAuthenticationThreatDetectionModule

Esta interfaz permite implementar la lógica de evaluación de riesgos en el momento en que el usuario proporciona las credenciales, pero antes de que AD FS las evalúe, es decir, la fase Autenticación previa.

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

La interfaz incluye el método EvaluatePreAuthentication, que permite usar la información pasada en los parámetros de entrada RequestContext requestContext, SecurityContext securityContext, ProtocolContext protocolContext y IList<Claim> additionalClams para escribir la lógica de evaluación de riesgos de autenticación previa.

Nota

Para obtener una lista de las propiedades pasadas con cada tipo de contexto, visite las definiciones de clase RequestContext, SecurityContext y ProtocolContext.

El otro parámetro de entrada pasado es el registrador, que es del tipo ThreatDetectionLogger. El parámetro se puede usar para escribir los mensajes de error, auditoría o depuración en los registros de AD FS.

El método devuelve ThrottleStatus (0 para NotEvaluated, 1 para Block y 2 para Allow) a AD FS, que bloquea o permite la solicitud.

Interfaz IPostAuthenticationThreatDetectionModule

Esta interfaz permite implementar la lógica de evaluación de riesgos después de que el usuario ha proporcionado credenciales y AD FS ha realizado la autenticación, es decir, la fase Autenticación posterior.

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

La interfaz incluye el método EvaluatePostAuthentication, que permite usar la información pasada en los parámetros de entrada RequestContext requestContext, SecurityContext securityContext, ProtocolContext protocolContext e IList<Claim> additionalClams para escribir la lógica de evaluación de riesgos de la fase Autenticación posterior.

Nota

Para obtener una lista completa de las propiedades pasadas con cada tipo de contexto, consulte Las definiciones de clase RequestContext, SecurityContext y ProtocolContext.

El otro parámetro de entrada pasado es el registrador, que es del tipo ThreatDetectionLogger. El parámetro se puede usar para escribir los mensajes de error, auditoría o depuración en los registros de AD FS.

El método devuelve la Puntuación de riesgo, que se puede usar en las reglas de notificación y la directiva de AD FS.

Nota

Para que el complemento funcione, la clase principal (en este caso UserRiskAnalyzer) debe derivarse de la clase abstracta ThreatDetectionModule y debe implementar al menos una de las tres interfaces que hemos descrito. Una vez registrado el archivo .dll, AD FS comprueba qué interfaces se implementan y las llama en la fase adecuada de la canalización.

Preguntas más frecuentes

¿Por qué debo crear estos complementos?
R: Estos complementos no solo proporcionan capacidad adicional para proteger su entorno frente a ataques, como los de difusión de contraseñas, sino que también proporcionan la flexibilidad necesaria para crear su propia lógica de evaluación de riesgos en función de sus requisitos.

¿Dónde se capturan los registros?
R: Puede escribir los registros de errores en el registro de eventos "AD FS/Admin" usando el método WriteAdminLogErrorMessage, los registros de auditoría en el registro de seguridad "Auditoría de AD FS" usando el método WriteAuditMessage y los registros de depuración en el registro de depuración "Seguimiento de AD FS" usando el método WriteDebugMessage.

Al agregar estos complementos, ¿puede aumentar la latencia del proceso de autenticación de AD FS?
R: El impacto en la latencia se determina en función del tiempo necesario para ejecutar la lógica de evaluación de riesgos que implemente. Se recomienda evaluar el impacto en la latencia antes de implementar el complemento en el entorno de producción.

¿Por qué AD FS no puede sugerir la lista de direcciones IP, usuarios, etc. de riesgo?
R: Aunque no está disponible actualmente, estamos trabajando en la creación de inteligencia para sugerir direcciones IP, usuarios, etc. de riesgo en el modelo de evaluación de riesgos acoplable. Pronto anunciaremos las fechas de lanzamiento.

¿Qué otros complementos de ejemplo hay disponibles?
R: Están disponibles los siguientes complementos de ejemplo:

Nombre	Descripción
Complemento de usuario de riesgo	Complemento de ejemplo que bloquea la autenticación o aplica MFA en función del nivel de riesgo del usuario determinado por Protección de id. de Microsoft Entra.