Créer des plug-ins avec un modèle d’évaluation des risques AD FS 2019Build Plug-ins with AD FS 2019 Risk Assessment Model

Vous pouvez maintenant créer vos propres plug-ins pour bloquer ou attribuer un score de risque aux demandes d’authentification au cours des différentes étapes : demande reçue, pré-authentification et après authentification.You can now build your own plug-ins to block or assign a risk score to authentication requests during various stages – request received, pre-authentication and post-authentication. Pour ce faire, vous pouvez utiliser le nouveau modèle d’évaluation des risques introduit avec AD FS 2019.This can be accomplished using the new Risk Assessment Model introduced with AD FS 2019.

Qu’est-ce que le modèle d’évaluation des risques ?What is the Risk Assessment Model?

Le modèle d’évaluation des risques est un ensemble d’interfaces et de classes qui permettent aux développeurs de lire les en-têtes de demande d’authentification et d’implémenter leur propre logique d’évaluation des risques.The Risk Assessment Model is a set of interfaces and classes which enable developers to read authentication request headers and implement their own risk assessment logic. Le code implémenté (plug-in) s’exécute ensuite en fonction du processus d’authentification AD FS.The implemented code (plug-in) then runs in line with AD FS authentication process. Par exemple, en utilisant les interfaces et les classes incluses dans le modèle, vous pouvez implémenter le code pour bloquer ou autoriser la demande d’authentification en fonction de l’adresse IP du client incluse dans l’en-tête de demande.For eg, using the interfaces and classes included with the model, you can implement code to either block or allow authentication request based on the client IP address included in the request header. AD FS exécutera le code pour chaque demande d’authentification et prendra les mesures appropriées conformément à la logique implémentée.AD FS will execute the code for each authentication request and take appropriate action as per the implemented logic.

Le modèle autorise le code de plug-in à trois étapes de AD FS pipeline d’authentification, comme indiqué ci-dessous.The model allows to plug-in code at any of three stages of AD FS authentication pipeline as shown below

model

  1. Étape de la demande reçue : active la génération de plug-ins pour autoriser ou bloquer la demande lorsque AD FS reçoit la demande d’authentification, c.-à-d. avant que l’utilisateur entre des informations d’identification.Request Received Stage – Enables building plug-ins to allow or block request when AD FS receives the authentication request i.e. before user enters credentials. Vous pouvez utiliser le contexte de la requête (par exemple, IP du client, méthode http, DNS du serveur proxy, etc.) disponible à ce niveau pour effectuer l’évaluation des risques.You can use the request context (eg, client IP, Http method, proxy server DNS, etc.) available at this stage to perform the risk assessment. Par exemple, vous pouvez créer un plug-in pour lire l’adresse IP à partir du contexte de la demande et bloquer la demande d’authentification si l’adresse IP se trouve dans la liste prédéfinie des adresses IP à risque.For eg, you can build a plug-in to read the IP from the request context and block the authentication request if the IP is in the pre-defined list of risky IPs.

  2. Étape de pré-authentification : permet de créer des plug-ins pour autoriser ou bloquer les demandes au point où l’utilisateur fournit les informations d’identification, mais avant que AD FS les évalue.Pre-Authentication Stage – Enables building plug-ins to allow or block request at the point where user provides the credentials but before AD FS evaluates them. À ce niveau, en plus du contexte de la requête, vous avez également des informations sur le contexte de sécurité (par exemple, jeton d’utilisateur, identificateur d’utilisateur, etc.) et le contexte de protocole (par exemple, le protocole d’authentification, ClientID, ResourceId, etc.) à utiliser dans votre logique d’évaluation des risques.At this stage, in addition to the request context you also have information on the security context (eg, user token, user identifier, etc) and the protocol context (eg, authentication protocol, clientid, resourceid, etc) to use in your risk assessment logic. Par exemple, vous pouvez créer un plug-in pour empêcher les attaques par pulvérisation de mot de passe en lisant le mot de passe utilisateur à partir du jeton de l’utilisateur et en bloquant la demande d’authentification si le mot de passe est dans la liste prédéfinie des mots de passe à risque.For eg, you can build a plug-in to prevent password spray attacks by reading the user password from the user token and blocking the authentication request if the password is in the pre-defined list of risky passwords.

  3. Après l’authentification : active la génération du plug-in pour évaluer les risques après que l’utilisateur a fourni les informations d’identification et que AD FS a effectué l’authentification.Post-Authentication – Enables building plug-in to assess risk after user has provided credentials and AD FS has performed authentication. À ce niveau, en plus du contexte de la requête, du contexte de sécurité et du contexte de protocole, vous avez également des informations sur le résultat de l’authentification (réussite ou échec).At this stage, in addition to the request context, security context, and protocol context, you also have information on the authentication result (Success or Failure). Le plug-in peut évaluer le score de risque en fonction des informations disponibles et passer le score de risque à la revendication et aux règles de stratégie pour une évaluation supplémentaire.The plug-in can evaluate the risk score based on the available information and pass the risk score to claim and policy rules for further evaluation.

Pour mieux comprendre comment créer un plug-in d’évaluation des risques et l’exécuter en ligne avec AD FS processus, nous allons créer un exemple de plug-in qui bloque les demandes provenant de certaines adresses IP extranet identifiées comme étant risquées, enregistrer le plug-in avec AD FS et enfin tester la fonctionnalité.To better understand how to build a risk assessment plug-in and run it in line with AD FS process, let's build a sample plug-in that blocks the requests coming from certain extranet IPs identified as risky, register the plug-in with AD FS and finally test the functionality.

Notes

Vous pouvez également générer un plug-in d’utilisateur à risque, un plug-in d’exemple qui exploite le niveau de risque de l’utilisateur déterminé par Azure ad Identity Protection pour bloquer l’authentification ou appliquer l’authentification multifacteur (MFA).Alternatively, you can build Risky User Plug-in, a sample plug-in that leverages user risk level determined by Azure AD Identity Protection to block authentication or enforce multi-factor authentication (MFA). Les étapes de génération d’un plug-in utilisateur à risque sont disponibles iciSteps to build Risky User Plug-in are available here

Génération d’un exemple de plug-inBuilding a sample plug-in

Notes

Cette procédure pas à pas sert uniquement à vous montrer comment créer un exemple de plug-in.This walkthrough is only to show you how you can create a sample plug-in. En aucun cas, la solution nous crée une solution d’entreprise prête.By no means is the solution we are creating an enterprise ready solution.

Conditions préalablesPre-requisites

Voici la liste des conditions préalables requises pour générer cet exemple de plug-inFollowing is the list of pre-requisites required to build this sample plug-in

  • AD FS 2019 installé et configuréAD FS 2019 installed and configured
  • .NET Framework 4,7 et versions ultérieures.NET Framework 4.7 and above
  • Visual StudioVisual Studio

Dll du plug-in de buildBuild plug-in dll

La procédure suivante vous guidera dans la création d’un exemple de dll de plug-in.The following procedure will walk you through building a sample plug-in dll.

  1. Téléchargez l’exemple de plug-in, utilisez git bash et tapez ce qui suit :Download the sample plug-in, use Git Bash and type the following:

    git clone https://github.com/Microsoft/adfs-sample-RiskAssessmentModel-RiskyIPBlock
    
  2. Créez un fichier . csv à n’importe quel emplacement sur votre serveur AD FS (dans mon cas, j’ai créé le fichier authconfigdb.csv sur C:\Extensions) et j’ajoute les adresses IP que vous souhaitez bloquer à ce fichier.Create a .csv file at any location on your AD FS server (In my case, I created the authconfigdb.csv file at C:\extensions) and add the IPs you want to block to this file.

    L’exemple de plug-in bloque toutes les demandes d’authentification provenant des adresses IP extranet listées dans ce fichier.The sample plug-in will block any authentication requests coming from the Extranet IPs listed in this file.

    {! Remarque : Si vous disposez d’une batterie de serveurs AD FS, vous pouvez créer le fichier sur tout ou partie des serveurs AD FS.{!NOTE] If you have an AD FS Farm, you can create the file on any or all the AD FS servers. N’importe quel fichier peut être utilisé pour importer les adresses IP à risque dans AD FS.Any of the files can be used to import the risky IPs into AD FS. Nous présenterons en détail le processus d’importation dans la section inscrire la dll du plug-in avec AD FS ci-dessous.We will discuss the import process in detail in the Register the plug-in dll with AD FS section below.

  3. Ouvrir le projet ThreatDetectionModule.sln à l’aide de Visual StudioOpen the project ThreatDetectionModule.sln using Visual Studio

  4. Supprimez l Microsoft.IdentityServer.dll 'de l’Explorateur de solutions comme indiqué ci-dessous :Remove the Microsoft.IdentityServer.dll from the Solutions Explorer as shown below:
    modelmodel

  5. Ajoutez une référence à l' Microsoft.IdentityServer.dll de votre AD FS comme indiqué ci-dessousAdd reference to the Microsoft.IdentityServer.dll of your AD FS as shown below

    a.a. Cliquez avec le bouton droit sur références dans l' Explorateur de solutions , puis sélectionnez Ajouter une référence...Right click on References in Solutions Explorer and select Add Reference…
    modelmodel

    b.b. Dans la fenêtre Gestionnaire de références , sélectionnez Parcourir.On the Reference Manager window select Browse. Dans la, sélectionnez les fichiers à référencer...In the Select the files to reference… , sélectionnez dans Microsoft.IdentityServer.dll votre dossier d’installation AD FS (dans mon cas C:\Windows\ADFS), puis cliquez sur Ajouter.dialogue, select Microsoft.IdentityServer.dll from your AD FS installation folder (in my case C:\Windows\ADFS) and click Add.

    Notes

    Dans mon cas, je crée le plug-in sur le serveur AD FS lui-même.In my case I am building the plug-in on the AD FS server itself. Si votre environnement de développement se trouve sur un autre serveur, copiez le Microsoft.IdentityServer.dll à partir de votre dossier d’installation AD FS sur AD FS serveur dans votre boîte de développement.If your development environment is on a different server, copy the Microsoft.IdentityServer.dll from your AD FS installation folder on AD FS server on to your development box.

    model

    c.c. Cliquez sur OK dans la fenêtre Gestionnaire de références après avoir vérifié que la Microsoft.IdentityServer.dll case est cochée.Click OK on the Reference Manager window after making sure Microsoft.IdentityServer.dll checkbox is selected
    modelmodel

  6. Toutes les classes et références sont maintenant en place pour effectuer une génération.All the classes and references are now in place to do a build. Toutefois, étant donné que la sortie de ce projet est une dll, elle doit être installée dans le global assembly cache(GAC) du serveur AD FS et la dll doit d’abord être signée.However, since the output of this project is a dll, it will have to be installed into the Global Assembly Cache, or GAC, of the AD FS server and the dll needs to be signed first. Pour cela, procédez comme suit :This can be done as follows:

    a.a. Cliquez avec le bouton droit sur le nom du projet, ThreatDetectionModule.Right-click on the name of the project, ThreatDetectionModule. Dans le menu, cliquez sur Propriétés.From the menu, click Properties.
    modelmodel

    b.b. Dans la page Propriétés , cliquez sur signature, à gauche, puis cochez la case signer l’assembly.From the Properties page, click Signing, on the left, and then check the checkbox marked Sign the assembly. Dans le menu déroulant choisir un fichier de clé de nom fort:, sélectionnez <nouveau... >From the Choose a strong name key file: pull down menu, select <New...>
    modelmodel

    c.c. Dans la boîte de dialogue créer une clé de nom fort, tapez un nom (vous pouvez choisir n’importe quel nom) pour la clé, désactivez la case à cocher protéger mon fichier de clé par un mot de passe.In the Create Strong Name Key dialogue, type a name (you can choose any name) for the key, uncheck the checkbox Protect my key file with password. Cliquez ensuite sur OK.Then, click OK.
    modelmodel

    d.d. Enregistrez le projet comme indiqué ci-dessousSave the project as shown below
    modelmodel

  7. Générez le projet en cliquant sur générer , puis sur régénérer la solution comme indiqué ci-dessousBuild the project by clicking Build and then Rebuild Solution as shown below
    modelmodel

    Vérifiez la fenêtre Sortie, en bas de l’écran, pour voir si des erreurs se sont produites.Check the Output window, at the bottom of the screen, to see if any errors occurred
    modelmodel

Le plug-in (dll) est maintenant prêt à être utilisé et se trouve dans le dossier \bin\Debug du dossier du projet (dans mon cas, c’est C:\extensions\ThreatDetectionModule\bin\Debug\ThreatDetectionModule.dll).The plug-in (dll) is now ready for use and is in the \bin\Debug folder of the project folder (In my case, that's C:\extensions\ThreatDetectionModule\bin\Debug\ThreatDetectionModule.dll).

L’étape suivante consiste à inscrire cette dll auprès de AD FS, afin qu’elle s’exécute en fonction du processus d’authentification AD FS.The next step is to register this dll with AD FS, so it runs in line with AD FS authentication process.

Inscrire la dll du plug-in avec AD FSRegister the plug-in dll with AD FS

Nous devons inscrire la dll dans AD FS à l’aide de la Register-AdfsThreatDetectionModule commande PowerShell sur le serveur de AD FS. Toutefois, avant de vous inscrire, nous devons récupérer le jeton de clé publique.We need to register the dll in AD FS by using the Register-AdfsThreatDetectionModule PowerShell command on the AD FS server, however, before we register, we need to get the Public Key Token. Ce jeton de clé publique a été créé lors de la création de la clé et de la signature de la dll à l’aide de cette clé.This public key token was created when we created the key and signed the dll using that key. Pour en savoir plus sur le jeton de clé publique de la dll, vous pouvez utiliser la SN.exe comme suit :To learn what the Public Key Token for the dll is, you can use the SN.exe as follows

  1. Copiez le fichier dll du dossier \bin\Debug vers un autre emplacement (dans mon cas, en le copiant dans C:\Extensions)Copy the dll file from the \bin\Debug folder to another location (In my case copying it to C:\extensions)

  2. Démarrez le invite de commandes développeur pour Visual Studio et accédez au répertoire contenant le sn.exe (dans mon cas, le répertoire est C:\Program Files (x86) \Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.7.2 Tools)  ModelStart the Developer Command Prompt for Visual Studio and go to the directory containing the sn.exe (In my case the directory is C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.7.2 Tools) model

  3. Exécutez la commande sn avec le paramètre -T et l’emplacement du fichier (dans mon cas SN -T "C:\extensions\ThreatDetectionModule.dll" ). Run the SN command with the -T parameter and the location of the file (In my case SN -T "C:\extensions\ThreatDetectionModule.dll") model
    La commande vous fournira le jeton de clé publique (pour moi, le jeton de clé publique est 714697626ef96b35)The command will provide you the public key token (For me, the Public Key Token is 714697626ef96b35)

  4. Ajoutez la dll au global assembly cache du serveur AD FS. nous vous conseillons de créer un programme d’installation approprié pour votre projet et d’utiliser le programme d’installation pour ajouter le fichier au GAC.Add the dll to the Global Assembly Cache of the AD FS server Our best practice would be that you create a proper installer for your project and use the installer to add the file to the GAC. Une autre solution consiste à utiliser Gacutil.exe (pour plus d’informations sur les Gacutil.exe disponibles ici) sur votre ordinateur de développement.Another solution is to use Gacutil.exe (more information on Gacutil.exe available here) on your development machine. Comme j’ai mon Visual Studio sur le même serveur que AD FS, j’utilise Gacutil.exe comme suitSince I have my visual studio on the same server as AD FS, I will be using Gacutil.exe as follows

    a.a. Sur Invite de commandes développeur pour Visual Studio et accédez au répertoire contenant le Gacutil.exe (dans mon cas, le répertoire est C:\Program Files (x86) \Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.7.2 Tools)On Developer Command Prompt for Visual Studio and go to the directory containing the Gacutil.exe (In my case the directory is C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.7.2 Tools)

    b.b. Exécuter le modèle de commande gacutil (dans mon cas Gacutil /IF C:\extensions\ThreatDetectionModule.dll ) Run the Gacutil command (In my case Gacutil /IF C:\extensions\ThreatDetectionModule.dll) model

    Notes

    Si vous disposez d’une batterie de serveurs AD FS, les éléments ci-dessus doivent être exécutés sur chaque serveur de AD FS de la batterie.If you have an AD FS farm, the above needs to be executed on each AD FS server in the farm.

  5. Ouvrez Windows PowerShell et exécutez la commande suivante pour inscrire la dllOpen Windows PowerShell and run the following command to register the 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>"
    

    Dans mon cas, la commande est :In my case, the command is:

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

    Notes

    Vous devez inscrire la dll une seule fois, même si vous disposez d’une batterie de AD FS.You need to register the dll only once, even if you have an AD FS farm.

  6. Redémarrer le service AD FS après l’inscription de la dllRestart the AD FS service after registering the dll

C’est là que la dll est maintenant enregistrée avec AD FS et prête à l’emploi.That's it, the dll is now registered with AD FS and ready for use!

Notes

Si des modifications sont apportées au plug-in et que le projet est régénéré, la dll mise à jour doit être inscrite à nouveau.If any changes are made to the plugin and the project is rebuilt, then the updated dll needs to be registered again. Avant de procéder à l’inscription, vous devrez annuler l’inscription de la dll actuelle à l’aide de la commande suivante :Before registering, you will need to unregister the current dll using the following command:

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

Dans mon cas, la commande est :In my case, the command is:

UnRegister-AdfsThreatDetectionModule -Name "IPBlockPlugin"

Test du plug-inTesting the plug-in

  1. Ouvrez le fichier authconfig.csv que nous avons créé précédemment (dans mon cas, à l’emplacement C:\Extensions) et ajoutez les adresses IP extranet que vous souhaitez bloquer.Open the authconfig.csv file we created earlier (in my case at location C:\extensions) and add the Extranet IPs you want to block. Chaque adresse IP doit se trouver sur une ligne distincte et il ne doit y avoir aucun espace à la finEvery IP should be on a separate line and there should be no spaces at the end
    modelmodel

  2. Enregistrez et fermez le fichier.Save and close the file

  3. Importez le fichier mis à jour dans AD FS en exécutant la commande PowerShell suivanteImport the updated file in AD FS by running the following PowerShell command

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

    Dans mon cas, la commande est :In my case, the command is:

    Import-AdfsThreatDetectionModuleConfiguration -name "IPBlockPlugin" -ConfigurationFilePath "C:\extensions\authconfigdb.csv")
    
  4. Initiez une demande d’authentification à partir du serveur avec la même adresse IP que celle que vous avez ajoutée dans authconfig.csv.Initiate authentication request from the server with the same IP you added in authconfig.csv.

    Pour cette démonstration, j’utiliserai AD FS l’aide de l' outil de radiographie pour lancer une demande.For this demonstration, I will be using AD FS Help Claims X-Ray tool to initiate a request. Si vous souhaitez utiliser l’outil de rayon X, suivez les instructionsIf you would like to use the X-Ray tool, please follow the instructions

    Entrez l’instance du serveur de Fédération et le bouton d’authentification du test de positionnement.Enter federation server instance and hit Test Authentication button.
    modelmodel

  5. L’authentification est bloquée comme indiqué ci-dessous.Authentication is blocked as shown below.
    modelmodel

Maintenant que nous savons comment générer et inscrire le plug-in, voyons pas à pas le code de plug-in pour comprendre l’implémentation à l’aide des nouvelles interfaces et classes introduites avec le modèle.Now that we know how to build and register the plug-in, let's walkthrough the plug-in code to understand the implementation using the new interfaces and classes introduced with the model.

Procédure pas à pas de code de plug-inPlug-in code walkthrough

Ouvrez le projet ThreatDetectionModule.sln à l’aide de Visual Studio, puis ouvrez le fichier principal UserRiskAnalyzer.cs à partir de l' Explorateur de solutions à droite de l’écran.Open the project ThreatDetectionModule.sln using Visual Studio and then open the main file UserRiskAnalyzer.cs from the Solutions Explorer on the right of the screen
modelmodel

Le fichier contient la classe principale UserRiskAnalyzer qui implémente les classes abstraites ThreatDetectionModule et interface IRequestReceivedThreatDetectionModule pour lire l’adresse IP à partir du contexte de la requête, comparer l’adresse IP obtenue avec les adresses IP chargées à partir de AD FS DB et bloquer la demande en cas de correspondance d’adresse IP.The file contains the main class UserRiskAnalyzer which implements the abstract class ThreatDetectionModule and interface IRequestReceivedThreatDetectionModule to read the IP from the request context, compare the obtained IP with the IPs loaded from AD FS DB, and block request if there is an IP match. Passons en revue ces types plus en détailLet's go over these types in more detail

Classe abstraite ThreatDetectionModuleThreatDetectionModule abstract class

Cette classe abstraite charge le plug-in dans AD FS pipeline, ce qui permet d’exécuter le code de plug-in en ligne avec AD FS processus.This abstract class loads the plug-in into AD FS pipeline making it possible to run the plug-in code in line with AD FS process.

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 classe comprend les méthodes et les propriétés suivantes.The class includes following methods and properties.

MéthodeMethod TypeType DéfinitionDefinition
OnAuthenticationPipelineLoadOnAuthenticationPipelineLoad VoidVoid Appelé par AD FS lorsque le plug-in est chargé dans son pipelineCalled by AD FS when the plugin is loaded into its pipeline
OnAuthenticationPipelineUnloadOnAuthenticationPipelineUnload VoidVoid Appelé par AD FS lorsque le plug-in est déchargé de son pipelineCalled by AD FS when the plugin is unloaded from its pipeline
OnConfigurationUpdateOnConfigurationUpdate VoidVoid Appelé par AD FS sur la mise à jour de la configurationCalled by AD FS on config update
PropriétéProperty TypeType DéfinitionDefinition
NomFournisseurVendorName StringString Obtient le nom du fournisseur propriétaire du plug-in.Gets the name of the vendor owning the plugin
ModuleIdentifierModuleIdentifier StringString Obtient l’identificateur du plug-in.Gets the identifier of the plugin

Dans notre exemple de plug-in, nous utilisons les méthodes OnAuthenticationPipelineLoad et OnConfigurationUpdate pour lire les adresses IP prédéfinies à partir de AD FS DB.In our sample plugin, we are using OnAuthenticationPipelineLoad and OnConfigurationUpdate methods to read the pre-defined IPs from AD FS DB. OnAuthenticationPipelineLoad est appelé quand le plug-in est inscrit avec AD FS tandis que OnConfigurationUpdate est appelé lorsque le fichier. csv est importé à l’aide de l’applet de commande Import-AdfsThreatDetectionModuleConfiguration .OnAuthenticationPipelineLoad is called when plug-in is registered with AD FS while OnConfigurationUpdate is called when the .csv is imported using the Import-AdfsThreatDetectionModuleConfiguration cmdlet.

Interface IRequestReceivedThreatDetectionModuleIRequestReceivedThreatDetectionModule Interface

Cette interface vous permet d’implémenter l’évaluation des risques au point où AD FS reçoit la demande d’authentification, mais avant que l’utilisateur n’entre les informations d’identification, c’est-à-dire à l’étape de demande reçue du processus d’authentification.This interface enables you to implement risk assessment at the point where AD FS receives the authentication request but before user enters credentials i.e. at Received Request stage of the authentication process.

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

L’interface comprend la méthode EvaluateRequest qui vous permet d’utiliser le contexte de la demande d’authentification passée dans le paramètre d’entrée RequestContext pour écrire votre logique d’évaluation des risques.The interface includes EvaluateRequest method which allows you to use the context of the authentication request passed in the requestContext input parameter to write your risk assessment logic. Le paramètre requestContext est de type RequestContext.The requestContext parameter is of type RequestContext.

L’autre paramètre d’entrée passé est Logger, qui est de type ThreatDetectionLogger.The other input parameter passed is logger which is type ThreatDetectionLogger. Le paramètre peut être utilisé pour écrire les messages d’erreur, d’audit et/ou de débogage dans AD FS journaux.The parameter can be used to write the error, audit and/or debug messages to AD FS logs.

La méthode retourne ThrottleStatus (0 si NotEvaluated, 1 à Block et 2 to allow) à AD FS qui bloque ou autorise ensuite la requête.The method returns ThrottleStatus (0 if NotEvaluated, 1 to Block, and 2 to Allow) to AD FS which then either blocks or allows the request.

Dans notre exemple de plug-in, l’implémentation de la méthode EvaluateRequest analyse le clientIpAddress à partir du paramètre RequestContext et le compare à toutes les adresses IP chargées à partir de la base de AD FS DB.In our sample plug-in, EvaluateRequest method implementation parses the clientIpAddress from the requestContext parameter and compares it with all the IPs loaded from the AD FS DB. Si une correspondance est trouvée, la méthode retourne 2 pour le bloc, sinon elle retourne 1 pour allow.If a match is found, method returns 2 for Block, else it returns 1 for Allow. En fonction de la valeur retournée, AD FS bloque ou autorise la demande.Based on the returned value, AD FS either blocks or allows the request.

Notes

L’exemple de plug-in abordé ci-dessus implémente uniquement l’interface IRequestReceivedThreatDetectionModule.The sample plug-in discussed above implements only IRequestReceivedThreatDetectionModule interface. Toutefois, le modèle d’évaluation des risques fournit deux interfaces supplémentaires : IPreAuthenticationThreatDetectionModule (pour implémenter la logique d’évaluation des risques au cours étape de pré-authentification) et IPostAuthenticationThreatDetectionModule (pour implémenter la logique d’évaluation des risques pendant la phase de postconnexion).However, the risk assessment model provides two additional interfaces –IPreAuthenticationThreatDetectionModule (to implement risk assessment logic duing pre-authentication stage) and IPostAuthenticationThreatDetectionModule (to implement risk assessment logic during post-authentication stage). Les détails sur les deux interfaces sont fournis ci-dessous.The details on the two interfaces are provided below.

Interface IPreAuthenticationThreatDetectionModuleIPreAuthenticationThreatDetectionModule Interface

Cette interface vous permet d’implémenter la logique d’évaluation des risques au point où l’utilisateur fournit les informations d’identification, mais avant AD FS les évalue, c.-à-d. l’étape de pré-authentification.This interface enables you to implement risk assessment logic at the point where user provides the credentials but before AD FS evaluates them i.e. pre-authentication stage.

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

L’interface comprend la méthode EvaluatePreAuthentication qui vous permet d’utiliser les informations passées dans les paramètres d’entrée RequestContext RequestContext, SecurityContext SecurityContext, ProtocolContext ProtocolContextet IList additionalClams pour écrire votre logique d’évaluation des risques de pré-authentification.The interface includes EvaluatePreAuthentication method which allows you to use the information passed in the RequestContext requestContext, SecurityContext securityContext, ProtocolContext protocolContext, and IList additionalClams input parameters to write your pre-authentication risk assessment logic.

Notes

Pour obtenir la liste des propriétés transmises avec chaque type de contexte, visitez les définitions de classe RequestContext, SecurityContextet ProtocolContext .For list of properties passed with each context type, visit RequestContext, SecurityContext, and ProtocolContext class definitions.

L’autre paramètre d’entrée passé est Logger, qui est de type ThreatDetectionLogger.The other input parameter passed is logger which is type ThreatDetectionLogger. Le paramètre peut être utilisé pour écrire les messages d’erreur, d’audit et/ou de débogage dans AD FS journaux.The parameter can be used to write the error, audit and/or debug messages to AD FS logs.

La méthode retourne ThrottleStatus (0 si NotEvaluated, 1 à Block et 2 to allow) à AD FS qui bloque ou autorise ensuite la requête.The method returns ThrottleStatus (0 if NotEvaluated, 1 to Block, and 2 to Allow) to AD FS which then either blocks or allows the request.

Interface IPostAuthenticationThreatDetectionModuleIPostAuthenticationThreatDetectionModule Interface

Cette interface vous permet d’implémenter la logique d’évaluation des risques une fois que l’utilisateur a fourni les informations d’identification et que AD FS a effectué l’authentification, c.-à-d. l’étape de postconnexion.This interface enables you to implement risk assessment logic after user has provided credentials and AD FS has performed authentication i.e. post-authentication stage.

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

L’interface comprend la méthode EvaluatePostAuthentication qui vous permet d’utiliser les informations passées dans les paramètres d’entrée RequestContext RequestContext, SecurityContext SecurityContext, ProtocolContext ProtocolContextet IList additionalClams pour écrire votre logique d’évaluation des risques après l’authentification.The interface includes EvaluatePostAuthentication method which allows you to use the information passed in the RequestContext requestContext, SecurityContext securityContext, ProtocolContext protocolContext, and IList additionalClams input parameters to write your post-authentication risk assessment logic.

Notes

Pour obtenir la liste complète des propriétés transmises avec chaque type de contexte, consultez les définitions de classe RequestContext, SecurityContextet ProtocolContext .For complete list of properties passed with each context type, refer RequestContext, SecurityContext, and ProtocolContext class definitions.

L’autre paramètre d’entrée passé est Logger, qui est de type ThreatDetectionLogger.The other input parameter passed is logger which is type ThreatDetectionLogger. Le paramètre peut être utilisé pour écrire les messages d’erreur, d’audit et/ou de débogage dans AD FS journaux.The parameter can be used to write the error, audit and/or debug messages to AD FS logs.

La méthode retourne le score de risque qui peut être utilisé dans AD FS règles de stratégie et de revendication.The method returns the Risk Score which can be used in AD FS policy and claim rules.

Notes

Pour que le plug-in fonctionne, la classe principale (dans ce cas UserRiskAnalyzer) doit dériver la classe abstraite ThreatDetectionModule et doit implémenter au moins l’une des trois interfaces décrites ci-dessus.For plug-in to work, the main class (in this case UserRiskAnalyzer) needs to derive ThreatDetectionModule abstract class and should implement at least one of the three interfaces described above. Une fois la dll inscrite, AD FS vérifie les interfaces qui sont implémentées et les appelle à l’étape appropriée dans le pipeline.Once the dll is registered, AD FS checks which of the interfaces are implemented and calls them at appropriate stage in the pipeline.

FAQFAQs

Pourquoi dois-je créer ces plug-ins ?Why should I build these plug-ins?
R : Ces plug-ins vous offrent non seulement des fonctionnalités supplémentaires pour sécuriser votre environnement contre les attaques telles que les attaques par pulvérisation de mot de passe, mais également la possibilité de créer votre propre logique d’évaluation des risques en fonction de vos besoins.A: These plug-ins not only provide you additional capability to secure your environment from attacks such as password spray attacks, but also give you the flexibility to build your own risk assessment logic based on your requirements.

Où les journaux sont-ils capturés ?Where are the logs captured?
R : Vous pouvez écrire les journaux d’erreurs dans le journal des événements « AD FS/admin » à l’aide de la méthode WriteAdminLogErrorMessage, les journaux d’audit dans le journal de sécurité « AD FS audit » à l’aide de la méthode WriteAuditMessage et les journaux de débogage dans le journal de débogage « AD FS Tracing » en utilisant la méthodeA: You can write error logs to "AD FS/Admin" event log using WriteAdminLogErrorMessage method, audit logs to "AD FS Auditing" security log using WriteAuditMessage method and debug logs to "AD FS Tracing" debug log using WriteDebugMessage method.

L’ajout de ces plug-ins augmente-t-il AD FS latence du processus d’authentification ?Can adding these plug-ins increase AD FS authentication process latency?
R : L’impact de la latence sera déterminé par le temps nécessaire à l’exécution de la logique d’évaluation des risques que vous implémentez.A: Latency impact will be determined by the time taken to execute the risk assessment logic you implement. Nous vous recommandons d’évaluer l’impact de la latence avant de déployer le plug-in dans l’environnement de production.We recommend evaluating the latency impact before deploying the plug-in in production enviroment.

Pourquoi ne puis-je pas AD FS suggérer la liste des adresses IP risquées, des utilisateurs, etc. ?Why can't AD FS suggest the list of risky IPs, users, etc?
R : Bien qu’elles ne soient pas disponibles actuellement, nous travaillons sur la création de l’intelligence pour suggérer des adresses IP à risque, des utilisateurs, etc. dans le modèle d’évaluation des risques enfichables.A: Though not currently available, we are working on building the intelligence to suggest risky IPs, users, etc. in the Pluggable Risk Assessment Model. Nous allons bientôt partager les dates de lancement.We will share the launch dates soon.

Quels sont les autres plug-ins d’exemples disponibles ?What other sample plug-ins are available?
R : Les exemples de plug-ins suivants sont disponibles :A: The following sample plug-in(s) are available:

NomName DescriptionDescription
Plug-in utilisateur à risqueRisky User Plug-in Exemple de plug-in qui bloque l’authentification ou applique l’authentification MFA en fonction du niveau de risque de l’utilisateur déterminé par Azure AD Identity Protection.Sample plug-in that blocks authentication or enforces MFA based on user risk level determined by Azure AD Identity Protection.