Microsoft Entra ID
Authentication

Tutorial Native Authentication Ios Macos Support Web Fallback

In brief

The tutorial explaining BrowserRequired handling and browser-based token acquisition for native authentication on iOS and macOS was deleted.

What Entra admins need to know

Administrators supporting these integrations can no longer use this tutorial at the documented URL. No administrator action is specified.

This editorial summary was generated by AI from the documentation changes. Verify important details in the full Microsoft Learn article.

Documentation change

The comparison below shows only the changed extract. Use the full-page view for complete context.

deleted file mode 100644

title: Support web fallback description: Learn how to implement web fallback in an iOS/macOS application by using native authentication to ensure stability in authentication flow.

manager: pmwongera

ms.service: identity-platform

ms.subservice: external ms.topic: tutorial ms.date: 09/02/2024 ms.custom: #Customer intent: As a developer, I want to support web fallback in my iOS/macOS app's native authentication flow so that I can ensure stability of my app's authentication flow.

Tutorial: Support web fallback

[!INCLUDE applies-to-external-only]

This tutorial demonstrates how to acquire a token through a browser where native authentication isn't sufficient to complete the user flow.

In this tutorial, you:

[!div class="checklist"]

  • Check BrowserRequired error.
  • Handle BrowserRequired error.

Prerequisites

Browser required

BrowserRequired is a fallback mechanism for various scenarios where native authentication isn't sufficient to complete the user flow.

To ensure stability of your application and avoid interruption of the authentication flow, it's highly recommended to use the SDK's acquireToken() method to continue the flow in the browser.

When we initialize the SDK, we need to specify which challenge types our application can support. Here are the list of challenge types that the SDK accepts:

  • OOB (out of band): add this challenge type when your iOS/macOS application can handle a one-time-passcode, in this case an email code.
  • Password: add this challenge type when your application is able to handle password based authentication.

When Microsoft Entra requires capabilities that the client can't provide the BrowserRequired error will be returned. For example, suppose we initialize the SDK instance specifying only the challenge type OOB, but in Microsoft Entra admin center, the application is configured with an Email with password user flow. When we call the signUp(username) method from the SDK instance, we get a BrowserRequired error, because Microsoft Entra requires different challenge type (password in this case) than the one configured in the SDK.

Insufficient challenge type is only one example of when BrowserRequired can occur. BrowserRequired is a general fallback mechanism that can happen in various scenarios.

Sample flow

In the following code snippet you can see how you can specify the challenge types during the SDK instance initialization:

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

In this case we're specifying only the challenge type OOB. Suppose that in the Microsoft Entra admin center, the application is configured with an Email with password user flow.

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

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

When we call the signUp(parameters:delegate) method from the SDK instance, we get a BrowserRequired error, because Microsoft Entra requires a different challenge type (password in this case) than the one configured in the SDK.

Handle BrowserRequired error

To handle this kind of error, we need to launch a browser and let the user perform the authentication flow there. This can be done by calling acquireToken() method. In order to use this method, a few additional configurations need to be done:

Now we can get a token and an account interactively. Here's an example of how to do it:

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
        }
    }
}

The tokens and account that are returned are identical to the ones that would be retrieved through a native auth flow.

Related content

Daily Entra.News

Get daily email updates

Get a concise summary of the latest Microsoft Entra updates delivered straight to your inbox.

Loading the secure signup form…