Panoramica dei criteri personalizzati di Azure AD B2C

I criteri personalizzati sono file di configurazione che definiscono il comportamento del tenant di Azure Active Directory B2C (Azure AD B2C). Mentre i flussi utente sono predefiniti nel portale di Azure AD B2C per le attività di identità più comuni, uno sviluppatore di identità può modificare i criteri personalizzati per completare molte attività diverse.

Un criterio personalizzato è completamente configurabile e basato su criteri. Un criterio personalizzato orchestra l'attendibilità tra le entità nei protocolli standard. Ad esempio, OpenID Connessione, OAuth, SAML e alcuni non standard, ad esempio scambi di attestazioni da sistema a sistema basati su API REST. Il framework crea esperienze con etichetta bianca e descrittive.

Un criterio personalizzato è rappresentato come uno o più file in formato XML che fanno riferimento l'uno all'altro in una catena gerarchica. Gli elementi XML definiscono i blocchi predefiniti, l'interazione con l'utente e altre parti e la logica di business.

Pacchetto Starter per i criteri personalizzati

Lo starter pack di criteri personalizzati di Azure AD B2C include diversi criteri predefiniti per iniziare rapidamente. Ogni pacchetto Starter contiene il numero minimo di profili tecnici e percorsi utente necessario per conseguire gli scenari descritti:

• LocalAccounts - Consente l'uso solo di account locali.
• SocialAccounts - Consente l'uso solo di account di social networking (o federati).
• SocialAndLocalAccounts - Consente sia l'uso di account locali che di account di social networking. La maggior parte degli esempi fa riferimento a questo criterio.
• SocialAndLocalAccountsWithMFA : abilita le opzioni di autenticazione social, locale e a più fattori.

Nel repository GitHub degli esempi di Azure AD B2C sono disponibili esempi per diversi percorsi utente e scenari CIAM personalizzati di Azure AD B2C avanzati. Ad esempio, miglioramenti dei criteri degli account locali, miglioramenti dei criteri degli account di social networking, miglioramenti dell'autenticazione a più fattori, miglioramenti dell'interfaccia utente, miglioramenti generici, migrazione delle app, migrazione degli utenti, accesso condizionale, test Web e CI/CD.

Informazioni sulle nozioni di base

Richieste di rimborso

Un'attestazione fornisce un'archiviazione temporanea dei dati durante l'esecuzione dei criteri di Azure AD B2C. Le attestazioni sono più simili a una variabile in un linguaggio di programmazione. Può archiviare informazioni sull'utente, ad esempio nome, cognome o qualsiasi altra attestazione ottenuta dall'utente o da altri sistemi (scambi di attestazioni). Lo schema di attestazioni è la posizione in cui si dichiarano le attestazioni.

Quando i criteri vengono eseguiti, Azure AD B2C invia e riceve le attestazioni da e verso parti interne ed esterne e quindi invia un subset di queste attestazioni all'applicazione relying party come parte del token. Le attestazioni vengono usate in questi modi:

• Un'attestazione viene salvata, letta o aggiornata rispetto all'oggetto utente della directory.
• Un'attestazione viene ricevuta da un provider di identità esterno.
• Le attestazioni vengono inviate o ricevute usando un servizio API REST personalizzato.
• I dati vengono raccolti come attestazioni dall'utente durante l'iscrizione o la modifica dei flussi del profilo.

Modifica delle attestazioni

Le trasformazioni delle attestazioni sono funzioni predefinite che possono essere usate per convertire una determinata attestazione in un'altra, valutare un'attestazione o impostare un valore attestazione. Ad esempio, l'aggiunta di un elemento a una raccolta di stringhe, la modifica del caso di una stringa o la valutazione di un'attestazione di data e ora. Una trasformazione delle attestazioni specifica un metodo di trasformazione, anch'esso predefinito.

Personalizzare e localizzare l'interfaccia utente

Per raccogliere informazioni dagli utenti presentando una pagina nel Web browser, usare il profilo tecnico autocertificato. È possibile modificare il profilo tecnico autocertifiato per aggiungere attestazioni e personalizzare l'input dell'utente.

Per personalizzare l'interfaccia utente per il profilo tecnico autocertivi, è necessario specificare un URL nell'elemento di definizione del contenuto con contenuto HTML personalizzato. Nel profilo tecnico autocertivi si fa riferimento a questo ID definizione del contenuto.

Per personalizzare stringhe specifiche della lingua, usare l'elemento di localizzazione . Una definizione di contenuto può contenere un riferimento di localizzazione che specifica un elenco di risorse localizzate da caricare. Azure AD B2C unisce elementi dell'interfaccia utente con il contenuto HTML caricato dall'URL e quindi mostra la pagina all'utente.

Panoramica dei criteri relying party

Un'applicazione relying party, che nel protocollo SAML è nota come provider di servizi, chiama i criteri della relying party per eseguire un percorso utente specifico. Il criterio relying party specifica il percorso utente da eseguire e l'elenco di attestazioni incluse nel token.

Tutte le applicazioni relying party che usano gli stessi criteri ricevono le stesse attestazioni di token e l'utente esegue lo stesso percorso utente.

Percorsi utente

I percorsi utente consentono di definire la logica di business con il percorso attraverso il quale l'utente segue per ottenere l'accesso all'applicazione. L'utente viene eseguito nel percorso utente per recuperare le attestazioni che devono essere presentate all'applicazione. Un percorso utente viene creato da una sequenza di passaggi di orchestrazione. Un utente deve raggiungere l'ultimo passaggio per acquisire un token.

Le istruzioni seguenti descrivono come aggiungere passaggi di orchestrazione ai criteri di starter pack di account di social networking e locale. Di seguito è riportato un esempio di chiamata API REST aggiunta.

Passaggi di orchestrazione

Il passaggio di orchestrazione fa riferimento a un metodo che implementa lo scopo o la funzionalità previsti. Questo metodo è denominato profilo tecnico. Quando il percorso utente richiede la diramazione per rappresentare meglio la logica di business, il passaggio di orchestrazione fa riferimento al percorso secondario. Un percorso secondario contiene un proprio set di passaggi di orchestrazione.

Un utente deve raggiungere l'ultimo passaggio di orchestrazione nel percorso utente per acquisire un token. Ma gli utenti potrebbero non dover eseguire tutti i passaggi di orchestrazione. I passaggi di orchestrazione possono essere eseguiti in modo condizionale in base alle precondizioni definite nel passaggio di orchestrazione.

Al termine di un passaggio di orchestrazione, Azure AD B2C archivia le attestazioni restituite nel contenitore delle attestazioni. Le attestazioni nel contenitore delle attestazioni possono essere utilizzate da qualsiasi ulteriore procedura di orchestrazione nel percorso utente.

Il diagramma seguente mostra come i passaggi di orchestrazione del percorso utente possono accedere al contenitore delle attestazioni.

Profilo tecnico

Un profilo tecnico fornisce un'interfaccia per comunicare con diversi tipi di parti. Un percorso utente combina la chiamata di profili tecnici tramite passaggi di orchestrazione per definire la logica di business.

Tutti i tipi di profili tecnici condividono lo stesso concetto. Si inviano attestazioni di input, si esegue la trasformazione delle attestazioni e si comunica con l'entità configurata. Al termine del processo, il profilo tecnico restituisce le attestazioni di output nel contenitore delle attestazioni. Per altre informazioni, vedere Panoramica dei profili tecnici.

Profilo tecnico di convalida

Quando un utente interagisce con l'interfaccia utente, può essere necessario convalidare i dati raccolti. Per interagire con l'utente, è necessario usare un profilo tecnico autocertificato.

Per convalidare l'input dell'utente, viene chiamato un profilo tecnico di convalida dal profilo tecnico autocertificato. Un profilo tecnico di convalida è un metodo per chiamare qualsiasi profilo tecnico non interattivo. In questo caso, il profilo tecnico può restituire attestazioni di output o un messaggio di errore. Il rendering del messaggio di errore viene eseguito all'utente sullo schermo, consentendo all'utente di riprovare.

Il diagramma seguente illustra come Azure AD B2C usa un profilo tecnico di convalida per convalidare le credenziali utente.

Modello di ereditarietà

Ogni starter pack include i file seguenti:

• un file di base che contiene la maggior parte delle definizioni. Per facilitare la risoluzione dei problemi e la manutenzione a lungo termine dei criteri, provare a ridurre al minimo il numero di modifiche apportate a questo file.
• File di localizzazione che contiene le stringhe di localizzazione. Questo file dei criteri è derivato dal file di base. Usare questo file per adattarsi a lingue diverse in base alle esigenze dei clienti.
• Un file di estensioni che contiene le modifiche di configurazione univoche per il tenant. Questo file di criteri è derivato dal file di localizzazione. Usare questo file per aggiungere nuove funzionalità o eseguire l'override delle funzionalità esistenti. Ad esempio, usare questo file per la federazione con nuovi provider di identità.
• Un file Relying Party (RP) è l'unico file incentrato sulle attività che viene chiamato direttamente dell'applicazione relying party, come applicazioni Web, mobili o desktop. Ogni attività univoca, ad esempio l'iscrizione, l'accesso o la modifica del profilo, richiede il proprio file di criteri relying party. Questo file di criteri è derivato dal file delle estensioni.

Il modello di ereditarietà è come segue:

• Il criterio figlio a qualsiasi livello può ereditare dal criterio padre ed estenderlo aggiungendo nuovi elementi.
• Per scenari più complessi, è possibile aggiungere altri livelli di ereditarietà (fino a 10 in totale).
• È possibile aggiungere altri criteri relying party. Ad esempio, eliminare l'account, modificare un numero di telefono, i criteri della relying party SAML e altro ancora.

Il diagramma seguente mostra la relazione tra i file di criteri e le applicazioni relying party.

Materiale sussidiario e procedure consigliate

Procedure consigliate

All'interno di un criterio personalizzato di Azure AD B2C, è possibile integrare la propria logica di business per creare le esperienze utente necessarie ed estendere le funzionalità del servizio. Sono disponibili una serie di procedure consigliate e raccomandazioni per iniziare.

• Creare la logica all'interno dei criteri di estensione o dei criteri della relying party. È possibile aggiungere nuovi elementi, che sostituiscono i criteri di base facendo riferimento allo stesso ID. Questo approccio consente di aumentare il numero di istanze del progetto semplificando l'aggiornamento dei criteri di base in un secondo momento se Microsoft rilascia nuovi pacchetti di avvio.
• All'interno dei criteri di base, è consigliabile evitare di apportare modifiche. Quando necessario, apportare commenti in cui vengono apportate le modifiche.
• Quando si esegue l'override di un elemento, ad esempio i metadati del profilo tecnico, evitare di copiare l'intero profilo tecnico dai criteri di base. Copiare invece solo la sezione richiesta dell'elemento . Vedere Disabilitare la verifica della posta elettronica per un esempio di come apportare la modifica.
• Per ridurre la duplicazione dei profili tecnici, in cui è condivisa la funzionalità di base, usare l'inclusione del profilo tecnico.
• Evitare di scrivere nella directory di Microsoft Entra durante l'accesso, che può causare problemi di limitazione.
• Se i criteri hanno dipendenze esterne, ad esempio le API REST, assicurarsi che siano a disponibilità elevata.
• Per un'esperienza utente migliore, assicurarsi che i modelli HTML personalizzati vengano distribuiti a livello globale usando la distribuzione di contenuti online. Azure rete per la distribuzione di contenuti (rete CDN) consente di ridurre i tempi di caricamento, risparmiare larghezza di banda e migliorare la velocità di risposta.
• Se si vuole apportare una modifica al percorso utente, copiare l'intero percorso utente dai criteri di base ai criteri di estensione. Specificare un ID percorso utente univoco per il percorso utente copiato. Quindi, nei criteri della relying party modificare l'elemento percorso utente predefinito in modo che punti al nuovo percorso utente.

Risoluzione dei problemi

Durante lo sviluppo con i criteri di Azure AD B2C, è possibile che si verifichino errori o eccezioni durante l'esecuzione del percorso utente. L'oggetto può essere analizzato usando Application Insights.

• Integrare Application Insights con Azure AD B2C per diagnosticare le eccezioni.
• L'estensione Azure AD B2C per Visual Studio Code consente di accedere e visualizzare i log in base al nome e all'ora dei criteri .
• L'errore più comune nell'impostazione dei criteri è la formattazione XML non corretta. Usare la convalida di XML Schema per identificare gli errori prima di caricare il file XML.

Integrazione continua

Usando una pipeline di integrazione e recapito continuo (CI/CD) configurata in Azure Pipelines, è possibile includere i criteri personalizzati di Azure AD B2C nell'automazione del controllo del codice e del recapito software. Quando si esegue la distribuzione in ambienti Azure AD B2C diversi, ad esempio sviluppo, test e produzione, è consigliabile rimuovere processi manuali ed eseguire test automatizzati usando Azure Pipelines.

Predisporre l'ambiente

Si inizia a usare i criteri personalizzati di Azure AD B2C:

1. Creare un tenant di Azure AD B2C
2. Registrare un'applicazione Web usando il portale di Azure in modo da poter testare i criteri.
3. Aggiungere le chiavi dei criteri necessarie e registrare le applicazioni Identity Experience Framework.
4. Ottenere il pacchetto di avvio dei criteri di Azure AD B2C e caricarlo nel tenant.
5. Dopo aver caricato il pacchetto starter, testare i criteri di iscrizione o di accesso.
6. È consigliabile scaricare e installare Visual Studio Code (VS Code). Visual Studio Code è un editor di codice sorgente leggero ma potente, che viene eseguito sul desktop ed è disponibile per Windows, macOS e Linux. Con VS Code è possibile esplorare e modificare rapidamente i file XML dei criteri personalizzati di Azure AD B2C installando l'estensione Azure AD B2C per VS Code

Passaggi successivi

Dopo aver configurato e testato i criteri di Azure AD B2C, è possibile iniziare a personalizzare i criteri. Vedere gli articoli seguenti per informazioni su come:

• Aggiungere attestazioni e personalizzare l'input dell'utente usando criteri personalizzati. Informazioni su come definire un'attestazione e aggiungere un'attestazione all'interfaccia utente personalizzando alcuni profili tecnici dello starter pack.
• Personalizzare l'interfaccia utente dell'applicazione usando un criterio personalizzato. Informazioni su come creare contenuti HTML personalizzati e personalizzare la definizione del contenuto.
• Localizzare l'interfaccia utente dell'applicazione usando un criterio personalizzato. Informazioni su come configurare l'elenco delle lingue supportate e fornire etichette specifiche della lingua aggiungendo l'elemento risorse localizzate.
• Durante lo sviluppo e il test dei criteri, è possibile disabilitare la verifica tramite posta elettronica. Informazioni su come sovrascrivere i metadati di un profilo tecnico.
• Configurare l'accesso con un account Google usando criteri personalizzati. Informazioni su come creare un nuovo provider di attestazioni con profilo tecnico OAuth2. Personalizzare quindi il percorso utente per includere l'opzione di accesso a Google.
• Per diagnosticare i problemi con i criteri personalizzati, è possibile raccogliere i log di Azure Active Directory B2C con Application Insights. Informazioni su come aggiungere nuovi profili tecnici e configurare i criteri della relying party.
• Per comprendere il modo in cui i criteri personalizzati vengono creati da zero, informazioni su come creare ed eseguire criteri personalizzati nella serie di procedure di Azure Active Directory B2C.