Aggiungere un connettore API a un flusso utente
Si applica a: Tenant della forza lavoro Tenant esterni (altre informazioni)
Per usare un connettore API, creare prima il connettore API, quindi abilitarlo in un flusso utente.
Importante
- dal 12 luglio 2021, se i clienti di Microsoft Entra B2B impostano nuove integrazioni di Google da utilizzare con la registrazione self-service per le loro applicazioni personalizzate o aziendali, l'autenticazione con le identità di Google non funzionerà finché le autenticazioni vengono spostate nelle web-view del sistema. Altre informazioni.
- Dal 30 settembre 2021, Google sta dismettendo il supporto per l'accesso con web-view incorporata. 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
La procedura descritta in questo articolo può 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.
Dopo la federazione con un provider di identità durante l'accesso
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
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.
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
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
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.