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.

Registrare un'applicazione per il sistema di approvazione

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

1. Accedere all'interfaccia di amministrazione di Microsoft Entra almeno come Amministratore utenti.
2. Andare a Identità>Applicazioni>Registrazioni app, quindi selezionare Nuova registrazione.
3. Immettere un nome per l'applicazione, ad esempio Approvazioni di iscrizioni.
4. Selezionare Registra. È possibile lasciare gli altri campi con le impostazioni predefinite.

1. In Gestisci nel menu a sinistra, selezionare Autorizzazioni API, 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, 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 Autorizza consenso amministratore per (nome del proprio tenant), quindi selezionare Sì.
10. In Gestisci nel menu a sinistra, selezionare Certificati e segreti, 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

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:

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

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

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

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.

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

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

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.

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

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

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.

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.