教程:支持 Web 回退

适用于:带灰色 X 号的白色圆圈。 员工租户 带白色对号的绿色圆圈。 外部租户(了解详细信息

本教程演示在本机身份验证不足以完成用户流时,如何通过浏览器获取令牌。

在本教程中,你将:

  • 检查 BrowserRequired 错误。
  • 处理 BrowserRequired 错误。

先决条件

需要浏览器

BrowserRequired 是在多种场景下,当本机身份验证不够充分以完成用户流程时采用的备用机制。

为了确保应用程序的稳定性并避免身份验证流程的中断,强烈建议使用 SDKacquireToken()的方法在浏览器中继续执行流程。

初始化 SDK 时,需要指定应用程序可以支持的挑战类型。 下面是 SDK 接受的质询类型列表:

  • OOB(带外):当 iOS/macOS 应用程序可以处理一次性密码(本例中为电子邮件代码)时,添加此质询类型。
  • 密码:当应用程序能够处理基于密码的身份验证时,请添加此认证类型。

当 Microsoft Entra 要求客户端无法提供的功能时,系统将返回错误BrowserRequired。 例如,假设我们初始化的 SDK 实例仅指定质询类型 OOB,但在 Microsoft Entra 管理中心,该应用程序配置了使用电子邮件及密码的用户流。 从 SDK 实例调用 signUp(username) 方法时,我们会收到BrowserRequired错误,因为 Microsoft Entra 需要的质询类型(在本例中为密码)与配置到 SDK 的类型不符。

质询类型不足只是可能出现 BrowserRequired 情况的一个示例。 BrowserRequired是一种可在各种情况下发生的常规回退机制。

示例流

在以下代码片段中,可以看到如何在 SDK 实例初始化期间指定质询类型:

nativeAuth = try MSALNativeAuthPublicClientApplication(
    clientId: "<client id>",
    tenantSubdomain: "<tenant subdomain>",
    challengeTypes: [.OOB]
)

在这个案例中,我们仅指定挑战类型 OOB。 假设在 Microsoft Entra 管理中心内,应用程序配置了使用电子邮件及密码的用户流。

let parameters = MSALNativeAuthSignUpParameters(username: email)
nativeAuth.signUp(parameters: parameters, delegate: self)

func onSignUpStartError(error: MSAL.SignUpStartError) {
    if error.isBrowserRequired {
        // handle browser required error
    }
}

从 SDK 实例调用signUp(parameters:delegate)方法时,我们会遇到BrowserRequired错误,因为 Microsoft Entra 需要一种不同的挑战类型(本例中为密码),而不是 SDK 中配置的类型。

处理 BrowserRequired 错误

若要处理此类错误,我们需要启动浏览器,让用户在浏览器执行身份验证流程。 这可以通过调用acquireToken()方法来完成。 若要使用此方法,需要完成一些其他配置:

现在,我们可以以交互方式获取令牌和帐户。 以下示例演示如何执行此操作:

func onSignUpStartError(error: MSAL.SignUpStartError) {
    if error.isBrowserRequired {
        let webviewParams = MSALWebviewParameters(authPresentationViewController: self)
        let parameters = MSALInteractiveTokenParameters(scopes: ["User.Read"], webviewParameters: webviewParams)

        nativeAuth.acquireToken(with: parameters) { (result: MSALResult?, error: Error?) in
            // result will contain account and tokens retrieved in the browser
        }
    }
}

返回的令牌和帐户与通过本机身份验证流检索的令牌和帐户相同。