Aggiungere un flusso di lavoro di approvazione personalizzato all'iscrizione self-service
Si applica a: Tenant della forza lavoro Tenant esterni (altre informazioni)
Con i connettori API è possibile eseguire l'integrazione con i propri flussi di lavoro di approvazione personalizzati con l'iscrizione self-service, in modo da poter gestire gli account utente guest creati nel tenant.
Questo articolo fornisce un esempio di come eseguire l'integrazione con un sistema di approvazione. In questo esempio, il flusso utente di iscrizione self-service raccoglie i dati utente durante il processo di iscrizione e lo passa al sistema di approvazione. Il sistema di approvazione può quindi:
- Approvare automaticamente l'utente e consentire a Microsoft Entra ID di creare l'account utente.
- Attivare una revisione manuale. Se la richiesta viene approvata, il sistema di approvazione usa Microsoft Graph per effettuare il provisioning dell'account utente. Il sistema di approvazione può anche notificare all'utente che è stato creato il proprio account.
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.
Registrare un'applicazione per il sistema di approvazione
Suggerimento
I passaggi descritti in questo articolo possono variare leggermente in base al portale di partenza.
È necessario registrare il sistema di approvazione come applicazione nel tenant di Microsoft Entra in modo che possa eseguire l'autenticazione con Microsoft Entra ID e avere l'autorizzazione per creare utenti. Altre informazioni sulle Nozioni di base su autenticazione e autorizzazione di base per Microsoft Graph.
- Accedere all'interfaccia di amministrazione di Microsoft Entra almeno come Amministratore utenti.
- Andare a Identità>Applicazioni>Registrazioni app, quindi selezionare Nuova registrazione.
- Immettere un nome per l'applicazione, ad esempio Approvazioni di iscrizioni.
- Selezionare Registra. È possibile lasciare gli altri campi con le impostazioni predefinite.
- In Gestisci nel menu a sinistra, selezionare Autorizzazioni API, quindi selezionare Aggiungi un'autorizzazione.
- Nella pagina Richiedi le autorizzazioni dell'API selezionare Microsoft Graph, quindi selezionare Autorizzazioni applicazione.
- In Seleziona autorizzazioni, espandere Utente, quindi selezionare la casella di controllo User.ReadWrite.All. Questa autorizzazione consente al sistema di approvazione di creare l'utente dopo l'approvazione. Quindi seleziona Aggiungi autorizzazioni.
- Nella pagina Autorizzazioni API, selezionare Autorizza consenso amministratore per (nome del proprio tenant), quindi selezionare Sì.
- In Gestisci nel menu a sinistra, selezionare Certificati e segreti, quindi selezionare Nuovo segreto client.
- Immettere una Descrizione per il segreto, ad esempio Approvazioni segreto client e selezionare la durata per la Scadenza del segreto client. Selezionare Aggiungi.
- Copiare il valore del segreto client. I valori dei segreti client possono essere visualizzati solo subito dopo la creazione. Assicurarsi di salvare il segreto al momento della creazione, prima di uscire dalla pagina.
- Configurare il sistema di approvazione per usare l'ID applicazione come ID client e il segreto client generato per l'autenticazione con Microsoft Entra ID.
Creare i connettori API
Quindi, verranno creati i connettori API per il flusso utente di iscrizione self-service. L'API del sistema di approvazione richiede due connettori e gli endpoint corrispondenti, come negli esempi illustrati di seguito. Questi connettori API eseguono le operazioni seguenti:
- Controlla stato dell'approvazione. Inviare una chiamata al sistema di approvazione subito dopo l'accesso di un utente con un provider di identità per verificare se l'utente ha una richiesta di approvazione esistente o se è già stata negata. Se il sistema di approvazione esegue solo decisioni di approvazione automatica, questo connettore API potrebbe non essere necessario. Esempio di un connettore API "Verifica stato approvazione".
- Richiedi approvazione: Inviare una chiamata al sistema di approvazione dopo che un utente completa la pagina della raccolta di attributi, ma prima della creazione dell'account utente, per richiedere l'approvazione. La richiesta di approvazione può essere concessa automaticamente o esaminata manualmente. Esempio di un connettore API "Richiedi approvazione".
Per creare questi connettori, seguire la procedura descritta in Creare un connettore API.
Abilitare i connettori API in un flusso utente
A questo punto, si aggiungeranno i connettori API a un flusso utente di iscrizione self-service con questi passaggi:
Accedere all'interfaccia di amministrazione di Microsoft Entra almeno come Amministratore utenti.
Andare a Identità>Identità esterne>Flussi utente, quindi selezionare il flusso utente per cui si vuole abilitare 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'iscrizione: selezionare il connettore API per lo stato di approvazione, ad esempio Controlla stato dell'approvazione.
- Prima di creare l'utente: Selezionare il connettore API di richiesta di approvazione, ad esempio Richiedi approvazione.
- Seleziona Salva.
Controllare il flusso di iscrizione con le risposte dell'API
Il sistema di approvazione può usare le risposte quando viene chiamato per controllare il flusso di iscrizione.
Richiesta e risposte per il connettore API "Controlla stato dell'approvazione"
Esempio della richiesta ricevuta dall'API dal connettore API "Controlla stato dell'approvazione":
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.
Risposta di continuazione per "Controlla stato dell'approvazione"
L'endpoint dell'API Controlla stato dell'approvazione deve restituire una risposta di continuazione se:
- L'utente non ha precedentemente richiesto un'approvazione.
Esempio di risposta di continuazione:
HTTP/1.1 200 OK
Content-type: application/json
{
"version": "1.0.0",
"action": "Continue"
}
Risposta di blocco per "Controlla stato dell'approvazione"
L'endpoint dell'API Controlla stato dell'approvazione deve restituire una risposta di blocco se:
- L'approvazione dell'utente è in sospeso.
- L'utente è stato negato e non deve essere autorizzato a richiedere nuovamente l'approvazione.
Di seguito sono riportati esempi di risposte di blocco:
HTTP/1.1 200 OK
Content-type: application/json
{
"version": "1.0.0",
"action": "ShowBlockPage",
"userMessage": "Your access request is already processing. You'll be notified when your request has been approved.",
}
HTTP/1.1 200 OK
Content-type: application/json
{
"version": "1.0.0",
"action": "ShowBlockPage",
"userMessage": "Your sign up request has been denied. Please contact an administrator if you believe this is an error",
}
Richiesta e risposte per il connettore API "Richiedi approvazione"
Esempio della richiesta HTTP ricevuta dall'API dal connettore API "Richiedi approvazione":
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à.
Risposta di continuazione per "Richiedi approvazione"
L'endpoint API Richiedi approvazione deve restituire una risposta di continuazione se:
- L'utente può essere approvato automaticamente.
Esempio di risposta di continuazione:
HTTP/1.1 200 OK
Content-type: application/json
{
"version": "1.0.0",
"action": "Continue"
}
Importante
Se viene ricevuta una risposta di continuazione, Microsoft Entra ID crea un account utente e indirizza l'utente all'applicazione.
Risposta di blocco per "Richiedi approvazione"
L'endpoint API Richiedi approvazione deve restituire una risposta di blocco se:
- È stata creata una richiesta di approvazione utente ed è ora in sospeso.
- Una richiesta di approvazione utente è stata negata automaticamente.
Di seguito sono riportati esempi di risposte di blocco:
HTTP/1.1 200 OK
Content-type: application/json
{
"version": "1.0.0",
"action": "ShowBlockPage",
"userMessage": "Your account is now waiting for approval. You'll be notified when your request has been approved.",
}
HTTP/1.1 200 OK
Content-type: application/json
{
"version": "1.0.0",
"action": "ShowBlockPage",
"userMessage": "Your sign up request has been denied. Please contact an administrator if you believe this is an error",
}
L'oggetto userMessage
nella risposta viene visualizzato all'utente, ad esempio:
Creazione dell'account utente dopo l'approvazione manuale
Dopo che il sistema di approvazione personalizzato ottiene l'approvazione manuale, crea un account utente usando Microsoft Graph. Il modo in cui il sistema di approvazione effettua il provisioning dell'account utente dipende dal provider di identità usato dall'utente.
Per un utente federato di Google o Facebook e un passcode monouso tramite e-mail
Importante
Il sistema di approvazione deve verificare in modo esplicito che identities
, identities[0]
e identities[0].issuer
siano presenti e che identities[0].issuer
sia uguale a "facebook", "google" o "mail" per utilizzare questo metodo.
Se l'utente ha eseguito l'accesso con un account Google o Facebook o con un passcode monouso tramite e-mail, è possibile usare l'API di creazione utente.
- Il sistema di approvazione riceve la richiesta HTTP dal flusso utente.
POST <Approvals-API-endpoint>
Content-type: application/json
{
"email": "johnsmith@outlook.com",
"identities": [
{
"signInType":"federated",
"issuer":"facebook.com",
"issuerAssignedId":"0123456789"
}
],
"displayName": "John Smith",
"city": "Redmond",
"extension_<extensions-app-id>_CustomAttribute": "custom attribute value",
"ui_locales":"en-US"
}
- Il sistema di approvazione usa Microsoft Graph per creare un account utente.
POST https://graph.microsoft.com/v1.0/users
Content-type: application/json
{
"userPrincipalName": "johnsmith_outlook.com#EXT@contoso.onmicrosoft.com",
"accountEnabled": true,
"mail": "johnsmith@outlook.com",
"userType": "Guest",
"identities": [
{
"signInType":"federated",
"issuer":"facebook.com",
"issuerAssignedId":"0123456789"
}
],
"displayName": "John Smith",
"city": "Redmond",
"extension_<extensions-app-id>_CustomAttribute": "custom attribute value"
}
Parametro | Richiesto | Descrizione |
---|---|---|
userPrincipalName | Sì | Può essere generato accettando l'attestazione email inviata all'API, sostituendo il carattere @ con _ e anticipandone lo stato in sospeso in #EXT@<tenant-name>.onmicrosoft.com . |
accountEnabled | Sì | Deve essere impostato su true . |
Sì | Equivalente all'attestazione email inviata all'API. |
|
userType | Sì | Deve essere Guest . Definisce l'utente come utente guest. |
identità | Sì | Informazioni sull'identità federata. |
<otherBuiltInAttribute> | No | Altri attributi predefiniti, ad esempio displayName , city e non solo. I nomi dei parametri sono gli stessi dei parametri inviati dal connettore API. |
<extension_{extensions-app-id}_CustomAttribute> | No | Attributi personalizzati relativi all'utente. I nomi dei parametri sono gli stessi dei parametri inviati dal connettore API. |
Per un utente federato di Microsoft Entra o un account Microsoft
Se un utente accede con un account Microsoft Entra federato o un account Microsoft, è necessario usare l'API di invito per creare l'utente e, in alternativa, l'API di aggiornamento utente per assegnare più attributi all'utente.
- Il sistema di approvazione riceve la richiesta HTTP dal flusso utente.
POST <Approvals-API-endpoint>
Content-type: application/json
{
"email": "johnsmith@fabrikam.onmicrosoft.com",
"displayName": "John Smith",
"city": "Redmond",
"extension_<extensions-app-id>_CustomAttribute": "custom attribute value",
"ui_locales":"en-US"
}
- Il sistema di approvazione crea l'invito usando l'oggetto
email
fornito dal connettore API.
POST https://graph.microsoft.com/v1.0/invitations
Content-type: application/json
{
"invitedUserEmailAddress": "johnsmith@fabrikam.onmicrosoft.com",
"inviteRedirectUrl" : "https://myapp.com"
}
Esempio di risposta:
HTTP/1.1 201 OK
Content-type: application/json
{
...
"invitedUser": {
"id": "<generated-user-guid>"
}
}
- Il sistema di approvazione usa l'ID dell'utente invitato per aggiornare l'account dell'utente con gli attributi utente raccolti (facoltativo).
PATCH https://graph.microsoft.com/v1.0/users/<generated-user-guid>
Content-type: application/json
{
"displayName": "John Smith",
"city": "Redmond",
"extension_<extensions-app-id>_AttributeName": "custom attribute value"
}