Skip to main content

SSO Troubleshooting

When SSO fails, Teams sends a signin/failure invoke activity to your bot with a code and message describing the error. The SDK's default handler logs a warning with these details.

Failure codes​

CodeSilentDescription
installappfailedNoFailed to install the app in the user's personal scope (group chat SSO flow).
authrequestfailedNoThe SSO auth request failed after app installation.
installedappnotfoundYesThe bot app is not installed for the user or group chat. (most common)
invokeerrorYesA generic error occurred during the SSO invoke flow.
resourcematchfailedYesThe token exchange resource URI on the OAuthCard does not match the Application ID URI in the Entra app registration's "Expose an API" section. (common)
oauthcardnotvalidYesThe bot's OAuthCard could not be parsed.
tokenmissingYesAAD token acquisition failed.

"Silent" failures produce no user-facing feedback in the Teams client — the user sees nothing and sign-in simply doesn't complete. "Non-silent" failures occur during the group chat SSO flow where the user is shown an install/auth card.

note

The userconsentrequired and interactionrequired codes are handled by the Teams client via the OAuth card fallback flow and do not typically reach the bot.

resourcematchfailed​

If you see a warning in your app logs like:

Sign-in failed for user "..." in conversation "...": resourcematchfailed -- Resource match failed

This means Teams attempted the SSO token exchange but failed because the token exchange resource URI does not match your Entra app registration. To fix this:

  1. Verify "Expose an API" in your Entra app registration: the Application ID URI must be set (typically api://<Your-Application-Id>)
  2. Verify the access_as_user scope is defined under "Expose an API"
  3. Verify pre-authorized client applications include the Teams Desktop (1fec8e78-bce4-4aaf-ab1b-5451cc387264) and Teams Web (5e3ce6c0-2b1f-4285-8d4b-75ee78787346) client IDs
  4. Verify the Token Exchange URL in your Azure Bot OAuth connection matches the Application ID URI exactly
  5. Verify the webApplicationInfo.resource in your Teams app manifest matches the Application ID URI
tip

If you don't need SSO and only want standard OAuth (sign-in button), leave the Token Exchange URL blank in your OAuth connection settings.

To handle signin/failure programmatically in your app, see Handling Sign-In Failures in the User Authentication guide.