Opening external Android app during auth flow in Android WebView in MS Teams

[pwittchen]

Hi,

Can you please tell me, what is the recommended flow and good practices if I want to perform an authentication flow with external Android authenticator app with MS teams? In the custom flow, custom auth website is opening and I want to open authenticator app after clicking on the link on the website on the phone. I know that deep links are probably blocked in the authentication flow in the WebView. Can I use regular links and Android App Links mechanism in Android authenticator app to handle link from the MS Teams Android app? Default Android WebView should handle that, but I don't know how it's implemented in MS Teams Android app. Or the website should use functions from the MS Teams JS library? Is openLink function recommended in that case? Will it open an external browser on the device, therefore Android App Links will be handled? Or will it open inside the WebView? Or should I use pure JS window.open function for opening the link?

My main goal is to open external authenticator app after clicking the link inside the WebView in the MS Teams for Android during the auth flow.

I'm looking forward to your help and recommendations.

Regards,
Piotr

[sayali-MSFT]

Hello @pwittchen ,
Thank you for bringing this issue to our attention. We will look into it and get back to you shortly.

[sayali-MSFT]

Hello @pwittchen ,
Microsoft Teams mobile (Android and iOS) deliberately restricts what can be launched from its embedded authentication WebView for security reasons. Custom URI schemes, intent URLs, and even Android App Links opened inside the WebView are blocked or kept within the WebView, which is why deep links clicked during auth appear to do nothing. Teams does not allow direct WebView → external app escapes.

The only supported and reliable way to exit the WebView and open an external app is by using the Teams JS SDK’s microsoftTeams.openLink(url). This API closes the WebView, opens the system browser, and allows Android App Links to resolve correctly—triggering the authenticator app as intended. Alternatives such as window.open(), custom schemes (myapp://), or intent URLs are blocked or unreliable and are explicitly not recommended.

The Microsoft-recommended architecture is: run the auth page inside the Teams WebView, then on success call openLink() to hand off to an https URL. Teams launches the system browser, Android resolves the App Link to your authenticator app, the app completes authentication, and finally redirects back to Teams via a standard https flow. This pattern—combined with proper Android App Link configuration—is the officially supported, secure, and widely used approach for external authentication apps in Teams.

Reference Document-
1.https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/build-and-test/deep-links-execution-handling?tabs=teamsjs-v2
2.https://github.com/MicrosoftDocs/msteams-docs/blob/main/msteams-platform/tabs/how-to/authentication/auth-oauth-provider.md
3.https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/build-and-test/deep-links
4.https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/build-and-test/deep-link-application?tabs=format1%2Cteamsjs-v2%2Cformat2%2Cspecific%2Cformat3%2Cformat4%2Cformat5

[pwittchen]

Ok, Thank you for an extensive response. Now, it's more clear for me.

I'd like to confirm that I understand proper implementation in my auth flow. I'm attaching MS teams screens in Polish language, but I'll explain everything in English.

Here is the flow:

Step 1 - clicking "Add account" on the left menu (option on the bottom)

Step 2 - providing an email in the company domain

Step 3 - after pressing "Next" (Dalej) on the previous screen, I'm being redirected to the custom auth page within the MS Teams internal WebView

Currently, the button with label "Yes, open Authenticator" is an Android Deep Link with the custom link scheme beyond-identity-endpoint-rolling:///. Clicking on this link does nothing, but I'd like to use it to open an external authenticator app installed on the device.

When I do the following things:

• use microsoftTeams.openLink(url) function for this button instead of regular link (e.g. <a href="..."> or window.open(...))
• use regular link like https://my-domain.com instead of custom link scheme like beyond-identity-endpoint-rolling:///
• handle App Links in my Android app

Then will this link open my custom Authenticator app (e.g. during redirect from the mobile web browser)?

I also have additional questions:

• How should I detect that I'm inside the MS Teams WebView, so I can use microsoftTeams.openLink(url) function? I suppose in regular non-MS apps, I won't be using this function.
• Are there similar restrictions in other MS Apps on Android? E.g. MS Outlook? How should I handle auth flow there? Should I use another MS JS SDK? I see this particular projects is dedicated specifically for MS Teams.

Thank you for your help and I'm looking forward to your reply.

Piotr

[pwittchen]

I performed the following test.

I created the simple html file with the following source code:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Teams Link Opener</title>
    <script src="https://res.cdn.office.net/teams-js/2.0.0/js/MicrosoftTeams.min.js"></script>
    <style>
        #teamsStatus {
            padding: 15px;
            margin: 10px 0;
            border-radius: 5px;
            font-weight: bold;
        }
        #teamsStatus.in-teams {
            background-color: #e6ffe6;
            color: #006600;
            border: 1px solid #00cc00;
        }
        #teamsStatus.not-in-teams {
            background-color: #ffe6e6;
            color: #660000;
            border: 1px solid #cc0000;
        }
    </style>
</head>
<body>
    <div id="teamsStatus">Checking Teams environment...</div>
    <button id="openLinkBtn">Open Example.com</button>

    <script>
        const statusEl = document.getElementById('teamsStatus');
        const openLinkBtn = document.getElementById('openLinkBtn');

        microsoftTeams.app.initialize()
            .then(() => {
                statusEl.textContent = 'You are inside Microsoft Teams!';
                statusEl.className = 'in-teams';
            })
            .catch((error) => {
                statusEl.textContent = 'You are NOT inside Microsoft Teams.';
                statusEl.className = 'not-in-teams';
            });

        openLinkBtn.addEventListener('click', () => {
            microsoftTeams.app.openLink('https://example.com');
        });
    </script>
</body>
</html>

and I opened it inside the WebView during the Auth Flow in the MS Teams Android app.

I've got the message You are NOT inside Microsoft Teams! and clicking on the link did not work (nothing happened).

What am I doing wrong? What can I do to make it work in my case?

I'm looking forward to your reply.

[pwittchen]

I improved my test website in the following way:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Teams Link Opener</title>
    <script src="https://res.cdn.office.net/teams-js/2.28.0/js/MicrosoftTeams.min.js"></script>
    <style>
        #teamsStatus {
            padding: 15px;
            margin: 10px 0;
            border-radius: 5px;
            font-weight: bold;
        }
        #teamsStatus.in-teams {
            background-color: #e6ffe6;
            color: #006600;
            border: 1px solid #00cc00;
        }
        #teamsStatus.not-in-teams {
            background-color: #ffe6e6;
            color: #660000;
            border: 1px solid #cc0000;
        }
        button:disabled {
            opacity: 0.5;
            cursor: not-allowed;
        }
    </style>
</head>
<body>
    <div id="teamsStatus">Checking Teams environment...</div>
    <button id="openLinkBtn">Open Example.com</button>

    <script>
        const statusEl = document.getElementById('teamsStatus');
        const openLinkBtn = document.getElementById('openLinkBtn');
        let isInTeams = false;

        // Disable button until SDK is ready
        openLinkBtn.disabled = true;

        microsoftTeams.app.initialize()
            .then(() => {
                isInTeams = true;
                statusEl.textContent = 'You are inside Microsoft Teams!';
                statusEl.className = 'in-teams';
                openLinkBtn.disabled = false;
            })
            .catch((error) => {
                statusEl.textContent = `Not in Teams: ${error.message || error}`;
                statusEl.className = 'not-in-teams';
                console.error('Teams SDK init failed:', error);
            });

        openLinkBtn.addEventListener('click', () => {
            if (isInTeams) {
                microsoftTeams.app.openLink('https://example.com');
            } else {
                window.open('https://example.com', '_blank');
            }
        });
    </script>
</body>
</html>

and now I see the following error:

so it still does not work. Can you give me any suggestions what can I do to make it work in the right way to open the external authenticator app from the MS Teams WebView in the auth flow or is it completely blocked by the MS Teams Android app?

[pwittchen]

Any updates or suggestions @sayali-MSFT? I will appreciate your help.

[sayali-MSFT]

Hello @pwittchen, Thank you for sharing the details. We will check this and let you know the update.

[sayali-MSFT]

Hello @pwittchen ,
The Microsoft Teams login WebView does not support the Teams JavaScript SDK because it is a secure, isolated environment designed only for authentication. As a result, SDK initialization fails, and Teams-specific APIs (like initialize() or openLink()) cannot be used. This behavior is expected and by design.

Additionally, custom URL schemes and deep links (e.g., myapp://, intent://) are blocked inside the Teams sign-in WebView for security reasons, meaning external apps cannot be launched directly during login. Only standard https:// links are allowed, and these may open either within the WebView or in the system browser.

Because of these platform restrictions, opening external apps directly from the login WebView is not possible. The recommended approach is to redirect users to the system browser via an HTTPS link (e.g., “Continue in browser”), where deep links, App Links, or custom schemes can successfully launch external apps. Providing both browser-based and Teams-based fallback flows is considered best practice.

Teams environment detection during login should rely on User-Agent checks rather than the Teams SDK. Outside the login WebView (such as in tabs or meeting panels), the Teams SDK functions normally. This browser-redirect architecture ensures compatibility across Teams mobile, iOS, Android, Outlook, and regular browsers.