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

Vous pouvez maintenant créer vos propres plug-ins pour bloquer ou affecter un score de risque aux demandes d’authentification pendant différentes étapes : demande reçue, pré-authentification et post-authentification. Pour ce faire, vous pouvez utiliser 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 en ligne avec le processus d’authentification AD FS. Par exemple, à l’aide des interfaces et 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 requête. AD FS exécute le code de chaque demande d’authentification et prend les mesures appropriées en fonction de la logique implémentée.

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

1. Étape reçue de la demande : permet de créer des plug-ins pour autoriser ou bloquer la demande lorsque 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 demande et bloquer la demande d’authentification si l’adresse IP se trouve dans la liste prédéfinie d’adresses IP à risque.

2. Étape de pré-authentification : permet de créer des plug-ins pour autoriser ou bloquer la requête au point où l’utilisateur fournit les informations d’identification, mais avant qu’AD FS ne les évalue. À ce stade, en plus du contexte de demande, vous disposez également d’informations sur le contexte de sécurité (par exemple : jeton utilisateur, identificateur 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 mots 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 se trouve dans la liste prédéfinie des mots de passe à risque.

3. Après l’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 d’authentification (réussite ou échec). Le plug-in peut évaluer le score de risque en fonction des informations disponibles et transmettre le score de risque aux règles de revendication et de stratégie pour une évaluation supplémentaire.

Pour mieux comprendre comment créer un plug-in d’évaluation des risques et l’exécuter conformément au processus AD FS, nous allons créer un exemple de plug-in qui bloque les demandes provenant de certaines adresses IP 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 plug-in utilisateur à risque, un exemple de plug-in qui tire parti du niveau de risque utilisateur déterminé par Microsoft Entra ID Protection pour bloquer l’authentification ou appliquer l’authentification multifacteur (MFA). Les étapes de construction du plug-in utilisateur à risque sont disponibles ici.

Création d’un exemple de plug-in

Remarque

Cette procédure pas à pas vous montre uniquement comment créer un exemple de plug-in. La solution que nous créons n’est pas une solution prête pour l’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 à 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 extranet répertoriées dans ce fichier.

Remarque

Si vous disposez d’une batterie de serveurs AD FS, vous pouvez créer le fichier sur n’importe quel ou tous les serveurs AD FS. Tous les fichiers peuvent être utilisés pour importer les adresses IP risquées dans AD FS. Nous allons aborder le processus d’importation en détail dans la section Inscription de la DLL du plug-in avec AD FS ci-dessous.

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

4. Supprimez l’Explorateur Microsoft.IdentityServer.dll de solutions, comme indiqué ci-dessous :
   

5. Ajoutez une référence au Microsoft.IdentityServer.dll de votre 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....

b. Dans la fenêtre Gestionnaire de références , sélectionnez Parcourir. Dans le dialogue Sélectionner les fichiers à référencer... dialogue, sélectionnez Microsoft.IdentityServer.dll dans votre dossier d’installation AD FS (dans mon cas C :\Windows\ADFS), puis cliquez sur 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 votre zone de développement.

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

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, elle doit être installée dans le Global Assembly Cache, ou GAC, du serveur AD FS et la dll doit être signée en premier. 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.

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

v. Dans le 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 mot de passe. Cliquez ensuite sur OK.

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

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

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

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

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 Register-AdfsThreatDetectionModule commande PowerShell 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 l' SN.exe comme suit :

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

2. Démarrez l’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).

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

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

4. Ajoutez la dll au Global Assembly Cache du serveur AD FS. Nous vous recommandons 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 mon visual Studio sur le même serveur que AD FS, j’utilise 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) :

Remarque

Si vous disposez d’une batterie de serveurs AD FS, les éléments ci-dessus doivent être exécutés sur chaque serveur AD FS de la batterie de serveurs.

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"

Remarque

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

6. Redémarrez le service AD FS après l’inscription de la dll.

C’est-à-dire que la dll est maintenant inscrite auprès d’AD FS et prête à être utilisée !

Remarque

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 module d'extension

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. Chaque adresse IP doit se trouver sur une ligne distincte et il ne doit y avoir aucun espace à la fin.
   

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 du serveur avec la même adresse IP que celle que vous avez ajoutée dans authconfig.csv.

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

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

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

Parcours détaillé du code de plugin

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

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 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 requête s’il existe une correspondance IP. Passons en détail à ces types

Classe abstraite ThreatDetectionModule

Cette classe abstraite charge le plug-in dans le pipeline AD FS, ce qui permet d’exécuter le code de plug-in en ligne avec le 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	Catégorie	Définition
OnAuthenticationPipelineLoad	Annulé	Appelé par AD FS lorsque le plug-in est chargé dans son pipeline
OnAuthenticationPipelineDécharger	Annulé	Appelé par AD FS lorsque le plug-in est déchargé à partir de son pipeline
OnConfigurationUpdate	Annulé	Appelé par AD FS lors de la mise à jour de configuration
Propriété	Type	Définition
Nom du fournisseur	Chaîne	Obtient le nom du fournisseur propriétaire du plug-in
ModuleIdentifier	Chaîne	Obtient l’identificateur du plug-in

Dans notre exemple de plug-in, nous utilisons des méthodes OnAuthenticationPipelineLoad et OnConfigurationUpdate pour lire les adresses IP prédéfinies 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 Import-AdfsThreatDetectionModuleConfiguration de commande.

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 entre les informations d’identification, c’est-à-dire à l’étape de 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 to Block et 2 to Allow) à 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 clientIpAddress à partir du paramètre requestContext et la 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 Block, sinon elle retourne 1 pour Autoriser. En fonction de la valeur retournée, AD FS bloque ou autorise la requête.

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 logique d’évaluation des risques pendant la phase de pré-authentification) et IPostAuthenticationThreatDetectionModule (pour implémenter la logique d’évaluation des risques pendant l’étape post-authentification). Les détails sur les deux interfaces sont fournis ci-dessous.

IPreAuthenticationThreatDetectionModule, interface

Cette interface vous permet d’implémenter la logique d’évaluation des risques au moment où l’utilisateur fournit les informations d’identification, mais avant qu’AD FS ne les évalue, c’est-à-dire lors de la phase de 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 les paramètres d'entrée IList<Claim> additionalClams pour écrire votre logique d'évaluation des risques de pré-authentification.

Remarque

Pour obtenir la liste des propriétés passées avec chaque type de contexte, visitez RequestContext, SecurityContext et les définitions de classes 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 to Block et 2 to Allow) à AD FS, qui bloque ou autorise la requête.

IPostAuthenticationThreatDetectionModule, interface

Cette interface vous permet d’implémenter la 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’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 les paramètres d'entrée RequestContext requestContext, SecurityContext securityContext, ProtocolContext protocolContext, et IList<Claim> additionalClaims pour écrire votre logique d’évaluation des risques post-authentification.

Remarque

Pour obtenir la liste complète des propriétés passées avec chaque type de contexte, reportez-vous aux définitions de 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.

Remarque

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. Une fois la dll inscrite, AD FS vérifie quelles interfaces sont implémentées et les appelle à l’étape appropriée du pipeline.

Questions fréquentes (FAQ)

Pourquoi dois-je créer ces plug-ins ?
Un: Ces plug-ins vous offrent non seulement une capacité supplémentaire à sécuriser votre environnement contre les attaques telles que les attaques par pulvérisation de mots de passe, mais vous donnent également la possibilité de 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 ?
Un: L’impact de la latence sera déterminé par le temps nécessaire pour exécuter la logique d’évaluation des risques que vous implémentez. Nous vous recommandons d’évaluer l’impact de la latence avant de déployer le plug-in dans l’environnement de production.

Pourquoi ad FS ne peut-il pas suggérer la liste des adresses IP risquées, des utilisateurs, etc. ?
Un: Bien qu’il ne soit actuellement pas disponible, nous travaillons à la création de l’intelligence pour suggérer des adresses IP risquées, des utilisateurs, etc. dans le modèle d’évaluation des risques enfichable. Nous partagerons bientôt les dates de lancement.

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

Nom	Descriptif
Plug-in d’utilisateur à risque	Exemple de plug-in qui bloque l’authentification ou applique l’authentification multifacteur en fonction du niveau de risque utilisateur déterminé par Microsoft Entra ID Protection.