Creare plug-in con il modello di valutazione dei rischi di AD FS 2019

È ora possibile creare plug-in personalizzati per bloccare o assegnare un punteggio di rischio alle richieste di autenticazione durante varie fasi: richiesta ricevuta, preautenticazione e post-autenticazione. A tale scopo, è possibile usare il nuovo modello di valutazione dei rischi introdotto con AD FS 2019.

Che cos'è il modello di valutazione dei rischi?

Il modello di valutazione dei rischi è un set di interfacce e classi che consentono agli sviluppatori di leggere le intestazioni delle richieste di autenticazione e implementare la propria logica di valutazione dei rischi. Il codice implementato (plug-in) viene quindi eseguito in linea con il processo di autenticazione ad AD FS. Ad esempio, usando le interfacce e le classi incluse nel modello, è possibile implementare il codice per bloccare o consentire la richiesta di autenticazione in base all'indirizzo IP client incluso nell'intestazione della richiesta. AD FS eseguirà il codice per ogni richiesta di autenticazione e eseguirà le azioni appropriate in base alla logica implementata.

Il modello consente il plug-in del codice in una delle tre fasi della pipeline di autenticazione di AD FS, come illustrato di seguito:

1. Fase di ricezione richiesta: consente di creare plug-in per consentire o bloccare la richiesta quando AD FS riceve la richiesta di autenticazione, ad esempio prima che l'utente immetta le credenziali. È possibile usare il contesto della richiesta (ad esempio, IP client, metodo Http, DNS del server proxy e così via) disponibile in questa fase per eseguire la valutazione dei rischi. Ad esempio, è possibile compilare un plug-in per leggere l'IP dal contesto della richiesta e bloccare la richiesta di autenticazione se l'INDIRIZZO IP si trova nell'elenco predefinito di indirizzi IP rischiosi.

2. Fase di preautenticazione : abilita la compilazione di plug-in per consentire o bloccare la richiesta nel punto in cui l'utente fornisce le credenziali, ma prima che AD FS li valuta. In questa fase, oltre al contesto della richiesta sono disponibili anche informazioni sul contesto di sicurezza (ad esempio, token utente, identificatore utente e così via) e contesto del protocollo (ad esempio, protocollo di autenticazione, clientID, resourceID e così via) da usare nella logica di valutazione dei rischi. Ad esempio, è possibile creare un plug-in per impedire attacchi password spraying leggendo la password utente dal token utente e bloccando la richiesta di autenticazione se la password si trova nell'elenco predefinito di password rischiose.

3. Post-autenticazione : consente di creare un plug-in per valutare il rischio dopo che l'utente ha fornito le credenziali e AD FS ha eseguito l'autenticazione. In questa fase, oltre al contesto della richiesta, al contesto di sicurezza e al contesto del protocollo, sono disponibili anche informazioni sul risultato dell'autenticazione (esito positivo o negativo). Il plug-in può valutare il punteggio di rischio in base alle informazioni disponibili e passare il punteggio di rischio alle regole delle richieste e delle polizze per un'ulteriore valutazione.

Per comprendere meglio come creare un plug-in di valutazione dei rischi ed eseguirlo in linea con il processo AD FS, creare un plug-in di esempio che blocchi le richieste provenienti da determinati INDIRIZZI IP extranet identificati come rischiosi, registrare il plug-in con AD FS e infine testare la funzionalità.

Nota

In alternativa, è possibile creare un plug-in utente rischioso, un plug-in di esempio che sfrutta il livello di rischio utente determinato da Microsoft Entra ID Protection per bloccare l'autenticazione o applicare l'autenticazione a più fattori (MFA). I passaggi per la compilazione del plug-in utente rischioso sono disponibili qui.

Creazione di un plug-in di esempio

Nota

Questa procedura dettagliata è solo per illustrare come creare un plug-in di esempio. La soluzione che si sta creando non è una soluzione pronta per le aziende.

Prerequisiti

Di seguito è riportato l'elenco dei prerequisiti necessari per compilare questo plug-in di esempio:

• AD FS 2019 installato e configurato
• .NET Framework 4.7 e versioni successive
• Visual Studio

Creare DLL del plug-in

La procedura seguente illustra come creare una DLL di plug-in di esempio:

1. Scaricare il plug-in di esempio, usare Git Bash e digitare quanto segue:

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

2. Creare un file.csv in qualsiasi posizione del server AD FS (nel mio caso, ho creato il file authconfigdb.csv in C:\extensions) e aggiungere gli INDIRIZZI IP da bloccare a questo file.

Il plug-in di esempio bloccherà le richieste di autenticazione provenienti dagli indirizzi IP Extranet elencati in questo file.

Nota

Se si dispone di una farm AD FS, è possibile creare il file in uno o tutti i server AD FS. È possibile usare uno qualsiasi dei file per importare gli INDIRIZZI IP rischiosi in AD FS. Il processo di importazione verrà illustrato in dettaglio nella sezione Registrare la DLL del plug-in con AD FS di seguito.

3. Aprire il progetto ThreatDetectionModule.sln usando Visual Studio.

4. Rimuovere il Microsoft.IdentityServer.dll Esplora Soluzioni come illustrato di seguito:
   

5. Aggiungi riferimento all'Microsoft.IdentityServer.dll del tuo AD FS come mostrato di seguito:

a) Fare clic con il pulsante destro del mouse su Riferimenti in Esplora soluzioni e selezionare Aggiungi riferimento.

b. Nella finestra Gestione riferimenti selezionare Sfoglia. Nella finestra di dialogo Seleziona i file a cui fare riferimento , selezionare Microsoft.IdentityServer.dll dalla cartella di installazione di AD FS (nel mio caso C:\Windows\ADFS) e fare clic su Aggiungi.

Nota

Nel mio caso, sto creando il plug-in nel server AD FS stesso. Se l'ambiente di sviluppo si trova in un server diverso, copiare il Microsoft.IdentityServer.dll dalla cartella di installazione di AD FS sul server AD FS all'ambiente di sviluppo.

c. Fare clic su OK nella finestra Gestione riferimenti dopo aver verificato che la Microsoft.IdentityServer.dll casella di controllo sia selezionata.

6. Tutte le classi e i riferimenti sono ora disponibili per eseguire una compilazione. Tuttavia, poiché l'output di questo progetto è una DLL, sarà necessario installarlo nella Global Assembly Cache, o GAC, del server AD FS e la dll deve essere firmata per prima. Questo può essere fatto come segue:

a) Fare clic con il pulsante destro del mouse sul nome del progetto ThreatDetectionModule. Scegliere Proprietà dal menu.

b. Nella pagina Proprietà, fai clic su Firma nel menu a sinistra, quindi seleziona la casella di controllo contrassegnata Firma l'assembly. Dal menu a discesa Scegliere un file di chiave con nome sicuro: selezionare <Nuovo.>

c. Nella finestra di dialogo Crea chiave con nome sicuro digitare un nome (è possibile scegliere qualsiasi nome) per la chiave, deselezionare la casella di controllo Proteggi il file di chiave con password. Fare quindi clic su OK.

d. Salvare il progetto come illustrato di seguito:

7. Compilare il progetto facendo clic su Compila e quindi ricompilando la soluzione come illustrato di seguito:
   

Controllare la finestra Output nella parte inferiore della schermata per verificare se si sono verificati errori.

Il plug-in (dll) è ora pronto per l'uso e si trova nella cartella \bin\Debug della cartella del progetto (in questo caso, è C:\extensions\ThreatDetectionModule\bin\Debug\ThreatDetectionModule.dll).

Il passaggio successivo consiste nel registrare questa DLL con AD FS, quindi viene eseguita in linea con il processo di autenticazione ad AD FS.

Registrare la dll del plug-in con AD FS

È necessario registrare la dll in AD FS usando il Register-AdfsThreatDetectionModule comando PowerShell nel server AD FS. Tuttavia, prima di eseguire la registrazione, è necessario ottenere il token di chiave pubblica. Questo token di chiave pubblica è stato creato quando è stata creata la chiave e firmato la dll usando tale chiave. Per informazioni sul token di chiave pubblica per la dll, è possibile usare il SN.exe come indicato di seguito:

1. Copiare il file DLL dalla cartella \bin\Debug in un altro percorso (nel mio caso copiarlo in C:\extensions).

2. Avviare il prompt dei comandi per gli sviluppatori per Visual Studio e passare alla directory contenente il sn.exe (in questo caso, la directory è C:\Programmi (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.7.2 Tools.

3. Eseguire il comando SN con il parametro -T e il percorso del file (nel mio caso SN -T "C:\extensions\ThreatDetectionModule.dll").

Il comando fornirà il token di chiave pubblica (per me, il token di chiave pubblica è 714697626ef96b35)

4. Aggiungere la dll alla Global Assembly Cache del server AD FS La procedura consigliata consiste nel creare un programma di installazione appropriato per il progetto e usare il programma di installazione per aggiungere il file alla GAC. Un'altra soluzione consiste nell'usare Gacutil.exe (altre informazioni su Gacutil.exe disponibili qui) nel computer di sviluppo. Poiché si dispone di Visual Studio nello stesso server di AD FS, si userà Gacutil.exe come indicato di seguito:

a) Aprire il Prompt dei Comandi degli Sviluppatori per Visual Studio, poi passare alla directory che contiene il Gacutil.exe (nel mio caso, la directory è C:\Programmi (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.7.2 Tools).

b. Eseguire il comando Gacutil (nel mio caso Gacutil /IF C:\extensions\ThreatDetectionModule.dll):

Nota

Se si dispone di una farm AD FS, è necessario eseguire il codice precedente in ogni server AD FS nella farm.

5. Aprire Windows PowerShell ed eseguire il comando seguente per registrare 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>"

In questo caso, il comando è:

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

Nota

È necessario registrare la dll una sola volta, anche se si dispone di una farm AD FS.

6. Riavviare il servizio AD FS dopo la registrazione della dll.

Questa è la dll ora registrata con AD FS e pronta per l'uso.

Nota

Se vengono apportate modifiche al plug-in e il progetto viene ricompilato, è necessario registrare nuovamente la DLL aggiornata. Prima di eseguire la registrazione, è necessario annullare la registrazione della DLL corrente usando il comando seguente:

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

In questo caso, il comando è:

UnRegister-AdfsThreatDetectionModule -Name "IPBlockPlugin"

Testare il plug-in

1. Aprire il fileauthconfig.csv creato in precedenza (nel mio caso nel percorso C:\extensions) e aggiungere gli INDIRIZZI IP Extranet da bloccare. Ogni INDIRIZZO IP deve trovarsi in una riga separata e non deve essere presente alcuno spazio alla fine.
   

2. Salva e chiudi il file.

3. Importare il file aggiornato in AD FS eseguendo il comando di PowerShell seguente:

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

In questo caso, il comando è:

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

4. Avviare la richiesta di autenticazione dal server con lo stesso INDIRIZZO IP aggiunto in authconfig.csv.

Inserire l'istanza del server federativo e cliccare sul pulsante Test Autenticazione.

5. L'autenticazione è bloccata come illustrato di seguito.
   

Ora che sappiamo come compilare e registrare il plug-in, esaminiamo il codice plug-in per comprendere l'implementazione usando le nuove interfacce e le nuove classi introdotte con il modello.

Guida passo passo per il codice plugin

Aprire il progetto ThreatDetectionModule.sln usando Visual Studio e quindi aprire il file principale UserRiskAnalyzer.cs da Esplora soluzioni a destra della schermata

Il file contiene la classe principale UserRiskAnalyzer che implementa la classe astratta ThreatDetectionModule e l'interfaccia IRequestReceivedThreatDetectionModule per leggere l'INDIRIZZO IP dal contesto della richiesta, confrontare l'IP ottenuto con gli INDIRIZZI IP caricati dal database AD FS e bloccare la richiesta se è presente una corrispondenza IP. Esaminiamo questi tipi in modo più dettagliato

Classe astratta di ThreatDetectionModule

Questa classe astratta carica il plug-in nella pipeline di AD FS, rendendo possibile eseguire il codice plug-in in linea con il processo 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 include i metodi e le proprietà seguenti:

Metodo	TIPO	Definizione
OnAuthenticationPipelineLoad	Nullo	Chiamato da AD FS quando il plug-in viene caricato nella pipeline
OnAuthenticationPipelineUnload	Nullo	Chiamato da AD FS quando il plug-in viene scaricato dalla pipeline
OnConfigurationUpdate	Nullo	Chiamato da AD FS nell'aggiornamento della configurazione
Proprietà	Tipo	Definizione
Nome fornitore	Stringa	Ottiene il nome del fornitore proprietario del plug-in
IdentificatoreDelModulo	Stringa	Ottiene l'identificatore del plug-in

Nel plug-in di esempio vengono usati i metodi OnAuthenticationPipelineLoad e OnConfigurationUpdate per leggere gli indirizzi IP predefiniti da AD FS DB. OnAuthenticationPipelineLoad viene chiamato quando il plug-in viene registrato con AD FS mentre OnConfigurationUpdate viene chiamato quando il .csv viene importato usando il Import-AdfsThreatDetectionModuleConfiguration cmdlet .

L'interfaccia IRequestReceivedThreatDetectionModule

Questa interfaccia consente di implementare la valutazione dei rischi nel punto in cui AD FS riceve la richiesta di autenticazione, ma prima che l'utente immetta le credenziali, ad esempio nella fase richiesta ricevuta del processo di autenticazione.

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

L'interfaccia include il metodo EvaluateRequest che consente di usare il contesto della richiesta di autenticazione passata nel parametro di input requestContext per scrivere la logica di valutazione dei rischi. Il parametro requestContext è di tipo RequestContext.

L'altro parametro di input passato è logger di tipo ThreatDetectionLogger. Il parametro può essere usato per scrivere i messaggi di errore, controllo e/o debug nei log di AD FS.

Il metodo restituisce ThrottleStatus (0 se NotEvaluated, 1 to Block e 2 to Allow) ad AD FS che quindi blocca o consente la richiesta.

Nel plug-in di esempio l'implementazione del metodo EvaluateRequest analizza il clientIpAddress dal parametro requestContext e lo confronta con tutti gli INDIRIZZI IP caricati dal database AD FS. Se viene trovata una corrispondenza, il metodo restituisce 2 per Block, altrimenti restituisce 1 per Allow. In base al valore restituito, AD FS blocca o consente la richiesta.

Nota

Il plug-in di esempio descritto in precedenza implementa solo l'interfaccia IRequestReceivedThreatDetectionModule. Tuttavia, il modello di valutazione dei rischi fornisce due interfacce aggiuntive:IPreAuthenticationThreatDetectionModule (per implementare la logica di valutazione dei rischi durante la fase di pre-autenticazione) e IPostAuthenticationThreatDetectionModule (per implementare la logica di valutazione dei rischi durante la fase post-autenticazione). Di seguito sono riportati i dettagli sulle due interfacce.

Interfaccia IPreAuthenticationThreatDetectionModule

Questa interfaccia consente di implementare la logica di valutazione dei rischi nel punto in cui l'utente fornisce le credenziali, ma prima che AD FS li valuta, ad esempio la fase di pre-autenticazione.

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

L'interfaccia include il metodo EvaluatePreAuthentication che consente di usare le informazioni passate nei parametri di input RequestContext requestContext, SecurityContext, ProtocolContext protocolContext e IList<Claim> additionalClams per scrivere la logica di valutazione dei rischi di preautenticazione.

Nota

Per l'elenco delle proprietà passate con ogni tipo di contesto, vedere RequestContext, SecurityContext e Definizioni di classe ProtocolContext.

L'altro parametro di input passato è logger di tipo ThreatDetectionLogger. Il parametro può essere usato per scrivere i messaggi di errore, controllo e/o debug nei log di AD FS.

Il metodo restituisce ThrottleStatus (0 se NotEvaluated, 1 to Block e 2 to Allow) ad AD FS che quindi blocca o consente la richiesta.

Interfaccia di IPostAuthenticationThreatDetectionModule

Questa interfaccia consente di implementare la logica di valutazione dei rischi dopo che l'utente ha fornito le credenziali e AD FS ha eseguito l'autenticazione, ad esempio dopo l'autenticazione.

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

L'interfaccia include il metodo EvaluatePostAuthentication che consente di usare le informazioni passate nei parametri di input RequestContext requestContext, SecurityContext, ProtocolContext protocolContext e IList<Claim> additionalClams per scrivere la logica di valutazione dei rischi post-autenticazione.

Nota

Per un elenco completo delle proprietà passate con ogni tipo di contesto, fare riferimento alle definizioni di classi RequestContext, SecurityContext e ProtocolContext.

L'altro parametro di input passato è logger di tipo ThreatDetectionLogger. Il parametro può essere usato per scrivere i messaggi di errore, controllo e/o debug nei log di AD FS.

Il metodo restituisce il punteggio di rischio che può essere usato nei criteri e nelle regole di attestazione di AD FS.

Nota

Per il funzionamento del plug-in, la classe principale (in questo caso UserRiskAnalyzer) deve derivare la classe astratta ThreatDetectionModule e deve implementare almeno una delle tre interfacce descritte in precedenza. Dopo aver registrato la dll, AD FS controlla quali interfacce vengono implementate e le chiama nella fase appropriata nella pipeline.

Domande frequenti

Perché è consigliabile creare questi plug-in?
Un: Questi plug-in non solo offrono funzionalità aggiuntive per proteggere l'ambiente da attacchi come gli attacchi password spray, ma offrono anche la flessibilità necessaria per creare una logica di valutazione dei rischi personalizzata in base ai requisiti.

Dove vengono acquisiti i log?
Un: È possibile scrivere log degli errori nel registro eventi "AD FS/Admin" usando il metodo WriteAdminLogErrorMessage, i log di controllo nel log di sicurezza "AD FS Auditing" usando il metodo WriteAuditMessage e i log di debug nel log di debug "Traccia AD FS" usando il metodo WriteDebugMessage.

L'aggiunta di questi plug-in può aumentare la latenza del processo di autenticazione di AD FS?
Un: L'impatto sulla latenza verrà determinato dal tempo impiegato per eseguire la logica di valutazione dei rischi implementata. È consigliabile valutare l'impatto sulla latenza prima di distribuire il plug-in nell'ambiente di produzione.

Perché AD FS non può suggerire l'elenco di indirizzi IP rischiosi, utenti e così via?
Un: Anche se non è attualmente disponibile, stiamo lavorando alla creazione dell'intelligence per suggerire indirizzi IP rischiosi, utenti e così via nel modello di valutazione dei rischi collegabile. Le date di lancio verranno condivise a breve.

Quali altri plug-in di esempio sono disponibili?
Un: Sono disponibili i plug-in di esempio seguenti:

Nome	Descrizione
Plug-in utente rischioso	Plug-in di esempio che blocca l'autenticazione o applica l'autenticazione a più fattori in base al livello di rischio utente determinato da Microsoft Entra ID Protection.