Aggiungere un connettore API a un flusso utente

Articolo
07/02/2024

Si applica a: Cerchio verde con un segno di spunta bianco. Tenant della forza lavoro Cerchio bianco con un simbolo X grigio. Tenant esterni (altre informazioni)

Per usare un connettore API, creare prima il connettore API, quindi abilitarlo in un flusso utente.

Importante

A partire dal 12 luglio 2021, se i clienti di Microsoft Entra B2B configurano nuove integrazioni di Google da usare con l'iscrizione self-service per le applicazioni personalizzate o line-of-business, l'autenticazione con identità Google non funzionerà finché le autenticazioni non verranno spostate nelle visualizzazioni Web di sistema. Altre informazioni.
A partire dal 30 settembre 2021, il supporto di Google per l'accesso tramite visualizzazione Web integrato è deprecato. Se le app autenticano gli utenti con una visualizzazione Web incorporata e si usa la federazione di Google con Azure AD B2C o Microsoft Entra B2B per gli inviti agli utenti esterni o l'iscrizione self-service, gli utenti di Google Gmail non saranno in grado di eseguire l'autenticazione. Altre informazioni.

Creare un connettore API

Suggerimento

I passaggi descritti in questo articolo possono variare leggermente in base al portale di partenza.

Accedere all'interfaccia di amministrazione di Microsoft Entra almeno come Amministratore utenti.
Andare a Identità>Identità esterne>Informazioni generali.
Selezionare Tutti i connettori API, quindi selezionare Nuovo connettore API.
Specificare un nome visualizzato per la chiamata. Ad esempio, controllare lo stato di approvazione.
Specificare l'URL dell'endpoint per la chiamata API.
Scegliere il Tipo di autenticazione e configurare le informazioni di autenticazione per chiamare l'API. Informazioni su come proteggere il connettore API.
Seleziona Salva.

La richiesta inviata all'API

Un connettore API si materializza come richiesta HTTP POST, inviando attributi utente ('richieste') come coppie chiave-valore in un corpo JSON. Gli attributi vengono serializzati in modo analogo alle proprietà utente di Microsoft Graph.

Richiesta di esempio

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

Solo le proprietà utente e gli attributi personalizzati elencati nell'esperienza Identità>Identità esterne>Informazioni generali>Attributi utente personalizzati possono essere inviati nella richiesta.

Gli attributi personalizzati esistono nella directory in formato extension_<extensions-app-id>_AttributeName. L'API dovrebbe aspettarsi di ricevere richieste nello stesso formato serializzato. Per altre informazioni sugli attributi personalizzati, vedere definire attributi personalizzati per i flussi di iscrizione self-service.

Inoltre, le attestazioni in genere vengono inviate in tutte le richieste:

Impostazioni locali dell'interfaccia utente ('ui_locales'): impostazione locale dell'utente finale così come è configurata sul suo dispositivo. Questa operazione può essere usata dall'API per restituire risposte internazionalizzate.

Indirizzo e-mail ('email') o identità ('identities'): queste attestazioni possono essere usate dall'API per identificare l'utente finale che esegue l'autenticazione all'applicazione.

Importante

Se un'attestazione non ha un valore al momento della chiamata dell'endpoint API, l'attestazione non verrà inviata all'API. L'API deve essere progettata per controllare e gestire in modo esplicito il caso in cui un'attestazione non si trova nella richiesta.

Abilitare il connettore API in un flusso utente

Seguire questa procedura per aggiungere un connettore API a un flusso utente di iscrizione self-service.

Accedere all'interfaccia di amministrazione di Microsoft Entra almeno come Amministratore utenti.
Andare a Identità>Identità esterne>Informazioni generali.
Selezionare Flussi utente, quindi selezionare il flusso utente a cui si vuole aggiungere il connettore API.
Selezionare Connettori API, quindi selezionare gli endpoint API da richiamare nei passaggi seguenti nel flusso utente:
- Dopo la federazione con un provider di identità durante l'accesso
- Prima della creazione dell'utente
Seleziona Salva.

Un connettore API in questo passaggio del processo di accesso viene richiamato immediatamente dopo l'autenticazione dell'utente con un provider di identità (ad esempio Google, Facebook o Microsoft Entra ID). Questo passaggio precede la pagina di raccolta attributi, ovvero il modulo presentato all'utente per raccogliere gli attributi utente.

Richiesta di esempio inviata all'API in questo passaggio

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "lastName":"Smith",
 "ui_locales":"en-US"
}

Le attestazioni esatte inviate all'API dipendono dalle informazioni fornite dal provider di identità. Il contenuto 'email' viene sempre inviato.

Tipi di risposta previsti dall'API Web in questo passaggio

Quando l'API Web riceve una richiesta HTTP da Microsoft Entra ID durante un flusso utente, può restituire queste risposte:

Risposta di continuazione
Risposta di blocco

Risposta di continuazione

Una risposta di continuazione indica che il flusso utente deve continuare con il passaggio successivo: la pagina di raccolta di attributi.

In una risposta di continuazione, l'API può restituire richieste. Se un'attestazione viene restituita dall'API, l'attestazione esegue le operazioni seguenti:

Precompila il campo di input nella pagina di raccolta degli attributi.

Vedere un esempio di risposta di continuazione.

Risposta di blocco

Una risposta di blocco esce dal flusso utente. Può essere rilasciata intenzionalmente dall'API per arrestare la continuazione del flusso utente visualizzando una pagina di blocco all'utente. La pagina di blocco visualizza l'oggetto userMessage fornito dall'API.

Vedere un esempio di risposta di blocco.

Prima della creazione dell'utente

Un connettore API in questo passaggio del processo di iscrizione viene richiamato dopo la pagina di raccolta degli attributi, se ne è inclusa una. Questo passaggio viene sempre richiamato prima che venga creato un account utente in Microsoft Entra ID.

Richiesta di esempio inviata all'API in questo passaggio

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

Le richieste esatte inviate all'API dipendono dalle informazioni raccolte dall'utente o fornite dal provider di identità.

Tipi di risposta previsti dall'API Web in questo passaggio

Quando l'API Web riceve una richiesta HTTP da Microsoft Entra ID durante un flusso utente, può restituire queste risposte:

Risposta di continuazione
Risposta di blocco
Risposta di convalida

Risposta di continuazione

Una risposta di continuazione indica che il flusso utente deve continuare con il passaggio successivo: creare l'utente nella directory.

In una risposta di continuazione, l'API può restituire richieste. Se un'attestazione viene restituita dall'API, l'attestazione esegue le operazioni seguenti:

Sovrascrivere qualsiasi valore già assegnato alla'attestazione dalla pagina di raccolta degli attributi.

Vedere un esempio di risposta di continuazione.

Risposta di blocco

Vedere un esempio di risposta di blocco.

Risposta di errore di convalida

Quando l'API risponde con una risposta di errore di convalida, il flusso utente rimane nella pagina di raccolta degli attributi e viene visualizzato un userMessage all'utente. L'utente può quindi modificare e inviare nuovamente il modulo. Questo tipo di risposta può essere usato per la convalida dell'input.

Vedere un esempio di risposta di errore di convalida.

Risposte di esempio

Esempio di una risposta di continuazione

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "Continue",
    "postalCode": "12349", // return claim
    "extension_<extensions-app-id>_CustomAttribute": "value" // return claim
}

Parametro	Type	Obbligatorio	Descrizione
versione	Stringa	Sì	La versione dell'API.
action	Stringa	Sì	Il valore deve essere `Continue`.
<builtInUserAttribute>	<attribute-type>	No	I valori possono essere archiviati nella directory se sono selezionati come Attestazione da ricevere nella configurazione del connettore API e come Attributi utente per un flusso utente. I valori possono essere restituiti nel token se selezionato come Attestazione dell'applicazione.
<extension_{extensions-app-id}_CustomAttribute>	<attribute-type>	No	L'attestazione non deve contenere `_<extensions-app-id>_`, è facoltativo. I valori restituiti possono sovrascrivere i valori raccolti da un utente.

Esempio di una risposta di blocco

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "There was an error with your request. Please try again or contact support.",
}

Parametro	Type	Obbligatorio	Descrizione
versione	Stringa	Sì	La versione dell'API.
action	Stringa	Sì	Il valore deve essere `ShowBlockPage`
userMessage	Stringa	Sì	Messaggio da visualizzare all'utente.

Esperienza utente finale con una risposta di blocco

Immagine di esempio dell'aspetto dell'esperienza utente finale dopo che un'API restituisce una risposta di blocco.

Esempio di una risposta di errore di convalida

HTTP/1.1 400 Bad Request
Content-type: application/json

{
    "version": "1.0.0",
    "status": 400,
    "action": "ValidationError",
    "userMessage": "Please enter a valid Postal Code.",
}

Parametro	Type	Obbligatorio	Descrizione
versione	Stringa	Sì	La versione dell'API.
action	Stringa	Sì	Il valore deve essere `ValidationError`.
stato	Integer / Stringa	Sì	Deve essere un valore di `400` o `"400"` per una risposta ValidationError.
userMessage	Stringa	Sì	Messaggio da visualizzare all'utente.

Nota

Il codice di stato HTTP deve essere "400" oltre al valore "status" nel corpo della risposta.

Esperienza utente finale con una risposta di errore di convalida

Immagine di esempio dell'aspetto dell'esperienza utente finale dopo che un'API restituisce una risposta di errore di convalida.

Procedure consigliate e risoluzione dei problemi

Uso delle funzioni cloud serverless

Le funzioni serverless, come i trigger HTTP in Funzioni di Azure, consentono di creare endpoint API da usare con il connettore API. È possibile usare la funzione cloud serverless per, ad esempio, eseguire la logica di convalida e limitare le iscrizione a domini di posta elettronica specifici. La funzione cloud serverless può anche chiamare e richiamare altre API Web, archivi dati e altri servizi cloud per scenari complessi.

Procedure consigliate

Assicurarsi che:

L'API segue la richiesta API e i contratti di risposta, come descritto in precedenza.
L'URL dell'endpoint del connettore API punta all'endpoint API corretto.
L'API verifica in modo esplicito la presenza di valori null delle attestazioni ricevute da cui dipende.
L'API implementa un metodo di autenticazione descritto in Proteggere il connettore API.
L'API risponde il più rapidamente possibile per garantire un'esperienza utente fluida.
- Microsoft Entra ID attende un massimo di 20 secondi per ricevere una risposta. Se non viene ricevuta una risposta, esegue un altro tentativo (retry) con la chiamata dell'API.
- Se si usa una funzione serverless o un servizio Web scalabile, usare un piano di hosting che mantiene l'API "attiva" o "calda" nell'ambiente di produzione. Per Funzioni di Azure, è consigliabile usare almeno il piano Premium.
Garantire la disponibilità elevata dell'API.
Monitorare e ottimizzare le prestazioni downstream delle API, dei database o di altre dipendenze dell'API.
Gli endpoint devono essere conformi ai requisiti di sicurezza di crittografia e TLS di Microsoft Entra. Per altre informazioni, vedere Requisiti della suite di crittografia e TLS.

Usare la registrazione

In generale, è utile usare gli strumenti di registrazione abilitati dal servizio API Web, ad esempio Application Insights, per monitorare l'API per individuare codici di errore imprevisti, eccezioni e prestazioni scarse.

Monitorare i codici di stato HTTP che non sono HTTP 200 o 400.
Un codice di stato HTTP 401 o 403 indica, in genere, che si è verificato un problema con l'autenticazione. Ricontrollare il livello di autenticazione dell'API e la configurazione corrispondente nel connettore API.
Se necessario, usare livelli più avanzati di registrazione, ad esempio "traccia" o "debug".
Monitorare l'API per tempi di risposta lunghi.

Passaggi successivi

Informazioni su come aggiungere un flusso di lavoro di approvazione personalizzato all'iscrizione self-service
Attività iniziali con esempi di avvio rapido.

Condividi tramite

Aggiungere un connettore API a un flusso utente

Creare un connettore API

La richiesta inviata all'API

Abilitare il connettore API in un flusso utente

Richiesta di esempio inviata all'API in questo passaggio

Tipi di risposta previsti dall'API Web in questo passaggio

Risposta di continuazione

Risposta di blocco

Prima della creazione dell'utente

Richiesta di esempio inviata all'API in questo passaggio

Tipi di risposta previsti dall'API Web in questo passaggio

Risposta di continuazione

Risposta di blocco

Risposta di errore di convalida

Risposte di esempio

Esempio di una risposta di continuazione

Esempio di una risposta di blocco

Esempio di una risposta di errore di convalida

Procedure consigliate e risoluzione dei problemi

Uso delle funzioni cloud serverless

Procedure consigliate

Usare la registrazione

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Aggiungere un connettore API a un flusso utente

Creare un connettore API

La richiesta inviata all'API

Abilitare il connettore API in un flusso utente

Dopo la federazione con un provider di identità durante l'accesso

Richiesta di esempio inviata all'API in questo passaggio

Tipi di risposta previsti dall'API Web in questo passaggio

Risposta di continuazione

Risposta di blocco

Prima della creazione dell'utente

Richiesta di esempio inviata all'API in questo passaggio

Tipi di risposta previsti dall'API Web in questo passaggio

Risposta di continuazione

Risposta di blocco

Risposta di errore di convalida

Risposte di esempio

Esempio di una risposta di continuazione

Esempio di una risposta di blocco

Esempio di una risposta di errore di convalida

Procedure consigliate e risoluzione dei problemi

Uso delle funzioni cloud serverless

Procedure consigliate

Usare la registrazione

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive