Aggiungere un flusso di lavoro di approvazione personalizzato all'iscrizione self-service

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

Con i connettori API, è possibile eseguire l'integrazione con i 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

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

Registrare un'applicazione per il sistema di approvazione

Suggerimento

I passaggi descritti in questo articolo possono variare leggermente in base al portale da cui si inizia.

È 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 sull'autenticazione e sull'autorizzazione per Microsoft Graph.

1. Accedere all'interfaccia di amministrazione di Microsoft Entra almeno come Amministratore utenti.
2. Passare a Applicazioni> di identità>Registrazioni app e quindi selezionare Nuova registrazione.
3. Immettere un nome per l'applicazione, ad esempio iscrizione Approvazioni.
4. Selezionare Registra. È possibile lasciare gli altri campi per impostazione predefinita.

1. In Gestisci nel menu a sinistra selezionare Autorizzazioni API e quindi selezionare Aggiungi un'autorizzazione.
2. Nella pagina Richiedi le autorizzazioni dell'API selezionare Microsoft Graph, quindi selezionare Autorizzazioni applicazione.
3. In Seleziona autorizzazioni espandere Utente e 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.

9. Nella pagina Autorizzazioni API selezionare Concedi consenso amministratore per (nome tenant) e quindi selezionare Sì.
10. In Gestisci nel menu a sinistra selezionare Certificati e segreti e quindi selezionare Nuovo segreto client.
11. Immettere una descrizione per il segreto, ad esempio Approvazioni segreto client e selezionare la durata per la scadenza del segreto client. Selezionare Aggiungi.
12. 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.

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

Si creeranno quindi i connettori API per il flusso utente di iscrizione self-service. L'API del sistema di approvazione richiede due connettori e endpoint corrispondenti, come gli esempi illustrati di seguito. Questi connettori API eseguono le operazioni seguenti:

• Controllare lo 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 è già stata negata. Se il sistema di approvazione esegue solo decisioni di approvazione automatica, questo connettore API potrebbe non essere necessario. Esempio di connettore API "Verifica stato approvazione".

• Richiedere l'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 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

Ora si aggiungeranno i connettori API a un flusso utente di iscrizione self-service con questi passaggi:

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

2. Passare a Identità>identità esterne>Flussi utente e quindi selezionare il flusso utente per cui si vuole abilitare il connettore API.

3. 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: selezionare il connettore API per lo stato di approvazione, ad esempio Controllare lo stato dell'approvazione.
   • Prima di creare l'utente: selezionare il connettore API di richiesta di approvazione, ad esempio Richiedi approvazione.

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

Richiedere e risposte per il connettore API "Controlla stato approvazione"

Esempio della richiesta ricevuta dall'API dal connettore API "Controlla stato 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à. 'email' viene sempre inviato.

Risposta di continuazione per "Controllare lo stato di approvazione"

L'endpoint dell'API Controlla stato approvazione deve restituire una risposta di continuazione se:

• L'utente non ha precedentemente richiesto un'approvazione.

Esempio della risposta di continuazione:

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "Continue"
}

Risposta di blocco per "Controllare lo stato dell'approvazione"

L'endpoint dell'API Controlla stato 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 bloccabili:

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

Richiedere e risposte per il connettore API "Richiedi approvazione"

Esempio di 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 attestazioni esatte inviate all'API dipendono dalle informazioni raccolte dall'utente o fornite dal provider di identità.

Risposta di continuazione per "Richiedi approvazione"

L'endpoint dell'API Di approvazione della richiesta deve restituire una risposta di continuazione se:

• L'utente può essere approvato automaticamente.

Esempio della 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 "Richiedere l'approvazione"

L'endpoint dell'API Di approvazione della richiesta 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 bloccabili:

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 posta elettronica

Importante

Il sistema di approvazione deve verificare in modo esplicito che identitiesidentities[0] sia presente e identities[0].issuer 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 un passcode monouso tramite posta elettronica, è possibile usare l'API di creazione utente.

1. Il sistema di approvazione usa 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"
}

2. 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 inviata all'API, sostituendo il carattere con e anteponendo l'attestazione email@a #EXT@<tenant-name>.onmicrosoft.com._
accountEnabled	Sì	Deve essere impostato su true.
mail	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, citye altri. 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, facoltativamente, l'API di aggiornamento dell'utente per assegnare più attributi all'utente.

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

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

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

Passaggi successivi

• Aggiungere un flusso utente di iscrizione self-service
• Aggiungere un connettore API
• Proteggere il connettore API
• iscrizione self-service per gli utenti guest con un esempio di approvazione manuale.