Aggiungere un connettore API a un flusso utente

Si applica a: Tenant esterni della forza lavoro (altre informazioni)

Per usare un connettore API, creare prima il connettore API e 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 per l'uso 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, Google deprecato il supporto per l'accesso alla visualizzazione Web incorporato. 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 degli 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 da cui si inizia.

1. Accedere all'interfaccia di amministrazione di Microsoft Entra almeno come Amministratore utenti.

2. Passare a Identity>External Identity Identities>Overview (Panoramica delle identità esterne).

3. Selezionare Tutti i connettori API e quindi Nuovo connettore API.

   

4. Specificare un nome visualizzato per la chiamata. Ad esempio, controllare lo stato dell'approvazione.

5. Specificare l'URL dell'endpoint per la chiamata API.

6. Scegliere il tipo di autenticazione e configurare le informazioni di autenticazione per chiamare l'API. Informazioni su come proteggere il Connessione or dell'API.

   

7. Seleziona Salva.

Richiesta inviata all'API

Un connettore API si materializza come richiesta HTTP POST , inviando attributi utente ('claims') 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"
}

Nella richiesta sono disponibili solo le proprietà utente e gli attributi personalizzati elencati nell'esperienza Identity>External Identity External Identity>Overview>Custom user attributes (Panoramica degli attributi utente personalizzati).

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

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

• Impostazioni locali dell'interfaccia utente ('ui_locales'): impostazioni locali dell'utente finale configurate nel dispositivo. Questa operazione può essere usata dall'API per restituire risposte internazionalizzate.

• Indirizzo di posta elettronica ('email') o identità ('identità'): 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.

1. Accedere all'interfaccia di amministrazione di Microsoft Entra almeno come Amministratore utenti.

2. Passare a Identity>External Identity Identities>Overview (Panoramica delle identità esterne).

3. Selezionare Flussi utente e quindi selezionare il flusso utente a cui si vuole aggiungere il connettore API.

4. Selezionare Connettori API e quindi selezionare gli endpoint API da richiamare nei passaggi seguenti nel flusso utente:

   • Dopo la federazione con un provider di identità durante l'iscrizione
   • Prima di creare l'utente

   

5. Seleziona Salva.

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

Un connettore API in questo passaggio del processo di iscrizione 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 della raccolta di 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à. '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 della raccolta di attributi.

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

• Precompila il campo di input nella pagina della raccolta di attributi.

Vedere un esempio di risposta di continuazione.

Risposta di blocco

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

Vedere un esempio di risposta di blocco.

Prima di creare l'utente

Un connettore API in questo passaggio del processo di iscrizione viene richiamato dopo la pagina della raccolta di 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 attestazioni 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 attestazioni. Se un'attestazione viene restituita dall'API, l'attestazione esegue le operazioni seguenti:

• Esegue l'override di qualsiasi valore già assegnato all'attestazione dalla pagina della raccolta di attributi.

Vedere un esempio di risposta di continuazione.

Risposta di blocco

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

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 della raccolta di attributi e userMessage viene visualizzato un oggetto 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 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ì	Versione dell'API.
action	Stringa	Sì	Il valore deve essere Continue.
<builtInUserAttribute>	<tipo di attributo>	No	I valori possono essere archiviati nella directory se sono selezionati come attestazione da ricevere nella configurazione del connettore API e attributi utente per un flusso utente. I valori possono essere restituiti nel token se selezionato come attestazione dell'applicazione.
<extension_{extensions-app-id}_CustomAttribute>	<tipo di attributo>	No	L'attestazione non deve contenere _<extensions-app-id>_, è facoltativa. I valori restituiti possono sovrascrivere i valori raccolti da un utente.

Esempio di 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ì	Versione dell'API.
action	Stringa	Sì	Il valore deve essere ShowBlockPage
userMessage	Stringa	Sì	Messaggio da visualizzare all'utente.

Esperienza dell'utente finale con una risposta di blocco

Esempio di 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ì	Versione dell'API.
action	Stringa	Sì	Il valore deve essere ValidationError.
stato	Integer/String	Sì	Deve essere un valore 400o "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 dell'utente finale con una risposta di errore di convalida

Procedure consigliate e risoluzione dei problemi

Uso delle funzioni cloud serverless

Le funzioni serverless, ad esempio 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 l'API Connessione or.
• 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 ricevuto alcuno, esegue un altro tentativo (riprovare) alla 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 delle API downstream, 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 di TLS e della suite di crittografia.

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. Controllare il livello di autenticazione dell'API e la configurazione corrispondente nel connettore API.
• Se necessario, usare livelli più aggressivi 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
• Introduzione agli esempi di avvio rapido.