Microsoft Entra B2B Collaboration: API und Anpassung

  • Artikel

Gilt für:Grüner Kreis mit weißem Häkchen. Mitarbeitermandanten Weißer Kreis mit grauem X. Externe Mandanten (weitere Informationen)

Mit der Microsoft Graph REST-API können Sie den Einladungsprozess so anpassen, wie es für Ihre Organisation am besten ist.

Funktionen der Einladungs-API

Die API bietet die folgenden Funktionen:

  1. Laden Sie einen externen Benutzer mit einer beliebigen E-Mail-Adresse ein.

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

  2. Legen Sie fest, an welche URL Benutzer weitergeleitet werden, nachdem sie Ihre Einladung angenommen haben.

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

  3. Senden Sie die Standardeinladung über uns.

    "sendInvitationMessage": true

    Fügen Sie eine anpassbare Nachricht an den Empfänger hinzu.

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

  4. Sie können Benutzer auf Cc setzen, die Sie über die Einladung dieses Benutzers informieren möchten.

  5. Sie können Ihren Einladungs- und Onboardingworkflow auch vollständig benutzerdefiniert anpassen, indem Sie Benachrichtigungen nicht über Microsoft Entra ID senden.

    "sendInvitationMessage": false

    In diesem Fall gibt die API eine Einlösungs-URL zurück, die Sie in eine E-Mail-Vorlage, eine Sofortnachricht oder eine andere Verteilungsmethode Ihrer Wahl einbetten können.

  6. Wenn Sie Administrator sind, können Sie den Benutzer als Mitglied einladen.

    "invitedUserType": "Member"

Ermitteln von bereits in Ihr Verzeichnis eingeladenen Benutzern

Mit der Einladungs-API können Sie ermitteln, ob ein Benutzer bereits in Ihrem Ressourcenmandanten vorhanden ist. Dies kann hilfreich sein, wenn Sie eine App entwickeln, die zum Einladen eines Benutzers die Einladungs-API verwendet. Wenn der Benutzer bereits in Ihrem Ressourcenverzeichnis vorhanden ist, erhält er keine Einladung. Sie können also zuerst eine Abfrage ausführen, um zu ermitteln, ob die E-Mail-Adresse bereits als Benutzerprinzipalname (UPN) oder andere Anmeldeeigenschaft vorhanden ist.

  1. Stellen Sie sicher, dass die E-Mail-Domäne des Benutzers nicht zur überprüften Domäne Ihres Ressourcenmandanten gehört.

  2. Verwenden Sie zum Abfragen des Benutzers im Ressourcenmandanten die folgende Abfrage, wobei {0} der E-Mail-Adresse des einzuladenden Benutzers entspricht:

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

Autorisierungsmodell

Die API kann in folgenden Autorisierungsmodi ausgeführt werden:

Modus „App und Benutzer“

In diesem Modus benötigt der jeweilige Benutzer der API die Berechtigungen, B2B-Einladungen zu erstellen.

Reiner App-Modus

Im reinen App-Modus benötigt die App den Berechtigungsbereich „User.Invite.All“, damit die Einladung erfolgreich ist.

Weitere Informationen finden Sie unter: https://developer.microsoft.com/graph/docs/authorization/permission_scopes

PowerShell

Sie können PowerShell verwenden, um externe Benutzer ganz einfach in eine Organisation einzuladen und dieser hinzuzufügen. Erstellen Sie eine Einladung mit dem Cmdlet:

New-MgInvitation

Sie können die folgenden Optionen verwenden:

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

Einladungsstatus

Nachdem Sie einem externen Benutzer eine Einladung gesendet haben, können Sie mithilfe des Cmdlets Get-MgBetaUser feststellen, ob er sie angenommen hat. Die folgenden Eigenschaften von „Get-MgBetaUser“ werden aufgefüllt, wenn einem externen Benutzer eine Einladung gesendet wird:

  • externalUserState zeigt an, ob der Status der Einladung PendingAcceptance oder Accpeted ist.
  • externalUserStateChangeDateTime zeigt den Zeitstempel für die letzte Änderung an der Eigenschaft externalUserState an.

Sie können die Option Filterverwenden, um die Ergebnisse nach externalUserState zu filtern. Das folgende Beispiel zeigt, wie Sie Ergebnisse so filtern, dass nur Benutzer mit einer ausstehenden Einladung angezeigt werden. Das Beispiel zeigt außerdem die Option Format-List, mit der Sie die anzuzeigenden Eigenschaften angeben können.

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

Hinweis

Stellen Sie sicher, dass Sie über die aktuelle Version des Microsoft Graph PowerShell-Moduls verfügen

Siehe auch

Sehen Sie sich die Einladungs-API-Referenz in https://developer.microsoft.com/graph/docs/api-reference/v1.0/resources/invitation an.

Nächste Schritte