API e personalizzazione di Microsoft Entra B2B Collaboration

Articolo
03/05/2024

Con l'API REST di Microsoft Graph, è possibile personalizzare il processo di invito in modo ottimale per l'organizzazione.

Funzionalità dell'API di invito

L'API offre le funzionalità seguenti:

Invitare un utente esterno con qualsiasi indirizzo di posta elettronica.

"invitedUserDisplayName": "Taylor"
"invitedUserEmailAddress": "taylor@fabrikam.com"

Personalizzare la pagina di destinazione visualizzata dagli utenti dopo avere accettato l'invito.
```
"inviteRedirectUrl": "https://myapps.microsoft.com/"
```
Scegliere di inviare la posta di invito standard tramite Microsoft.
```
"sendInvitationMessage": true
```
con un messaggio al destinatario che è possibile personalizzare.
```
"customizedMessageBody": "Hello Sam, let's collaborate!"
```
Scegliere di mettere in copia conoscenza le persone che si vuole mantenere nel ciclo relativo all'invito di questo collaboratore.
Oppure personalizzare completamente il flusso di lavoro di invito e onboarding scegliendo di non inviare notifiche tramite Microsoft Entra ID.
```
"sendInvitationMessage": false
```
In questo caso, si ottiene un URL di riscatto dall'API, che è possibile incorporare in un modello di messaggio di posta elettronica, in un messaggio istantaneo o in un altro metodo di distribuzione.
Infine, se sei un amministratore, puoi scegliere di invitare l'utente come membro.
```
"invitedUserType": "Member"
```

Determinare se un utente è già stato invitato nella directory

È possibile usare l'API di invito per determinare se un utente esiste già nel tenant delle risorse. Ciò può essere utile quando si sviluppa un'app che usa l'API di invito per invitare un utente. Se l'utente esiste già nella directory delle risorse, non riceverà un invito, quindi è possibile eseguire prima una query per determinare se il messaggio di posta elettronica esiste già come UPN o un'altra proprietà di accesso.

Assicurarsi che il dominio di posta elettronica dell'utente non faccia parte del dominio verificato del tenant delle risorse.

Nel tenant della risorsa usare la query get user seguente in cui {0} è l'indirizzo di posta elettronica che si sta invitando:

“userPrincipalName eq '{0}' or mail eq '{0}' or proxyAddresses/any(x:x eq 'SMTP:{0}') or signInNames/any(x:x eq '{0}') or otherMails/any(x:x eq '{0}')"

Modello di autorizzazione

L'API può essere eseguita nelle modalità di autorizzazione seguenti:

Modalità app + utente

In questa modalità, chiunque usi l'API deve disporre delle autorizzazioni per creare gli inviti B2B.

Modalità solo app

In un contesto di solo app l'invito viene inviato solo se nell'app è presente l'ambito User.Invite.All.

Per altre informazioni, vedere: https://developer.microsoft.com/graph/docs/authorization/permission_scopes

PowerShell

È possibile usare PowerShell per aggiungere e invitare facilmente utenti esterni a un'organizzazione. Creare un invito tramite il cmdlet:

New-MgInvitation

È possibile usare le opzioni seguenti:

-InvitedUserDisplayName
-InvitedUserEmailAddress
-SendInvitationMessage
-InvitedUserMessageInfo

Stato invito

Dopo aver inviato un invito a un utente esterno, è possibile usare il cmdlet Get-MgBetaUser per verificare se l'utente lo ha accettato. Quando un utente esterno invia un invito, vengono popolate le proprietà seguenti di Get-MgBetaUser:

externalUserState indica se l'invito è PendingAcceptance o Accepted.
externalUserStateChangeDateTime mostra il timestamp per la modifica più recente alla proprietà externalUserState .

È possibile usare l'opzione Filtro per filtrare i risultati in base a externalUserState. L'esempio seguente mostra come filtrare i risultati per mostrare solo gli utenti in attesa di invito. L'esempio mostra anche l'opzione Format-List che consente di specificare le proprietà da visualizzare.

Get-MgBetaUser -Filter "externalUserState eq 'PendingAcceptance'" | Format-List -Property DisplayName,UserPrincipalName,externalUserState,externalUserStateChangeDateTime

Nota

Assicurarsi di avere la versione più recente del modulo PowerShell di Microsoft Graph

Vedi anche

Eseguire il check-out del riferimento all'API di invito in https://developer.microsoft.com/graph/docs/api-reference/v1.0/resources/invitation.