使用 Microsoft Entra B2B 将外部用户加入业务线应用程序
应用程序开发人员可以使用 Microsoft Entra B2B 在业务线 (LOB) 应用程序中加入外部用户并与之协作。 应用程序开发人员可以在集成 Microsoft Entra ID 的任意 LOB 应用程序中创建一键式邀请体验,类似于许多 Office 365 应用程序中的“共享”按钮。
优势包括:
- 用户登录和访问 LOB 应用程序。 用户只需几个步骤即可访问
- 支持外部用户自带标识并执行单一登录 (SSO)
- 向 Microsoft Entra ID 预配外部身份
- 应用 Microsoft Entra 条件访问和跨租户访问策略来强制实施授权策略,例如多重身份验证
集成流
若要将 LOB 应用程序与 Microsoft Entra B2B 集成,请遵循以下模式:
- 最终用户在 LOB 应用程序中触发“邀请”,并提供外部用户的电子邮件地址。 应用程序检查用户是否已存在,如果不存在,则继续执行创建并发送邀请|
- 应用程序代表用户向 Microsoft Graph API 发送 POST。 应用程序会提供确认外部用户在目录中中定义的重定向 URL 和外部用户的电子邮件。
- Microsoft Graph API 在 Microsoft Entra ID 中预配来宾用户。
- Microsoft Graph API 返回 API 调用的成功或失败状态。 如果成功,响应将包括 Microsoft Entra 用户对象 ID 和发送给受邀用户的电子邮件的邀请链接。 你可以禁用 Microsoft 电子邮件并发送自定义电子邮件。
- (可选)向受邀用户写入更多属性,或将受邀用户添加到组。 应用程序对 Microsoft Graph API 进行了额外的 API 调用。
- (可选)Microsoft Graph API 会更新 Microsoft Entra ID。
- (可选)Microsoft Graph API 将成功或失败状态返回给应用程序。
- 应用程序通过将用户的对象 ID 属性用作“不可变 ID”,将用户预配到应用程序的数据库/后端用户目录。
- 应用程序向最终用户显示成功或失败状态。
如果需要分配才能访问 LOB 应用程序,则要将受邀的来宾用户分配到具有相应应用程序角色的应用程序。 启用此操作作为另一个 API 调用,将受邀的来宾添加到组,或使用 Microsoft Entra 动态成员资格组来自动管理成员资格。 动态成员资格组不需要应用程序进行另一次 API 调用;但是,它们的更新速度与通过用户邀请将用户添加到组中一样快。
确认外部用户位于目录中
外部用户可能已被邀请并已加入。 LOB 应用程序检查用户是否在目录中。 调用 Microsoft Graph API 并向发出邀请的用户显示匹配项,供他们选择。
例如:
Application Permission: User.read.all
GET https://microsoftgraph.chinacloudapi.cn/v1.0/users?$filter=othermails/any(id:id eq 'userEmail@contoso.com')
如果在响应中收到用户详细信息,则用户位于目录中。 向发出邀请的用户显示返回的用户。 允许用户选择获取访问权限的外部用户。 若要授予用户对应用程序的访问权限,请执行 API 调用或触发其他进程。
创建并发送邀请
如果外部用户不在目录中,请使用 Microsoft Entra B2B 邀请用户并将其加入到 Microsoft Entra 租户。 确定在向 Microsoft Graph API 发出的邀请请求中包含哪些内容。
使用以下元素:
- 提示最终用户提供外部用户的电子邮件地址
- 确定邀请 URL,系统会在受邀用户验证身份并兑换 B2B 邀请后将其重定向到这个 URL
- URL 可以是通用登陆页,也可以由 LOB 应用程序根据最终用户触发邀请的位置动态来确定
邀请请求的更多标志和属性:
- 受邀用户显示名称
- 默认 Microsoft 邀请电子邮件,或禁用默认电子邮件以创建自己的电子邮件
应用程序收集所需信息后,应用程序必须使用 POST 将请求发布到 Microsoft Graph API 邀请管理器。 确保应用程序注册在 Microsoft Entra ID 中具有权限。
例如:
Delegated Permission: User.Invite.All
POST https://microsoftgraph.chinacloudapi.cn/v1.0/invitations
Content-type: application/json
{
"invitedUserDisplayName": "John Doe",
"invitedUserEmailAddress": "john.doe@contoso.com",
"sendInvitationMessage": true,
"inviteRedirectUrl": "https://customapp.contoso.com"
}
注意
若要查看邀请 JSON 正文的选项,请参阅 Microsoft Graph v1.0 中的邀请资源类型。
应用程序开发人员可以使用 Microsoft Entra 自助注册或权利管理访问包加入外部用户。 在 LOB 应用程序中创建一个邀请按钮,该按钮会触发带有自助注册 URL 或访问包 URL 的自定义电子邮件。 受邀用户加入并访问应用程序。
(可选)将其他属性写入 Microsoft Entra ID
重要
授予应用程序更新目录中用户的权限是一项高特权操作。 如果向应用程序授予这些高特权权限,则应保护和监视 LOB 应用。
组织或 LOB 应用程序可能需要存储更多信息以备将来使用,例如令牌中的声明发出或精细授权策略。 在 Microsoft Entra ID 中邀请或创建外部用户时,应用程序可以执行另一个 API 调用来更新这些用户。 应用程序必须具有额外的 API 权限,并且需要额外调用 Microsoft Graph API。
若要更新用户,请使用从邀请 API 调用中创建的来宾用户的对象 ID、来自存在检查或邀请的 API 响应中的 ID 值。 可以写入任何标准属性或自定义扩展属性。
例如:
Application Permission: User.ReadWrite.All
PATCH https://microsoftgraph.chinacloudapi.cn/v1.0/users/<user's object ID>
Content-type: application/json
{
"businessPhones": [
"+1 234 567 8900"
],
"givenName": "John"
"surname": "Doe",
"extension_cf4ff515cbf947218d468c96f9dc9021_appRole": "external"
}
有关详细信息,请参阅 Microsoft Graph v1.0 中的更新用户。
(可选)将受邀用户分配到组
注意
如果不需要用户分配即可访问应用程序,则可以跳过此步骤。
如果在 Microsoft Entra ID 中,需要针对应用程序访问全县或角色分配来分配用户,则将用户分配给该应用程序。 否则,无论身份验证结果如何,用户都无法访问。 若要将受邀的外部用户添加到组,请执行另一个 API 调用。 将组分配给应用程序并映射到应用程序角色。
权限示例:将组更新者角色或自定义角色分配给企业应用程序。 将角色分配范围设定为此应用程序更新的组。 或者在 Microsoft Graph API 中分配 group.readwrite.all
权限。
POST https://microsoftgraph.chinacloudapi.cn/v1.0/groups/<insert group id>/members/$ref
Content-type: application/json
{
"@odata.id": "https://microsoftgraph.chinacloudapi.cn/v1.0/directoryObjects/<insert user id>"
}
有关详细信息,请参阅Microsoft Graph v1.0 中的添加成员。
或者,可以使用 Microsoft Entra 动态成员资格组,根据特定属性(例如 userType、电子邮件或自定义属性)自动分配用户。 但是,如果用户访问权限具有时效性,则不建议使用此方法,因为动态成员资格组可能需要最长 24 小时才能填充。
如果使用动态成员资格组,请不要使用另一个 API 调用将用户添加到组中。 相反,创建一个组,根据属性(如 userType、电子邮件或自定义属性)将用户添加为组成员。 有关详细信息,请参阅创建或编辑动态组并获取状态。
将受邀用户预配到应用程序
在 Microsoft Entra ID 中配置受邀的外部用户后,Microsoft Graph API 将返回包含用户信息(例如对象 ID 和电子邮件)的响应。 LOB 应用程序会将用户预配到自己的目录或数据库。 预配会有所不同,具体取决于应用程序及其所使用的内部目录类型。
在 Microsoft Entra ID 和应用程序中预配外部用户后,LOB 应用程序会通知发起请求的用户该过程已成功。 受邀用户使用标识获取 SSO,而无需邀请组织加入并颁发额外的凭据。 Microsoft Entra ID 会通过条件访问和 Microsoft Entra ID 多重身份验证强制实施授权策略。
其他注意事项
确保在 LOB 应用程序中完成错误处理。 应用程序会验证每个 API 调用。 如果失败,则额外的尝试或错误消息非常有用。
为了使 LOB 应用程序更新受邀的外部用户,请授予自定义角色,允许应用程序更新用户并将范围分配给动态管理单元。 例如,创建动态管理单元,包含 usertype = guest 的所有用户。 当外部用户加入 Microsoft Entra ID 时,系统会将他们添加到管理单元。 LOB 应用程序需要尝试更新用户,如果出现延迟,则可能需要多次尝试。 尽管存在延迟,但该方法使 LOB 应用程序能够更新外部用户,而无需授予其更新目录中用户的权限。