Microsoft Entra B2B コラボレーションの API とカスタマイズ
Microsoft Graph REST API を使うと、組織に最適な方法で招待プロセスをカスタマイズできます。
招待 API の機能
API には次の機能が用意されています。
"任意の" 電子メール アドレスで外部ユーザーを招待できます。
"invitedUserDisplayName": "Taylor" "invitedUserEmailAddress": "taylor@fabrikam.com"招待に応じたユーザーの移動先をカスタマイズできます。
"inviteRedirectUrl": "https://myapps.microsoft.com/"標準的な招待メールを Microsoft 経由で送信することを選択できます。
"sendInvitationMessage": trueカスタマイズできる受信者へのメッセージを添付できます。
"customizedMessageBody": "Hello Sam, let's collaborate!"また、このコラボレーターの招待について知らせておきたい人を cc することができます。
または、Microsoft Entra ID を通じて通知を送信しないことを選択して、招待とオンボード ワークフローを完全にカスタマイズすることができます。
"sendInvitationMessage": falseこの場合は、招待に応じるための URL を API から受け取り、それを電子メール テンプレート、IM、またはその他の任意の配布方法に埋め込むことができます。
最後に、管理者である場合は、ユーザーをメンバーとして招待することを選択できます。
"invitedUserType": "Member"
ユーザーが既にディレクトリに招待されたかどうかを判断する
招待 API を使用して、ユーザーがリソース テナントに既に存在するかどうかを判断できます。 これは、招待 API を使用してユーザーを招待するアプリを開発している場合に便利です。 ユーザーが既にリソース ディレクトリに存在する場合、そのユーザーは招待を受信しないため、まずクエリを実行して、電子メールが UPN またはその他のサインイン プロパティとして既に存在するかどうかを判定できます。
ユーザーのメール ドメインが、リソース テナントの確認済みドメインに含まれていないことを確認します。
リソース テナントで、次のユーザーの取得クエリを使用します。ここで、{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
Note
必ず最新バージョンの Microsoft Graph PowerShell モジュールを使ってください。
関連項目
招待 API のリファレンスは、https://developer.microsoft.com/graph/docs/api-reference/v1.0/resources/invitation で確認できます。