Skapa plugin-program med AD FS 2019 Riskbedömningsmodell

Nu kan du skapa dina egna plugin-program för att blockera eller tilldela en riskpoäng till autentiseringsbegäranden under olika faser – begäran mottagen, förautentisering och efter autentisering. Detta kan åstadkommas med hjälp av den nya riskbedömningsmodellen som introducerades med AD FS 2019.

Vad är riskbedömningsmodellen?

Riskbedömningsmodellen är en uppsättning gränssnitt och klasser som gör det möjligt för utvecklare att läsa autentiseringsbegärandehuvuden och implementera sin egen logik för riskbedömning. Den implementerade koden (plugin-programmet) körs sedan i linje med AD FS-autentiseringsprocessen. Om du till exempel använder de gränssnitt och klasser som ingår i modellen kan du implementera kod för att antingen blockera eller tillåta autentiseringsbegäran baserat på klientens IP-adress som ingår i begärandehuvudet. AD FS kör koden för varje autentiseringsbegäran och vidtar lämpliga åtgärder enligt den implementerade logiken.

Modellen gör det möjligt att ansluta kod i någon av tre steg i AD FS-autentiseringspipelinen enligt nedan:

1. Begäran mottagen fas – Gör det möjligt att skapa plugin-program för att tillåta eller blockera begäran när AD FS tar emot autentiseringsbegäran, dvs. innan användaren anger autentiseringsuppgifter. Du kan använda begärandekontexten (till exempel klient-IP, Http-metod, proxyserverns DNS osv.) som är tillgänglig i det här skedet för att utföra riskbedömningen. Du kan till exempel skapa ett plugin-program för att läsa IP-adressen från begärandekontexten och blockera autentiseringsbegäran om IP-adressen finns i den fördefinierade listan över riskfyllda IP-adresser.

2. Förautentiseringssteg – Gör det möjligt att skapa plugin-program för att tillåta eller blockera begäran vid den punkt där användaren tillhandahåller autentiseringsuppgifterna men innan AD FS utvärderar dem. I det här skedet har du förutom begärandekontexten även information om säkerhetskontexten (till exempel användartoken, användaridentifierare osv.) och protokollkontexten (till exempel autentiseringsprotokoll, clientID, resourceID osv.) som ska användas i din riskbedömningslogik. Du kan till exempel skapa ett plugin-program för att förhindra lösenordssprayattacker genom att läsa användarlösenordet från användartoken och blockera autentiseringsbegäran om lösenordet finns i den fördefinierade listan över riskfyllda lösenord.

3. Efter autentisering – Gör det möjligt att skapa plugin-program för att bedöma risker när användaren har angett autentiseringsuppgifter och AD FS har utfört autentisering. I det här skedet, förutom kontexten för begäran, säkerhetskontexten och protokollkontexten, har du också information om autentiseringsresultatet (lyckades eller misslyckades). Plugin-programmet kan utvärdera riskpoängen baserat på tillgänglig information och skicka riskpoängen till anspråks- och policyregler för ytterligare utvärdering.

För att bättre förstå hur du skapar ett plugin-program för riskbedömning och kör det i enlighet med AD FS-processen ska vi skapa ett exempel på plugin-program som blockerar begäranden som kommer från vissa extranät-IP-adresser som identifierats som riskfyllda, registrera plugin-programmet med AD FS och slutligen testa funktionerna.

Skapa ett exempel på plugin-program

Pre-requisites

Följande är listan över förutsättningar som krävs för att skapa det här exempel-plugin-programmet:

• AD FS 2019 installerat och konfigurerat
• .NET Framework 4.7 och senare
• Visual Studio

Skapa plugin-dll

Följande procedur beskriver hur du skapar ett exempel på en plugin-dll:

1. Ladda ned exempel-plugin-programmet, använd Git Bash och skriv följande:

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

2. Skapa en .csv fil på valfri plats på AD FS-servern (i mitt fall skapade jag authconfigdb.csv-filen i C:\extensions) och lägg till de IP-adresser som du vill blockera i den här filen.

Exempel-plugin-programmet blockerar alla autentiseringsbegäranden som kommer från de extranät-IP-adresser som anges i den här filen.

3. Öppna projektet ThreatDetectionModule.sln med Visual Studio.

4. Microsoft.IdentityServer.dll Ta bort från Lösningsutforskaren enligt nedan:
   

5. Lägg till en referens till din Microsoft.IdentityServer.dll i AD FS enligt följande:

a. Högerklicka på Referenser i Solutions Explorer och välj Lägg till referens....

b. I fönstret Referenshanteraren väljer du Bläddra. I dialogrutan Välj de filer som ska refereras till... väljer du Microsoft.IdentityServer.dll från installationsmappen för AD FS (i mitt fall C:\Windows\ADFS) och klickar på Lägg till.

c. Klicka på OK i fönstret Referenshanteraren när du har kontrollerat att kryssrutan Microsoft.IdentityServer.dll är markerad.

6. Alla klasser och referenser finns nu på plats för att bygga. Men eftersom utdata från det här projektet är en dll måste det installeras i den Globala samlingscache, eller GAC, för AD FS-servern och dll-filen måste signeras först. Detta kan göras på följande sätt:

a. Högerklicka på namnet på projektet ThreatDetectionModule. Klicka på Egenskaper på menyn.

b. På sidan Egenskaper klickar du på Signering till vänster och markerar sedan kryssrutan Sign the assembly (Signera sammansättningen). På rullgardinsmenyn Välj en stark namnnyckel:, välj <Ny...>.

c. I dialogrutan Skapa stark namnnyckel skriver du ett namn (du kan välja valfritt namn) för nyckeln, avmarkerar kryssrutan Skydda min nyckelfil med lösenord. Klicka sedan på OK.

d. Spara projektet enligt nedan:

7. Skapa projektet genom att klicka på Skapa och sedan återskapa lösningen enligt nedan:
   

Kontrollera utdatafönstret längst ned på skärmen för att se om det har uppstått några fel.

Plugin-programmet (dll) är nu redo att användas och finns i mappen \bin\Debug i projektmappen (i mitt fall är det C:\extensions\ThreatDetectionModule\bin\Debug\ThreatDetectionModule.dll).

Nästa steg är att registrera den här dll-filen med AD FS, så att den körs i linje med AD FS-autentiseringsprocessen.

Registrera plugin-dll-filen med AD FS

Vi måste registrera dll-filen i AD FS med hjälp Register-AdfsThreatDetectionModule av PowerShell-kommandot på AD FS-servern. Men innan vi registrerar oss måste vi hämta token för offentlig nyckel. Den här offentliga nyckeltoken skapades när vi skapade nyckeln och signerade dll-filen med den nyckeln. Om du vill veta vad den offentliga nyckeltoken för dll:en är kan du använda SN.exe på följande sätt:

1. Kopiera dll-filen från mappen \bin\Debug till en annan plats (i mitt fall kopiera den till C:\extensions).

2. Starta kommandotolken för utvecklare för Visual Studio och gå till katalogen som innehåller sn.exe (i mitt fall är katalogen C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.7.2 Tools).

3. Kör SN-kommandot med parametern -T och filens plats (i mitt fall SN -T "C:\extensions\ThreatDetectionModule.dll").

Kommandot ger dig den offentliga nyckeltoken (för mig är den offentliga nyckeltoken 714697626ef96b35)

4. Lägg till dll-filen i AD FS-serverns Global Assembly Cache (GAC). Vi rekommenderar att du skapar ett korrekt installationsprogram för projektet och använder installationsprogrammet för att lägga till filen i GAC. En annan lösning är att använda Gacutil.exe (mer information om Gacutil.exe finns här) på utvecklingsdatorn. Eftersom jag har min Visual Studio på samma server som AD FS använder jag Gacutil.exe på följande sätt:

a. I Kommandotolken för utvecklare för Visual Studio och gå till katalogen som innehåller Gacutil.exe (i mitt fall är katalogen C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.7.2 Tools).

b. Kör Gacutil-kommandot (i mitt fall Gacutil /IF C:\extensions\ThreatDetectionModule.dll):

5. Öppna Windows PowerShell och kör följande kommando för att registrera dll:en:

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

I mitt fall är kommandot:

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

6. Starta om AD FS-tjänsten när dll-filen har registrerats.

Dll-filen är nu registrerad hos AD FS och klar för användning!

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

UnRegister-AdfsThreatDetectionModule -Name "IPBlockPlugin"

Testa plugin-programmet

1. Öppna denauthconfig.csv fil som vi skapade tidigare (i mitt fall på plats C:\extensions) och lägg till de extranät-IP-adresser som du vill blockera. Varje IP-adress ska finnas på en separat rad och det ska inte finnas några blanksteg i slutet.
   

2. Spara och stäng filen.

3. Importera den uppdaterade filen i AD FS genom att köra följande PowerShell-kommando:

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

I mitt fall är kommandot:

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

4. Initiera autentiseringsbegäran från servern med samma IP-adress som du lade till i authconfig.csv.

Ange federationsserverinstansen och tryck på knappen Testa autentisering .

5. Autentiseringen blockeras enligt nedan.
   

Nu när vi vet hur du skapar och registrerar plugin-programmet ska vi gå igenom plugin-koden för att förstå implementeringen med hjälp av de nya gränssnitt och klasser som introduceras med modellen.

Genomgång av plugin-kod

Öppna projektet ThreatDetectionModule.sln med Visual Studio och öppna sedan huvudfilen UserRiskAnalyzer.cs från Solutions Explorer till höger på skärmen

Filen innehåller huvudklassen UserRiskAnalyzer som implementerar den abstrakta klassen ThreatDetectionModule och gränssnitts-IRequestReceivedThreatDetectionModule för att läsa IP-adressen från begärandekontexten, jämföra den erhållna IP-adressen med IP-adresser som lästs in från AD FS DB och blockera begäran om det finns en IP-matchning. Nu går vi vidare med de här typerna i detalj

Abstrakt klass för ThreatDetectionModule

Den här abstrakta klassen läser in plugin-programmet i AD FS-pipelinen, vilket gör det möjligt att köra plugin-koden i linje med AD FS-processen.

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);
}

Klassen innehåller följande metoder och egenskaper:

I vårt exempel-plugin-program använder vi Metoderna OnAuthenticationPipelineLoad och OnConfigurationUpdate för att läsa de fördefinierade IP-adresserna från AD FS DB. OnAuthenticationPipelineLoad anropas när plugin-programmet registreras med AD FS medan OnConfigurationUpdate anropas när .csv importeras med hjälp av cmdleten Import-AdfsThreatDetectionModuleConfiguration .

IRequestReceivedThreatDetectionModule Interface

Med det här gränssnittet kan du implementera riskbedömning vid den tidpunkt då AD FS tar emot autentiseringsbegäran, men innan användaren anger autentiseringsuppgifter, dvs. i fasen Mottagen begäran i autentiseringsprocessen.

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

Gränssnittet innehåller metoden EvaluateRequest som gör att du kan använda kontexten för den autentiseringsbegäran som skickades i parametern requestContext-indata för att skriva din riskbedömningslogik. Parametern requestContext är av typen RequestContext.

Den andra indataparametern som skickas är logger som är typen ThreatDetectionLogger. Parametern kan användas för att skriva fel-, gransknings- och/eller felsökningsmeddelanden till AD FS-loggar.

Metoden returnerar ThrottleStatus (0 om NotEvaluated, 1 till Blockera och 2 till Tillåt) till AD FS som sedan antingen blockerar eller tillåter begäran.

I vårt exempel-plugin-program parsar Implementeringen av EvaluateRequest-metodenclientIpAddress från parametern requestContext och jämför den med alla IP-adresser som lästs in från AD FS DB. Om en matchning hittas returnerar metoden 2 för Block, annars returneras 1 för Tillåt. Baserat på det returnerade värdet blockerar eller tillåter AD FS antingen begäran.

IPreAuthenticationThreatDetectionModule Interface

Med det här gränssnittet kan du implementera riskbedömningslogik vid den tidpunkt då användaren tillhandahåller autentiseringsuppgifterna, men innan AD FS utvärderar dem, dvs. förautentiseringssteget.

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

Gränssnittet innehåller metoden EvaluatePreAuthentication som gör att du kan använda informationen som skickas i requestContext requestContext, SecurityContext securityContext, ProtocolContext protocolContext och IList<Claim> additionalClams-indataparametrar för att skriva logiken för riskbedömning före autentisering.

Den andra indataparametern som skickas är logger som är typen ThreatDetectionLogger. Parametern kan användas för att skriva fel-, gransknings- och/eller felsökningsmeddelanden till AD FS-loggar.

Metoden returnerar ThrottleStatus (0 om NotEvaluated, 1 till Blockera och 2 till Tillåt) till AD FS som sedan antingen blockerar eller tillåter begäran.

IPostAuthenticationThreatDetectionModule Interface

Med det här gränssnittet kan du implementera riskbedömningslogik när användaren har angett autentiseringsuppgifter och AD FS har utfört autentisering, dvs. fas efter autentisering.

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

Gränssnittet innehåller metoden EvaluatePostAuthentication som gör att du kan använda informationen som skickas i requestContext requestContext, SecurityContext securityContext, ProtocolContext protocolContext och IList<Claim> additionalClams-indataparametrar för att skriva logiken för riskbedömning efter autentisering.

Den andra indataparametern som skickas är logger som är typen ThreatDetectionLogger. Parametern kan användas för att skriva fel-, gransknings- och/eller felsökningsmeddelanden till AD FS-loggar.

Metoden returnerar riskpoängen som kan användas i AD FS-principen och anspråksregler.

FAQs

Varför ska jag skapa dessa plugin-program?
S: Dessa plugin-program ger dig inte bara ytterligare funktioner för att skydda din miljö från attacker som lösenordssprayattacker, utan ger dig också flexibiliteten att skapa din egen logik för riskbedömning baserat på dina krav.

Var registreras loggarna?
S: Du kan skriva felloggar till händelseloggen "AD FS/Admin" med metoden WriteAdminLogErrorMessage, granska loggar till säkerhetsloggen "AD FS-granskning" med hjälp av metoden WriteAuditMessage och felsöka loggar till felsökningsloggen "AD FS-spårning" med hjälp av metoden WriteDebugMessage.

Kan tillägg av dessa plugin-program öka svarstiden för AD FS-autentiseringsprocessen?
S: Svarstidspåverkan bestäms av den tid det tar att köra den riskbedömningslogik som du implementerar. Vi rekommenderar att du utvärderar svarstidspåverkan innan du distribuerar plugin-programmet i produktionsmiljön.

Varför kan inte AD FS föreslå listan över riskfyllda IP-adresser, användare osv.?
S: Även om det för närvarande inte är tillgängligt arbetar vi med att skapa information för att föreslå riskfyllda IP-adresser, användare osv. i modellen för pluggbar riskbedömning. Vi kommer snart att dela startdatumen.

Vilka andra exempel-plugin-program är tillgängliga?
S: Följande exempel på plugin-program är tillgängliga: