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.
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.
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.
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.
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.
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.
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.
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 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".
Scopri in che modo Microsoft Entra External ID può offrire esperienze di accesso sicure e semplici per i clienti consumer e aziendali. Esplorare la creazione di tenant, la registrazione delle app, la personalizzazione del flusso e la sicurezza degli account.
Illustrare le funzionalità di Microsoft Entra ID per modernizzare le soluzioni di identità, implementare soluzioni ibride e implementare la governance delle identità.