Bot token framework showing 6-digit magic code flow

Question

Bot token framework showing 6-digit magic code flow

Kuldeep Ravaliya 0 Microsoft Employee

We're using a Bot Framework OAuth Connection with a Generic OAuth2 provider (LinkedIn). We generate the sign-in resource using UserTokenClient.getSignInResource() and launch it through the documented Teams msteams: { type: "signin" } mechanism. Authentication succeeds, but the Token Service is now consistently falling back to the 6-digit magic-code flow. What exact condition causes Token Service to choose magic-code verification instead of automatically completing the token exchange, and is there any supported way to force automatic token exchange?

0 comments

4 answers

Your answer

Answer 1

The six-digit code is an expected security fallback when Bot Framework Token Service cannot correlate the completed authentication with the Teams conversation user. There is no supported option to force automatic completion in that condition.

LinkedIn Generic OAuth requires interactive authentication and doesn’t support Teams/Entra silent SSO token exchange. However, the documentation doesn’t establish that Generic OAuth or an intermediate 302 must always produce a magic code.

Please use a native OAuthCard with a fresh getSignInResource() URL, ensure token.botframework.com is in validDomains, and test from a Teams personal chat using the same browser/session. The sign-in URL’s exact lifetime isn’t publicly documented or configurable, so create it when the user clicks rather than expecting it to remain valid for days.

If native OAuthCard previously completed automatically under identical conditions but now consistently shows a code, provide timestamps, tenant/bot/conversation/user IDs, Teams client version, and a network trace, then open a Microsoft support case to confirm whether Token Service behavior changed.

Answer 2

BabybooHN 2,210 Independent Advisor

Dear @Kuldeep Ravaliya

I understand you are looking to clarify why the Bot Framework Token Service defaults to the 6-digit magic code flow during LinkedIn OAuth authentication in Microsoft Teams, and whether automatic token exchange can be forced.

Question: Why Token Service Falls Back to the 6-Digit Magic Code

The 6-digit magic code is a fallback security mechanism used by the Bot Framework Token Service to prevent token hijacking. It occurs whenever the Token Service cannot securely verify that the user who completed the browser login is the same user active in the Teams chat session.

In your setup, this occurs due to three specific conditions:

Provider Limitations (Generic OAuth2 vs. Entra ID): Automatic background token exchange (silent SSO via signin/tokenExchange) is natively supported only for Microsoft Entra ID (Azure AD v2). Third-party Generic OAuth2 providers (such as LinkedIn) require an explicit interactive login and consent dialog.
Custom Sign-in Launch via getSignInResource(): Generating a raw URL via getSignInResource() and opening it through a generic link action bypasses the built-in Teams authentication callback. Because the popup window cannot communicate its success callback back to the Teams client context, the Token Service renders the 6-digit code as a security gate.
Missing Popup Close Callback: If the OAuth completion redirect does not trigger microsoftTeams.authentication.notifySuccess(), Teams cannot capture the authorization state directly, forcing the manual code entry page.

Question: Can You Force Automatic Token Exchange?

Silent SSO: No. You cannot perform silent, zero-click token exchange for 3rd-party OAuth2 providers like LinkedIn because the OAuth protocol requires external identity provider consent.
Eliminating the 6-Digit Code: No. There is no supported way to force the automatic path when the identity/conversation correlation fails. Silent SSO is only fully supported for Microsoft Entra ID.

Please let me know if you need further assistance.

Kuldeep Ravaliya 0 Reputation points Microsoft Employee

2026-08-13T17:41:10.51+00:00
Thanks, that's helpful. To make sure I'm not misreading point 2, here's exactly what we do today:

We send an Adaptive Card whose button is Action.Submit , pointing at our own /login endpoint. (hosted on our webapp domain)

/login calls getSignInResource() to mint a fresh link, and 302-redirects the popup to the returned signInLink on token.botframework.com . (We redirect to /login so we can create a new login link on each click and the login link doesn't expire)

The user signs in to LinkedIn, lands back on the Token Service page, and sees the 6-digit code.

Questions:

Is that 302 hop through our own domain what breaks the built-in Teams callback? We also tried sending a native OAuthCard (SDK CardFactory.oauthCard ) with no /login hop, and still got the 6-digit code; Is that expected, or does that indicate a misconfiguration?

What is the lifetime of the signInLink returned by getSignInResource() ? Is it documented or configurable? Basically we want the link to not expire so even if the user clicks on it days after it is send it should allow them to sign in.
Kuldeep Ravaliya 0 Reputation points Microsoft Employee

2026-08-13T18:00:46.06+00:00
@BabybooHN Thanks, that's helpful. To make sure I'm not misreading point 2, here's exactly what we do today:

We send an Adaptive Card whose button is Action.Submit , pointing at our own /login endpoint. (hosted on our webapp domain)

/login calls getSignInResource() to mint a fresh link, and 302-redirects the popup to the returned signInLink on token.botframework.com . (We redirect to /login so we can create a new login link on each click and the login link doesn't expire)

The user signs in to LinkedIn, lands back on the Token Service page, and sees the 6-digit code.

Questions:

Is that 302 hop through our own domain what breaks the built-in Teams callback? We also tried sending a native OAuthCard (SDK CardFactory.oauthCard ) with no /login hop, and still got the 6-digit code; Is that expected, or does that indicate a misconfiguration?

What is the lifetime of the signInLink returned by getSignInResource() ? Is it documented or configurable? Basically we want the link to work even if the users click on it after several days.
BabybooHN 2,210 Reputation points Independent Advisor

2026-08-14T02:31:26.93+00:00
Dear @Kuldeep Ravaliya

Here are direct answers to your two specific follow-up questions:

Question 1: Does the 302 hop break the callback, and is getting a magic code with native OAuthCard expected?

Is the 302 redirect breaking the callback?

Yes. When you route through your custom /login endpoint via Action.Submit, the popup window opens under your domain context instead of Teams' native authentication container. Teams relies on window messaging/callbacks tied specifically to the sign-in URL emitted by the Token Service. Redirecting through a intermediate custom endpoint prevents Teams from establishing the direct parent-child window postMessage bridge, which causes Teams to lose the verifyState hook and fall back to the 6-digit magic code.

Why did native OAuthCard (CardFactory.oauthCard) still produce a magic code?

This is expected behavior for third-party OAuth2 providers like LinkedIn.

Teams automatic popup closure / token handling (signin/verifyState) requires the identity provider or web flow to execute microsoftTeams.authentication.notifySuccess().

Because external providers (like LinkedIn) redirect back to token.botframework.com upon completion, the Token Service renders its standard completion page. For non-Entra ID generic OAuth2 connections, the Token Service defaults to displaying the 6-digit magic code unless a custom consent/popup page is hosted that triggers the Teams JS SDK callback.

Question 2: What is the lifetime of signInLink from getSignInResource()? Is it configurable?

Default Lifetime:

The signInLink URL generated by getSignInResource() is embedded with a short-lived state token generated by the Bot Framework Token Service. By default, this link is valid for 15 minutes.

Is it configurable?

No. The expiration window is hardcoded within the Azure Bot Framework Token Service security architecture and cannot be extended or configured in bot settings.

Why links shouldn't last for days:

The sign-in link is cryptographically tied to a specific ConversationID and UserID state at the moment of request. Allowing long-lived sign-in links creates security vulnerabilities (such as session replay or unauthorized access if a link is shared/intercepted later).

Please let me know if you need any additional clarification on setting up the OAuth dialog flow

Answer 3

Kuldeep Ravaliya 0 Microsoft Employee

what do you mean by identities should match, do you mean to say the credentials should be the same?

BabybooHN 2,210 Reputation points Independent Advisor

2026-08-13T16:56:24.93+00:00

Dear @Kuldeep Ravaliya

No, it does not mean the login credentials have to be identical.

Identity matching is the Token Service checking that the LinkedIn login belongs to the exact same Teams user who started the process in that specific conversation. If it can’t confirm that, it forces the safer 6-digit code.

Answer 4

The 6-digit magic-code flow is triggered when the identity that authenticates in the popup does not match the Teams conversation user. In that case, the Token Service can’t match the redirect state back to the pending OAuth session, so Teams falls back to magic-code verification.

This is expected behavior, not a bug.

Automatic completion happens only when the client can correlate the sign-in back to the same conversation and user context. If that correlation succeeds, Teams sends a signin/verifyState invoke and the SDK can exchange the code for a token without showing the user a magic code in the normal fallback flow.

There is no supported way in the provided documentation to force automatic token exchange when that identity correlation cannot be made. The supported approach is to ensure the authenticating identity matches the Teams session user. The documentation also notes that some channels can complete sign-in without the user noticing, but when the sign-in URL can’t be securely tied back to the same conversation/user, Bot Framework uses the 6-digit code as a security measure.

Also, if SSO token exchange succeeds with a TokenExchangeInvokeResponse status of 200, the client doesn’t show the OAuth card. For any other status, or if no TokenExchangeInvokeResponse is received, the client shows the OAuth card fallback.

Security note: the sign-in URL is tied to a specific conversation ID and user ID and should not be shared.