使用 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 应用程序集成的屏幕截图。

  1. 最终用户在 LOB 应用程序中触发“邀请”,并提供外部用户的电子邮件地址。 应用程序检查用户是否已存在,如果不存在,则继续执行创建并发送邀请|
  2. 应用程序代表用户向 Microsoft Graph API 发送 POST。 应用程序会提供确认外部用户在目录中中定义的重定向 URL 和外部用户的电子邮件。
  3. Microsoft Graph API 在 Microsoft Entra ID 中预配来宾用户。
  4. Microsoft Graph API 返回 API 调用的成功或失败状态。 如果成功,响应将包括 Microsoft Entra 用户对象 ID 和发送给受邀用户的电子邮件的邀请链接。 你可以禁用 Microsoft 电子邮件并发送自定义电子邮件。
  5. (可选)向受邀用户写入更多属性,或将受邀用户添加到组。 应用程序对 Microsoft Graph API 进行了额外的 API 调用。
  6. (可选)Microsoft Graph API 会更新 Microsoft Entra ID。
  7. (可选)Microsoft Graph API 将成功或失败状态返回给应用程序。
  8. 应用程序通过将用户的对象 ID 属性用作“不可变 ID”,将用户预配到应用程序的数据库/后端用户目录。
  9. 应用程序向最终用户显示成功或失败状态。

如果需要分配才能访问 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 应用程序能够更新外部用户,而无需授予其更新目录中用户的权限。