API et personnalisation de Microsoft Entra B2B Collaboration

  • Article

Avec l’API REST Microsoft Graph, vous pouvez personnaliser le processus d’invitation de la manière qui convient le mieux à votre organisation.

Fonctionnalités de l’API d’invitation

L’API offre les fonctionnalités suivantes :

  1. Invitez un utilisateur externe avec n’importe quelle adresse e-mail.

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

  2. Personnalisez l’emplacement vers lequel vous souhaitez diriger vos utilisateurs une fois qu’ils ont accepté l’invitation.

    "inviteRedirectUrl": "https://myapps.microsoft.com/"

  3. Choisissez d’envoyer l’e-mail d’invitation standard par notre intermédiaire.

    "sendInvitationMessage": true

    accompagné d’un message au destinataire que vous pouvez personnaliser.

    "customizedMessageBody": "Hello Sam, let's collaborate!"

  4. Et choisissez de mettre en copie des personnes que vous souhaitez informer de votre invitation de ce collaborateur.

  5. Ou personnalisez entièrement votre flux de travail d’invitation et d’accueil en choisissant de ne pas envoyer des notifications via Microsoft Entra ID.

    "sendInvitationMessage": false

    Dans ce cas, vous obtenez une URL d’échange de la part de l’API que vous pouvez incorporer dans un modèle d’e-mail, un message instantané ou toute autre méthode de distribution de votre choix.

  6. Enfin, si vous êtes un administrateur, vous pouvez choisir d’inviter l’utilisateur en tant que membre.

    "invitedUserType": "Member"

Déterminer si un utilisateur a déjà été invité dans votre répertoire

Vous pouvez utiliser l’API d’invitation pour déterminer si un utilisateur existe déjà dans votre locataire de ressource. Cela peut être utile lorsque vous développez une application qui utilise l’API d’invitation pour inviter un utilisateur. Si l’utilisateur existe déjà dans votre répertoire de ressources, il ne recevra pas d’invitation. Vous pouvez donc d’abord exécuter une requête pour déterminer si l’adresse e-mail existe en tant qu’UPN ou autre propriété de connexion.

  1. Vérifiez que le domaine de messagerie de l’utilisateur ne fait pas partie du domaine vérifié de votre locataire de ressource.

  2. Dans le locataire de la ressource, utilisez la requête d’obtention d’utilisateur suivante, où {0} est l’adresse e-mail que vous invitez :

    “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}')"

Modèle d’autorisation

L’API peut être exécutée dans les modes d’autorisation suivants :

Mode Application + Utilisateur

Dans ce mode, toute personne utilisant l’API doit disposer des autorisations permettant de créer des invitations B2B.

Mode Application uniquement

Dans le contexte Application uniquement, l’application a besoin de l’étendue User.Invite.All pour que l’invitation réussisse.

Pour plus d’informations, consultez : https://developer.microsoft.com/graph/docs/authorization/permission_scopes

PowerShell

Vous pouvez utiliser PowerShell pour ajouter et inviter facilement des utilisateurs externes au sein d’une organisation. Créez une invitation à l’aide de l’applet de commande suivante :

New-MgInvitation

Vous pouvez utiliser les options suivantes :

  • -InvitedUserDisplayName
  • -InvitedUserEmailAddress
  • -SendInvitationMessage
  • -InvitedUserMessageInfo

Statut de l’invitation

Une fois que vous avez envoyé une invitation à un utilisateur externe, vous pouvez utiliser l’applet de commande Get-MgBetaUser pour voir s’il l’a acceptée. Les propriétés suivantes de l’applet de commande Get-MgBetaUser sont remplies quand une invitation est envoyée à un utilisateur externe :

  • externalUserState indique si le statut de l’invitation est PendingAcceptance (En attente d’acceptation) ou Accepted (Acceptée).
  • externalUserStateChangeDateTime affiche l’horodatage de la modification la plus récente de la propriété externalUserState.

Vous pouvez utiliser l’option Filtrer pour filtrer les résultats en fonction de la propriété externalUserState. L’exemple ci-dessous montre comment filtrer les résultats pour afficher uniquement les utilisateurs qui ont une invitation en attente. L’exemple illustre également l’option Format-List, qui vous permet de spécifier les propriétés à afficher.

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

Remarque

Veillez à disposer de la dernière version du module PowerShell Microsoft Graph.

Voir aussi

Consultez les informations de référence sur les API d’invitation dans https://developer.microsoft.com/graph/docs/api-reference/v1.0/resources/invitation.

Étapes suivantes