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.

Creare un connettore API

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

2. Andare a Identità>Identità esterne>Informazioni generali.

3. Selezionare Tutti i connettori API, quindi selezionare Nuovo connettore API.

   

4. Specificare un nome visualizzato per la chiamata. Ad esempio, controllare lo stato di 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 connettore API.

   

7. 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.

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. Andare a Identità>Identità esterne>Informazioni generali.

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

4. 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

   

5. 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
}

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.",
}

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.",
}

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.