Microsoft Entra B2B-samenwerkings-API en aanpassing

  • Artikel

Met de Microsoft Graph REST API kunt u het uitnodigingsproces aanpassen op een manier die het beste werkt voor uw organisatie.

Mogelijkheden van de uitnodigings-API

De API biedt de volgende mogelijkheden:

  1. Nodig een externe gebruiker uit met een e-mailadres.

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

  2. Pas aan waar uw gebruikers terechtkomen nadat ze hun uitnodiging hebben geaccepteerd.

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

  3. Kies ervoor om de standaarduitnodigingsmail via ons te sturen.

    "sendInvitationMessage": true

    met een bericht aan de geadresseerde die u kunt aanpassen.

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

  4. En kies voor CC: personen die u in de gaten wilt houden over uw uitnodiging voor deze samenwerker.

  5. Of pas uw uitnodiging en onboarding-werkstroom volledig aan door ervoor te kiezen geen meldingen te verzenden via Microsoft Entra-id.

    "sendInvitationMessage": false

    In dit geval krijgt u een inwissel-URL terug van de API die u kunt insluiten in een e-mailsjabloon, chatbericht of een andere distributiemethode van uw keuze.

  6. Als u een beheerder bent, kunt u ervoor kiezen om de gebruiker als lid uit te nodigen.

    "invitedUserType": "Member"

Bepalen of een gebruiker al is uitgenodigd voor uw directory

U kunt de uitnodigings-API gebruiken om te bepalen of er al een gebruiker bestaat in uw resourcetenant. Dit kan handig zijn wanneer u een app ontwikkelt die gebruikmaakt van de uitnodigings-API om een gebruiker uit te nodigen. Als de gebruiker al bestaat in uw resourcemap, ontvangt deze geen uitnodiging, zodat u eerst een query kunt uitvoeren om te bepalen of het e-mailbericht al bestaat als een UPN of een andere aanmeldingseigenschap.

  1. Zorg ervoor dat het e-maildomein van de gebruiker geen deel uitmaakt van het geverifieerde domein van uw resourcetenant.

  2. Gebruik in de resourcetenant de volgende get user query where {0} is the email address you're invite:

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

Autorisatiemodel

De API kan worden uitgevoerd in de volgende autorisatiemodi:

App + gebruikersmodus

In deze modus moet degene die de API gebruikt de machtigingen hebben om B2B-uitnodigingen te maken.

Alleen app-modus

Alleen in de context van de app heeft de app het bereik User.Invite.All nodig om de uitnodiging te laten slagen.

Zie voor meer informatie: https://developer.microsoft.com/graph/docs/authorization/permission_scopes

Powershell

U kunt PowerShell gebruiken om eenvoudig externe gebruikers aan een organisatie toe te voegen en uit te nodigen. Maak een uitnodiging met behulp van de cmdlet:

New-MgInvitation

U kunt de volgende opties gebruiken:

  • -InviteUserDisplayName
  • -InviteUserEmailAddress
  • -SendInvitationMessage
  • -InviteUserMessageInfo

Uitnodigingsstatus

Nadat u een externe gebruiker een uitnodiging hebt verzonden, kunt u de cmdlet Get-MgBetaUser gebruiken om te zien of deze is geaccepteerd. De volgende eigenschappen van Get-MgBetaUser worden ingevuld wanneer een externe gebruiker een uitnodiging ontvangt:

  • externalUserState geeft aan of de uitnodiging PendingAcceptance of Geaccepteerd is.
  • externalUserStateChangeDateTime toont de tijdstempel voor de meest recente wijziging in de eigenschap externalUserState .

U kunt de filteroptie gebruiken om de resultaten te filteren op externalUserState. In het onderstaande voorbeeld ziet u hoe u resultaten filtert om alleen gebruikers weer te geven die een uitnodiging in behandeling hebben. In het voorbeeld ziet u ook de optie Opmaaklijst , waarmee u de eigenschappen kunt opgeven die moeten worden weergegeven.

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

Notitie

Zorg ervoor dat u de nieuwste versie van de Microsoft Graph PowerShell-module hebt

Zie ook

Bekijk de api-verwijzing voor de uitnodiging in https://developer.microsoft.com/graph/docs/api-reference/v1.0/resources/invitation.

Volgende stappen