Créer des plug-ins avec un modèle d’évaluation des risques AD FS 2019

  • Article

Vous pouvez maintenant créer vos propres plug-ins pour bloquer ou affecter un score de risque aux demandes d’authentification au cours de différentes étapes : demande reçue, pré-authentification et post-authentification. Pour ce faire, utilisez le nouveau modèle d’évaluation des risques introduit avec AD FS 2019.

Qu’est-ce que le modèle d’évaluation des risques ?

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. Le code implémenté (plug-in) s’exécute ensuite conformément au processus d’authentification AD FS. Par exemple, à l’aide des interfaces et des classes incluses dans le modèle, vous pouvez implémenter du code pour bloquer ou autoriser la demande d’authentification en fonction de l’adresse IP du client incluse dans l’en-tête de la demande. AD FS exécute le code pour chaque demande d’authentification et prend les mesures appropriées conformément à la logique implémentée.

Le modèle permet de créer du code de plug-in à l’une des trois étapes du pipeline d’authentification AD FS, comme indiqué ci-dessous :

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

  1. Étape de réception de la demande : permet de créer des plug-ins pour autoriser ou bloquer la demande quand AD FS reçoit la demande d’authentification, c’est-à-dire avant que l’utilisateur entre les informations d’identification. Vous pouvez utiliser le contexte de requête (par exemple, adresse IP cliente, méthode HTTP, DNS du serveur proxy, etc.) disponible à ce stade pour effectuer l’évaluation des risques. 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 figure dans la liste prédéfinie des adresses IP à risque.

  2. Étape de pré-authentification : permet de créer des plug-ins pour autoriser ou bloquer la demande au moment où l’utilisateur fournit les informations d’identification, mais avant qu’AD FS les évalue. À ce stade, en plus du contexte de la demande, vous disposez également d’informations sur le contexte de sécurité (par exemple, jeton d’utilisateur, identificateur d’utilisateur, etc.) et le contexte de protocole (par exemple, protocole d’authentification, clientID, resourceID, etc.) à utiliser dans votre logique d’évaluation des risques. 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 utilisateur et en bloquant la demande d’authentification si le mot de passe figure dans la liste prédéfinie des mots de passe à risque.

  3. Post-authentification : permet de créer un plug-in pour évaluer les risques une fois que l’utilisateur a fourni des informations d’identification et qu’AD FS a effectué l’authentification. À ce stade, en plus du contexte de requête, du contexte de sécurité et du contexte de protocole, vous disposez également d’informations sur le résultat de l’authentification (réussite ou échec). Le plug-in peut évaluer le score de risque en fonction des informations disponibles et passer le score de risque pour réclamer et les règles de stratégie pour une évaluation plus approfondie.

Pour mieux comprendre comment créer un plug-in d’évaluation des risques et l’exécuter conformément avec le processus AD FS, nous allons créer un exemple de plug-in qui bloque les demandes provenant de certaines adresses IP d’extranet identifiées comme risquées, inscrire le plug-in auprès d’AD FS et enfin tester la fonctionnalité.

Remarque

Vous pouvez également créer un Module d'utilisateur à risque, un échantillon de module qui tire parti du niveau de risque utilisateur déterminé par Protection des Microsoft Entra ID pour bloquer l'authentification ou appliquer Multi-Factor Authentication (MFA). Les étapes de création du plug-in d’utilisateur à risque sont disponibles ici.

Création d’un exemple de plug-in

Notes

Cette procédure pas à pas vous montre uniquement comment créer un exemple de plug-in. La solution que nous créons n’est en aucun cas une solution prête pour une entreprise.

Conditions préalables

Voici la liste des conditions préalables requises pour générer cet exemple de plug-in :

  • AD FS 2019 installé et configuré
  • .NET framework 4.7 et versions ultérieures
  • Visual Studio

Générer une dll de plug-in

La procédure suivante vous guide tout au long de la création d’un exemple de dll de plug-in :

  1. Téléchargez l’exemple de plug-in, utilisez Git Bash et tapez ce qui suit :

    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 dans C:\extensions) et ajoutez les adresses IP que vous souhaitez bloquer à ce fichier.

    L’exemple de plug-in bloque toutes les demandes d’authentification provenant des adresses IP d’extranet répertoriées dans ce fichier.

    Notes

    Si vous disposez d’une batterie AD FS, vous pouvez créer le fichier sur tous les serveurs AD FS. Tous les fichiers peuvent être utilisés pour importer les adresses IP à risque dans AD FS. Nous aborderons le processus d’importation en détail dans la section Inscrire la dll de plug-in auprès d’AD FS ci-dessous.

  3. Ouvrez le projet ThreatDetectionModule.sln à l’aide de Visual Studio.

  4. Supprimez le Microsoft.IdentityServer.dll de l’Explorateur de solutions comme indiqué ci-dessous :
    Screenshot that highlights the Remove menu option.

  5. Ajoutez une référence au Microsoft.IdentityServer.dll de votre instance AD FS comme indiqué ci-dessous :

    a. Cliquez avec le bouton droit sur Références dans l’Explorateur de solutions, puis sélectionnez Ajouter une référence....

    Screenshot that highlights the Add Reference menu option.

    b. Dans la fenêtre Gestionnaire de références, sélectionnez Parcourir. Dans la boîte de dialogue Sélectionner les fichiers à référencer..., sélectionnez Microsoft.IdentityServer.dll dans votre dossier d’installation AD FS (dans mon cas C:\Windows\ADFS), puis sélectionnez Ajouter.

    Remarque

    Dans mon cas, je crée le plug-in sur le serveur AD FS lui-même. 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 le serveur AD FS sur vers votre zone de développement.

    Screenshot that shows the file you should copy.

    c. Cliquez sur OK dans la fenêtre Gestionnaire de références après avoir vérifié que la case à cocher Microsoft.IdentityServer.dll est activée.

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

  6. Toutes les classes et références sont désormais en place pour effectuer une build. Toutefois, étant donné que la sortie de ce projet est une dll, il doit être installé dans le Global Assembly Cache, ou GAC, du serveur AD FS, et la dll doit d’abord être signée. Pour cela, procédez comme suit :

    a. Cliquez avec le bouton droit sur le nom du projet, ThreatDetectionModule. Dans le menu, cliquez sur Propriétés.

    Screenshot that highlights the Properties menu option.

    b. Dans la page Propriétés, cliquez sur Signature, à gauche, puis cochez la case Signer l’assembly. Dans le menu déroulant Choisir un fichier de clé de nom fort :, sélectionnez <Nouveau...>.

    Screenshot that shows the Sign the assembly checkbox.

    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écochez la case Protéger mon fichier de clé avec un mot de passe. Cliquez ensuite sur OK.

    Screenshot that shows Protect my key file with password checkbox.

    d. Enregistrez le projet comme indiqué ci-dessous :

    Screenshot that shows where to save your project.

  7. Générez le projet en cliquant sur Générer, puis sur Reconstruire la solution comme indiqué ci-dessous :

    Screenshot that shows the Rebuild Solution menu option.

    Vérifiez la fenêtre Sortie en bas de l’écran pour voir si des erreurs se sont produites
    .

    Screenshot that shows the output from the rebuilt solution.

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:\extensions\ThreatDetectionModule\bin\Debug\ThreatDetectionModule.dll).

L’étape suivante consiste à inscrire cette dll auprès d’AD FS, afin qu’elle s’exécute conformément au processus d’authentification AD FS.

Inscrire la dll de plug-in auprès d’AD FS

Nous devons inscrire la dll dans AD FS à l’aide de la commande PowerShell Register-AdfsThreatDetectionModule sur le serveur AD FS. Toutefois, avant de nous inscrire, nous devons obtenir le jeton de clé publique. Ce jeton de clé publique a été créé lorsque nous avons créé la clé et signé la dll à l’aide de cette clé. Pour savoir quel est le jeton de clé publique pour la dll, vous pouvez utiliser SN.exe comme suit :

  1. Copiez le fichier dll du dossier \bin\Debug vers un autre emplacement (dans mon cas, en le copiant dans C:\extensions).

  2. Démarrez l’invite de commandes développeur pour Visual Studio et accédez au répertoire contenant sn.exe (dans mon cas, le répertoire est 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. Exécutez la commande SN avec le paramètre -T et l’emplacement du fichier (dans mon cas SN -T "C:\extensions\ThreatDetectionModule.dll").

    Screenshot that shows how to run the S N command.

    La commande vous fournira le jeton de clé publique (pour moi, le jeton de clé publique est 714697626ef96b35)

  4. Ajouter la dll au Global Assembly Cache du serveur AD FS. Notre recommandation est de créer un programme d’installation approprié pour votre projet et d’utiliser le programme d’installation pour ajouter le fichier au GAC. Une autre solution consiste à utiliser Gacutil.exe (plus d’informations sur Gacutil.exe disponibles ici) sur votre ordinateur de développement. Étant donné que j’ai Visual Studio sur le même serveur qu’AD FS, j’utiliserai Gacutil.exe comme suit :

    a. À l’invite de commandes développeur pour Visual Studio, accédez au répertoire contenant Gacutil.exe (dans mon cas, le répertoire est C:\Program Files (x86)\Microsoft SDK\Windows\v10.0A\bin\NETFX 4.7.2 Tools).

    b. Exécutez la commande Gacutil (dans mon cas Gacutil /IF C:\extensions\ThreatDetectionModule.dll) :

    Screenshot that shows how to run the Gacutil command.

    Note

    Si vous disposez d’une batterie AD FS, ce qui précède doit être exécuté sur chaque serveur AD FS de la batterie.

  5. Ouvrez Windows PowerShell et exécutez la commande suivante pour inscrire la 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 :

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

    Notes

    Vous ne devez inscrire la dll qu’une seule fois, même si vous disposez d’une batterie AD FS.

  6. Redémarrez le service AD FS après avoir inscrit la dll.

Voilà, la dll est maintenant inscrite auprès d’AD FS et prête à être utilisée !

Notes

Si des modifications sont apportées au plug-in et que le projet est reconstruit, la dll mise à jour doit être inscrite à nouveau. Avant de vous inscrire, vous devez annuler l’inscription de la dll active à l’aide de la commande suivante :

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



Dans mon cas, la commande est :

UnRegister-AdfsThreatDetectionModule -Name "IPBlockPlugin"

Test du 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 d’extranet que vous souhaitez bloquer. Chaque adresse IP doit se trouver sur une ligne distincte et il ne doit y avoir aucun espace à la fin.

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

  2. Enregistrez et fermez le fichier.

  3. Importez le fichier mis à jour dans AD FS en exécutant la commande PowerShell suivante :

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

    Dans mon cas, la commande est :

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

  4. Lancez la demande d’authentification à partir du serveur avec la même adresse IP que celle que vous avez ajoutée dans authconfig.csv.

    Pour cette démonstration, je vais utiliser l’outil X-Ray d’aide AD FS pour lancer une demande. Si vous souhaitez utiliser l’outil X-Ray, suivez les instructions

    Entrez l’instance du serveur de fédération et appuyez sur le bouton Tester l’authentification.

    Screenshot that shows the Test Authentication button.

  5. L’authentification est bloquée comme montré ci-dessous.

    Screenshot that shows that authentication is blocked.

Maintenant que nous savons comment générer et inscrire le plug-in, passons en revue le code du plug-in pour comprendre l’implémentation à l’aide des nouvelles interfaces et classes introduites avec le modèle.

Procédure pas à pas du code de plug-in

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

model

Le fichier contient la classe principale UserRiskAnalyzer qui implémente la classe abstraite ThreatDetectionModule et l’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 la base de données AD FS et bloquer la demande en cas de correspondance d’IP. Examinons ces types plus en détail

Classe abstraite ThreatDetectionModule

Cette classe abstraite charge le plug-in dans le pipeline AD FS, ce qui permet d’exécuter le code du plug-in conformément au processus 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 classe inclut les méthodes et propriétés suivantes :

Méthode Type Définition
OnAuthenticationPipelineLoad Void Appelé par AD FS lorsque le plug-in est chargé dans son pipeline
OnAuthenticationPipelineUnload Void Appelé par AD FS lorsque le plug-in est déchargé de son pipeline
OnConfigurationUpdate Void Appelé par AD FS lors de la mise à jour de la configuration
Propriété Type Définition
VendorName String Obtient le nom du fournisseur propriétaire du plug-in
ModuleIdentifier String Obtient l’identificateur du plug-in

Dans notre exemple de plug-in, nous utilisons les méthodes OnAuthenticationPipelineLoad et OnConfigurationUpdate pour lire les adresses IP prédéfinies à partir de la base de données AD FS. OnAuthenticationPipelineLoad est appelé lorsque le plug-in est inscrit auprès d’AD FS, tandis qu’OnConfigurationUpdate est appelé lorsque le .csv est importé à l’aide de l’applet de commande Import-AdfsThreatDetectionModuleConfiguration.

IRequestReceivedThreatDetectionModule, interface

Cette interface vous permet d’implémenter l’évaluation des risques au moment 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 Demande reçue du processus d’authentification.

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

L’interface inclut la méthode EvaluateRequest qui vous permet d’utiliser le contexte de la demande d’authentification transmise dans le paramètre d’entrée requestContext pour écrire votre logique d’évaluation des risques. Le paramètre requestContext est de type RequestContext.

L’autre paramètre d’entrée passé est l’enregistreur d’événements qui est de type ThreatDetectionLogger. Le paramètre peut être utilisé pour écrire les messages d’erreur, d’audit et/ou de débogage dans les journaux AD FS.

La méthode retourne ThrottleStatus (0 si NotEvaluated, 1 pour Bloquer et 2 pour Autoriser) à AD FS qui bloque ou autorise la requête.

Dans notre exemple de plug-in, l’implémentation de la méthode EvaluateRequest analyse le paramètre clientIpAddress à partir de requestContext et le compare à toutes les adresses IP chargées à partir de la base de données AD FS. Si une correspondance est trouvée, la méthode retourne 2 pour Bloquer, sinon elle retourne 1 pour Autoriser. En fonction de la valeur retournée, AD FS bloque ou autorise la demande.

Remarque

L’exemple de plug-in décrit ci-dessus implémente uniquement l’interface IRequestReceivedThreatDetectionModule. Toutefois, le modèle d’évaluation des risques fournit deux interfaces supplémentaires : IPreAuthenticationThreatDetectionModule (pour implémenter la phase de pré-authentification de la logique d’évaluation des risques) et IPostAuthenticationThreatDetectionModule (pour implémenter la logique d’évaluation des risques pendant la phase post-authentification). Les détails sur les deux interfaces sont fournis ci-dessous.

IPreAuthenticationThreatDetectionModule, interface

Cette interface vous permet d’implémenter une logique d’évaluation des risques au point où l’utilisateur fournit les informations d’identification, mais avant qu’AD FS les évalue, c’est-à-dire l’étape Pré-authentification.

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

L’interface inclut la méthode EvaluatePreAuthentication qui vous permet d’utiliser les informations transmises dans RequestContext requestContext, SecurityContext securityContext, ProtocolContext protocolContext et IList<Claim> additionalClams pour écrire votre logique d’évaluation des risques pré-authentification.

Remarque

Pour obtenir une liste des propriétés transmises avec chaque type de contexte, consultez les définitions des classes RequestContext, SecurityContext et ProtocolContext.

L’autre paramètre d’entrée passé est l’enregistreur d’événements qui est de type ThreatDetectionLogger. Le paramètre peut être utilisé pour écrire les messages d’erreur, d’audit et/ou de débogage dans les journaux AD FS.

La méthode retourne ThrottleStatus (0 si NotEvaluated, 1 pour Bloquer et 2 pour Autoriser) à AD FS qui bloque ou autorise la requête.

IPostAuthenticationThreatDetectionModule, interface

Cette interface vous permet d’implémenter une logique d’évaluation des risques une fois que l’utilisateur a fourni des informations d’identification et qu’AD FS a effectué l’authentification, c’est-à-dire après l’étape Post-authentification.

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

L’interface inclut la méthode EvaluatePostAuthentication qui vous permet d’utiliser les informations transmises dans RequestContext requestContext, SecurityContext securityContext, ProtocolContext protocolContext et IList<Claim> additionalClams pour écrire votre logique d’évaluation des risques après l’authentification.

Notes

Pour obtenir la liste complète des propriétés transmises avec chaque type de contexte, reportez-vous aux définitions des classes RequestContext, SecurityContext et ProtocolContext.

L’autre paramètre d’entrée passé est l’enregistreur d’événements qui est de type ThreatDetectionLogger. Le paramètre peut être utilisé pour écrire les messages d’erreur, d’audit et/ou de débogage dans les journaux AD FS.

La méthode retourne le score de risque qui peut être utilisé dans les règles de revendication et de stratégie AD FS.

Notes

Pour que le plug-in fonctionne, la classe principale (dans ce cas UserRiskAnalyzer) doit dériver la classe abstraite ThreatDetectionModule et implémenter au moins une des trois interfaces décrites ci-dessus. Une fois la dll inscrite, AD FS vérifie quelles interfaces sont implémentées et les appelle à l’étape appropriée dans le pipeline.

FAQ

Pourquoi créer ces plug-ins ?
R : Ces plug-ins vous permettent non seulement de sécuriser votre environnement contre les attaques par pulvérisation de mot de passe, mais vous offrent également la flexibilité nécessaire pour créer votre propre logique d’évaluation des risques en fonction de vos besoins.

Où les journaux sont-ils capturés ?
R : Vous pouvez écrire les journaux d’erreurs dans le journal des événements « AD FS/Administration » à l’aide de la méthode WriteAdminLogErrorMessage, les journaux d’audit dans le journal de sécurité « Audit AD FS » à l’aide de la méthode WriteAuditMessage et les journaux de débogage dans le journal de débogage « Suivi AD FS » à l’aide de la méthode WriteDebugMessage.

L’ajout de ces plug-ins peut-il augmenter la latence du processus d’authentification AD FS ?
R : L’impact sur la latence est déterminé par le temps nécessaire à l’exécution de la logique d’évaluation des risques que vous implémentez. Nous vous recommandons d’évaluer l’impact sur la latence avant de déployer le plug-in en environnement de production.

Pourquoi AD FS ne peut-il pas suggérer la liste des adresses IP, utilisateurs, etc. à risque ?
R : Bien que cette fonctionnalité ne soit pas disponible actuellement, nous travaillons à la création de renseignements pour suggérer des adresses IP, utilisateurs, etc. à risque dans le modèle d’évaluation des risques enfichables. Nous partagerons bientôt les dates de lancement.

Quels autres exemples de plug-ins sont disponibles ?
R : Les exemples de plug-ins suivants sont disponibles :

Nom Description
Plug-in d’utilisateur à risque Échantillon de module qui bloque l'authentification ou applique l'authentification multifacteur en fonction du niveau de risque utilisateur déterminé par Protection des Microsoft Entra ID.