Microsoft Entra B2B 협업 API 및 사용자 지정

적용 대상: 인력 테넌트 외부 테넌트(자세히 알아보기)

Microsoft Graph REST API를 사용하면 조직에 가장 적합한 방식으로 초대 프로세스를 사용자 지정할 수 있습니다.

초대 API의 기능

이 API는 다음과 같은 기능을 제공합니다.

1. 다음 JSON 표현은 모든 전자 메일 주소가 있는 외부 사용자를 초대하는 방법을 설명합니다.

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

2. 초대를 수락한 후에 사용자가 리디렉션되려는 위치를 사용자 지정합니다.

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

3. Microsoft를 통해 표준 초대 메일을 발송하려면 이 항목을 선택합니다.

   "sendInvitationMessage": true
   

   받는 사람에게 사용자 지정할 수 있는 메시지를 보냅니다.

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

4. 또한 이 공동 작업자 초대에 대한 정보를 계속 알리려는 사람을 참조:에 추가하도록 선택합니다.

5. 또는 Microsoft Entra ID를 통해 알림을 보내지 않도록 선택하여 초대 및 온보딩 워크플로를 완전히 사용자 지정합니다.

   "sendInvitationMessage": false
   

   이 경우 전자 메일 템플릿, IM 또는 선택한 기타 배포 방법에 포함할 수 있는 API에서 상환 URL을 다시 얻을 수 있습니다.

6. 마지막으로 관리자는 사용자를 구성원으로 초대하도록 선택할 수 있습니다.

   "invitedUserType": "Member"
   

사용자가 디렉터리에 이미 초대되었는지 확인

초대 API를 사용하여 사용자가 리소스 테넌트에 이미 존재하는지 확인할 수 있습니다. 이는 초대 API를 사용하여 사용자를 초대하는 앱을 개발하는 경우에 유용할 수 있습니다. 리소스 디렉터리에 이미 존재하는 사용자는 초대를 받지 않으므로 먼저 쿼리를 실행하여 이미 이메일이 UPN이나 다른 로그인 속성으로 존재하는지 확인할 수 있습니다.

1. 사용자의 이메일 도메인이 리소스 테넌트의 확인된 도메인에 속해 있지 않은지 확인하세요.

2. 리소스 테넌트에서 다음 사용자 가져오기 쿼리를 사용합니다. 여기서 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을 사용하여 외부 사용자를 조직에 쉽게 추가하고 초대할 수 있습니다. cmdlet을 사용하여 초대 만들기

New-MgInvitation

사용할 수 있는 옵션은 다음과 같습니다.

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

초대 상태

외부 사용자에게 초대를 보낸 후 Get-MgBetaUser cmdlet을 사용하여 해당 사용자가 초대를 수락했는지 확인할 수 있습니다. 외부 사용자에게 초대가 전송되면 Get-MgBetaUser의 다음 속성이 채워집니다.

• externalUserState는 초대가 PendingAcceptance 또는 Accepted인지 여부를 나타냅니다.
• externalUserStateChangeDateTime은 externalUserState 속성의 최신 변경 내용에 대한 타임스탬프를 표시합니다.

필터 옵션을 사용하면 externalUserState별로 결과를 필터링할 수 있습니다. 아래 예제에서는 보류 중인 초대를 보유한 사용자만 표시하도록 결과를 필터링하는 방법을 보여 줍니다. 이 예제에서는 표시할 속성을 지정할 수 있는 Format-List 옵션도 보여 줍니다.

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

참고 항목

https://developer.microsoft.com/graph/docs/api-reference/v1.0/resources/invitation에서 초대 API 참조를 확인하세요.

관련 콘텐츠

• Microsoft Entra B2B 협업이란?
• 게스트 사용자 추가 및 초대
• B2B 협업 초대 이메일의 요소