API совместной работы Microsoft Entra B2B и настройка

Статья
02/29/2024

Область применения: Зеленый круг с белым проверка символом знака. клиенты рабочей силы внешние Белый круг с серым символом X. клиенты (дополнительные сведения)

С помощью REST API Microsoft Graph можно настроить процесс приглашения таким образом, который лучше всего подходит для вашей организации.

Возможности API приглашения

Интерфейс API предоставляет следующие возможности:

Пригласите внешнего пользователя, используя любой адрес электронной почты.
```
"invitedUserDisplayName": "Taylor"
"invitedUserEmailAddress": "taylor@fabrikam.com"
```
Настройте, куда будет перенаправляться пользователь после принятия приглашения.
```
"inviteRedirectUrl": "https://myapps.microsoft.com/"
```
Выберите для отправки стандартной почты приглашения через нас.
```
"sendInvitationMessage": true
```
с сообщением получателю, который можно настроить.
```
"customizedMessageBody": "Hello Sam, let's collaborate!"
```
Выберите также, кому отправить копию. Это могут быть пользователи, которых вы хотите известить о приглашении данного сотрудника.
Или полностью настройте приглашение и рабочий процесс подключения, выбрав не отправлять уведомления с помощью идентификатора Microsoft Entra.
```
"sendInvitationMessage": false
```
В этом случае вы получите URL-адрес активации из API, который можно вставить в шаблон электронного сообщения, отправить в мгновенном сообщении или распространить другим способом на свое усмотрение.
Наконец, если вы являетесь администратором, вы можете пригласить пользователя в качестве участника.
```
"invitedUserType": "Member"
```

Определите, был ли пользователь уже приглашен в ваш каталог

Вы можете использовать API приглашения, чтобы определить, существует ли уже пользователь в вашем клиенте ресурсов. Это может быть полезно при разработке приложения, использующего API приглашения для приглашения пользователя. Если пользователь уже существует в каталоге ресурсов, он не получит приглашение, поэтому сначала можно выполнить запрос, чтобы определить, существует ли сообщение электронной почты как имя участника-пользователя или другое свойство входа.

Убедитесь, что домен электронной почты пользователя не является частью подтвержденного домена вашего клиента ресурса.
В клиенте ресурсов используйте следующий запрос на получение пользователя, где {0} - это адрес электронной почты, на который направлено приглашение:
```
“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}')"
```

Модель авторизации

API можно запустить в следующих режимах авторизации:

Приложение + пользователь

В этом режиме приложение или пользователь, использующий API, должен иметь разрешения на создание приглашений в службу B2B.

Только приложение

В контексте "только приложение" для успешного выполнения приглашения приложению требуется область User.Invite.All.

Для получения дополнительной информации см. https://developer.microsoft.com/graph/docs/authorization/permission_scopes

PowerShell

Вы можете добавлять и приглашать в организацию внешних пользователей, теперь можно использовать PowerShell. Создайте новое приглашение, используя приведенный ниже командлет.

New-MgInvitation

Можно использовать следующие параметры.

-InvitedUserDisplayName
-InvitedUserEmailAddress
-SendInvitationMessage
-InvitedUserMessageInfo

Статус приглашения

После отправки приглашения внешнего пользователя можно использовать командлет Get-MgBetaUser , чтобы узнать, приняли ли они его. Следующие свойства Get-MgBetaUser заполняются при отправке приглашения внешним пользователем:

externalUserState указывает, является ли приглашение ожидающей или принятой.
externalUserStateChangeDateTime показывает метку времени последнего изменения в свойстве externalUserState .

Параметр "Фильтр" можно использовать для фильтрации результатов по externalUserState. В приведенном ниже примере показано, как фильтровать результаты, чтобы показывать только тех пользователей, у которых есть ожидающее приглашения. В примере также показан параметр Format-List, который позволяет указывать свойства для отображения.

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

Примечание.

Убедитесь, что у вас установлена последняя версия модуля Microsoft Graph PowerShell

См. также

Ознакомьтесь со справочником по API приглашения по адресу https://developer.microsoft.com/graph/docs/api-reference/v1.0/resources/invitation.

Поделиться через