Condividi tramite

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 gruppo 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 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:

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

  1. Fase di ricezione della 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 del 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'IP si trova nell'elenco predefinito di 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 dei criteri e delle regole delle attestazioni 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 bisogna creare un plug-in di esempio che blocchi le richieste provenienti da determinati IP Extranet identificati come rischiosi, registrare il plug-in con AD FS e infine testare la funzionalità.

Nota

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

Creazione di un plug-in di esempio

Nota

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

Prerequisiti

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

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

Creare una dll di 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 con estensione .csv in qualsiasi posizione nel server AD FS (in questo caso, è stato creato il file authconfigdb.csv in C:\extensions) e aggiungere gli IP che si vogliono bloccare a questo file.

    Il plug-in di esempio bloccherà le richieste di autenticazione provenienti dagli 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 IP rischiosi in AD FS. Il processo di importazione verrà illustrato in dettaglio nella sezione Registrare la dll di plug-in con AD FS di seguito.

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

  4. Rimuovere Microsoft.IdentityServer.dll da Esplora soluzioni come illustrato di seguito:
    Screenshot that highlights the Remove menu option.

  5. Aggiungere un riferimento a Microsoft.IdentityServer.dll di AD FS come illustrato di seguito:

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

    Screenshot that highlights the Add Reference menu option.

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

    Nota

    In questo caso viene creato il plug-in sul server AD FS stesso. Se l'ambiente di sviluppo si trova in un server diverso, copiare Microsoft.IdentityServer.dll dalla cartella di installazione di AD FS nel server AD FS nella casella di sviluppo.

    Screenshot that shows the file you should copy.

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

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

  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 installarla nella Global Assembly Cache, o GAC, del server AD FS e la dll deve essere firmata per prima. Attenersi alla procedura riportata di seguito:

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

    Screenshot that highlights the Properties menu option.

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

    Screenshot that shows the Sign the assembly checkbox.

    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.

    Screenshot that shows Protect my key file with password checkbox.

    d. Salvare il progetto come illustrato di seguito:

    Screenshot that shows where to save your project.

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

    Screenshot that shows the Rebuild Solution menu option.

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

    Screenshot that shows the output from the rebuilt solution.

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, per poter essere eseguita in linea con il processo di autenticazione AD FS.

Registrare la dll di plug-in con AD FS

È necessario registrare la dll in AD FS usando il comando PowerShell Register-AdfsThreatDetectionModule 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 firmata la dll usando tale chiave. Per informazioni sul token di chiave pubblica per la dll, è possibile usare SN.exe come indicato di seguito:

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

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

    Screenshot that shows the Developer Command Prompt for Visual Studio.

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

    Screenshot that shows how to run the S N command.

    Il comando fornirà il token di chiave pubblica (in questo caso, 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 (ulteriori informazioni su Gacutil.exe disponibili qui) sul computer di sviluppo. Poiché si dispone di Visual Studio nello stesso server di AD FS, si usa Gacutil.exe come indicato di seguito:

    a. Nel prompt dei comandi per gli sviluppatori per Visual Studio e passare alla directory contenente Gacutil.exe (in questo caso, la directory è C:\Programmi (x86)\Microsoft SDK\Windows\v10.0A\bin\NETFX 4.7.2 Strumenti).

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

    Screenshot that shows how to run the Gacutil command.

    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 è tutto, ora la dll è 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 attuale 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"

Test del plug-in

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

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

  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 IP aggiunto in authconfig.csv.

    Per questa dimostrazione, viene usato lo strumento attestazioni X-Ray della Guida di AD FS per avviare una richiesta. Per usare lo strumento X-Ray, seguire le istruzioni

    Immettere l'istanza del server federativo e fare clic sul pulsante Test di autenticazione.

    Screenshot that shows the Test Authentication button.

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

    Screenshot that shows that authentication is blocked.

Ora che sappiamo come creare 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.

Procedura dettagliata per il codice plug-in

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

model

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

Classe astratta 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
VendorName Stringa Ottiene il nome del fornitore proprietario del plug-in
ModuleIdentifier Stringa Ottiene l'identificatore del plug-in

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

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, di controllo e/o di debug nei log di AD FS.

Il metodo restituisce ThrottleStatus (0 se NotEvaluated, 1 per Blocca e 2 per Consenti) 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 IP caricati dal database AD FS. Se viene trovata una corrispondenza, il metodo restituisce 2 per Blocca, altrimenti restituisce 1 per Consenti. 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 di 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 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, di controllo e/o di debug nei log di AD FS.

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

Interfaccia 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 di 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, di controllo e/o di debug nei log di AD FS.

Il metodo restituisce il punteggio di rischio che può essere usato nei criteri e nelle regole delle attestazioni 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?
R: questi plug-in non solo offrono funzionalità aggiuntive per proteggere l'ambiente da attacchi come attacchi password spraying, ma offrono anche la flessibilità necessaria per creare una logica di valutazione dei rischi personalizzata in base alle esigenze.

Dove vengono acquisiti i log?
R: è 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 "Tracciamento AD FS" usando il metodo WriteDebugMessage.

L'aggiunta di questi plug-in può aumentare la latenza del processo di autenticazione di AD FS?
R: l'impatto sulla latenza sarà 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 IP rischiosi, utenti rischiosi e così via?
R: anche se non è attualmente disponibile, stiamo lavorando alla creazione dell'intelligenza per suggerire IP rischiosi, utenti rischiosi e così via nel modello di valutazione dei rischi collegabile. Le date di avvio verranno condivise a breve.

Quali altri plug-in di esempio sono disponibili?
R: 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 dell'utente determinato da Microsoft Entra ID Protection.