Panoramica delle estensioni di autenticazione personalizzate

Questo articolo offre una panoramica tecnica generale delle estensioni di autenticazione personalizzate per Microsoft Entra ID. Le estensioni di autenticazione personalizzate consentono di personalizzare l'esperienza di autenticazione di Microsoft Entra attraverso l'integrazione con sistemi esterni.

Il diagramma seguente illustra il flusso di accesso integrato con un'estensione di autenticazione personalizzata.

1. Un utente tenta di accedere a un'app e viene reindirizzato alla pagina di accesso di Microsoft Entra.
2. Una volta completato un determinato passaggio nell'autenticazione, viene attivato un listener di eventi.
3. L'estensione di autenticazione personalizzata invia una richiesta HTTP all'endpoint dell'API REST. La richiesta contiene informazioni sull'evento, il profilo utente, i dati della sessione e altre informazioni di contesto.
4. L'API REST esegue un flusso di lavoro personalizzato.
5. L'API REST restituisce una risposta HTTP all'ID Microsoft Entra.
6. L'estensione di autenticazione personalizzata Microsoft Entra elabora la risposta e personalizza l'autenticazione in base al tipo di evento e al payload della risposta HTTP.
7. Un token viene restituito all'app.

Endpoint API REST per l'estensione personalizzata dell'autenticazione

Quando viene generato un evento, Microsoft Entra ID chiama un endpoint dell'API REST di cui sei proprietario. La richiesta all'API REST contiene informazioni sull'evento, il profilo utente, i dati della richiesta di autenticazione e altre informazioni di contesto.

È possibile usare qualsiasi linguaggio di programmazione, framework e ambiente di hosting per creare e ospitare l'API REST delle estensioni di autenticazione personalizzate. Per un modo rapido per iniziare, usare una funzione di Azure C#. Funzioni di Azure consente di eseguire il codice in un ambiente serverless senza dover prima creare una macchina virtuale (VM) o pubblicare un'applicazione Web.

L'API REST deve gestire:

• Convalida dei token per la protezione delle chiamate API REST.
• Logica di business
• Convalida in ingresso e in uscita degli schemi di richiesta e risposta HTTP.
• Controllo e registrazione.
• Controlli di disponibilità, prestazioni e sicurezza.

Per gli sviluppatori che eseguono l'API REST in Funzioni di Azure, è consigliabile usare la libreria NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents, che consente l'implementazione della convalida dei token usando le funzionalità di autenticazione predefinite di Microsoft Azure. Fornisce un modello di dati per diversi tipi di evento, avvia l'elaborazione di richieste e risposte in ingresso e in uscita, in modo da poter concentrarsi maggiormente sulla logica di business.

Proteggere l'API REST

Per garantire che le comunicazioni tra l'estensione di autenticazione personalizzata e l'API REST siano protette in modo appropriato, è necessario applicare più controlli di sicurezza.

1. Quando l'estensione di autenticazione personalizzata chiama l'API REST, invia un'intestazione HTTP Authorization con un token di connessione rilasciato da Microsoft Entra ID.
2. Il token di portatore contiene una rivendicazione appid o azp. Verificare che la rispettiva attestazione contenga il 99045fe1-7639-4a75-9d4a-577b6ca3810f valore. Questo valore garantisce che l'ID Microsoft Entra sia quello che chiama l'API REST.
   1. Per le applicazioni di V1, convalidare l'attestazione appid.
   2. Per le applicazioni V2, convalida l'attestazione azp.
3. L'attestazione dell'audience del token portatore aud contiene l'ID della registrazione dell'applicazione associata. L'endpoint dell'API REST deve verificare che il token di connessione venga emesso per quel gruppo di destinatari specifico.
4. L'attestazione dell'autorità emittente del token iss di connessione contiene l'URL dell'autorità di certificazione Microsoft Entra. A seconda della configurazione del tenant, l'URL dell'autorità di certificazione sarà uno dei seguenti:
   • Forza lavoro: https://login.microsoftonline.com/{tenantId}/v2.0.
   • Cliente: https://{domainName}.ciamlogin.com/{tenantId}/v2.0.

Tipi di evento di autenticazione personalizzati

All'interno di un flusso utente di iscrizione e accesso sono disponibili eventi di autenticazione predefiniti. È anche possibile aggiungere estensioni di autenticazione personalizzate in punti specifici all'interno del flusso di autenticazione. Un'estensione di autenticazione personalizzata è essenzialmente un listener di eventi che, quando attivato, effettua una chiamata HTTP a un endpoint DELL'API REST in cui si definisce un'azione del flusso di lavoro. Questa sezione elenca gli eventi di autenticazione personalizzati disponibili in Microsoft Entra ID.

Evento di avvio del rilascio di token

L'evento di avvio del rilascio del token OnTokenIssuanceStart viene attivato quando un token sta per essere rilasciato a un'applicazione. Si tratta di un tipo di evento configurato all'interno di un provider di attestazioni personalizzato. Il provider di attestazioni personalizzate è un'estensione di autenticazione personalizzata che chiama un'API REST per recuperare le attestazioni da sistemi esterni. Un provider di attestazioni personalizzato esegue il mapping delle attestazioni dai sistemi esterni nei token e può essere assegnato a una o più applicazioni nell'elenco.

Per informazioni dettagliate, vedere provider di attestazioni personalizzati.

Inizio raccolta attributi

Gli eventi di avvio della raccolta di attributi possono essere usati con estensioni di autenticazione personalizzate per aggiungere logica prima che gli attributi vengano raccolti da un utente. L’evento OnAttributeCollectionStart si verifica all'inizio del passaggio della raccolta di attributi, prima del rendering della pagina della raccolta di attributi. Consente di aggiungere azioni come la precompilazione dei valori e la visualizzazione di un messaggio di errore bloccante.

Raccolta attributi invio

Gli eventi di invio della raccolta di attributi possono essere usati con estensioni di autenticazione personalizzate per aggiungere logica dopo che gli attributi vengono raccolti da un utente. L'evento OnAttributeCollectionSubmit viene attivato dopo che l'utente immette e invia attributi, consentendo di aggiungere azioni come la convalida delle voci o la modifica degli attributi.

Evento di invio di passcode monouso

L'evento OnOtpSend viene attivato quando si attiva un'email con un passcode monouso. Consente di chiamare un'API REST per usare il proprio provider di posta elettronica. Questo evento può essere usato per inviare messaggi di posta elettronica personalizzati agli utenti che eseguono l'iscrizione, reimpostano la password, accedono con posta elettronica e passcode monouso o l'autenticazione a più fattori tramite posta elettronica (MFA).

Quando viene attivato l'evento OnOtpSend, Microsoft Entra invia un passcode monouso all'API REST specificata di vostra proprietà. L'API REST usa quindi il provider di posta elettronica scelto, ad esempio il servizio di comunicazione di Azure o SendGrid, per inviare il passcode monouso con il modello di posta elettronica personalizzato, dall'indirizzo e dall'oggetto di posta elettronica, supportando al tempo stesso la localizzazione.

Contenuto correlato

• Maggiori informazioni sui fornitori personalizzati di attestazioni
• Creare estensioni di autenticazione personalizzate per l'avvio della raccolta di attributi e inviare eventi con un'applicazione OpenID Connect di esempio
• Configurare un provider di posta elettronica personalizzato per l'invio di eventi con passcode monouso