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. また、このコラボレーターの招待について知らせておきたい人を cc することができます。

5. または、Microsoft Entra ID を通じて通知を送信しないことを選択して、招待とオンボード ワークフローを完全にカスタマイズすることができます。

   "sendInvitationMessage": false
   

   この場合は、招待に応じるための URL を API から受け取り、それを電子メール テンプレート、IM、またはその他の任意の配布方法に埋め込むことができます。

6. 最後に、管理者である場合は、ユーザーをメンバーとして招待することを選択できます。

   "invitedUserType": "Member"
   

ユーザーが既にディレクトリに招待されたかどうかを判断する

招待 API を使用して、ユーザーがリソース テナントに既に存在するかどうかを判断できます。 これは、招待 API を使用してユーザーを招待するアプリを開発している場合に便利です。 ユーザーが既にリソース ディレクトリに存在する場合、そのユーザーは招待を受信しないため、まずクエリを実行して、電子メールが UPN またはその他のサインイン プロパティとして既に存在するかどうかを判定できます。

1. ユーザーのメール ドメインが、リソース テナントの確認済みドメインに含まれていないことを確認します。

2. リソース テナントで、次の get ユーザー クエリを使用します。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 は、招待が PendingAcceptance であるか Accepted であるかを示します。
• externalUserStateChangeDateTime は、externalUserState プロパティに対する最新の変更のタイムスタンプを示します。

Filter オプションを使用して、externalUserState で結果をフィルター処理できます。 次の例では、保留中の招待を持っているユーザーのみを表示するように結果をフィルター処理する方法を示しています。 表示するプロパティを指定するための Format-List オプションも示しています。

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

関連項目

招待 API のリファレンスは、https://developer.microsoft.com/graph/docs/api-reference/v1.0/resources/invitation で確認できます。

関連コンテンツ

• Microsoft Entra B2B コラボレーションとは?
• ゲスト ユーザーを追加して招待する
• B2B コラボレーションの招待メールの要素