Add docs for signin/failure handling (#2719)

Add documentation for new feature adding handling for `'signin/failure'`
invoke activities, which previously would fail silently.

**Note**: I have included a special note for Python that points out the
difference between middleware chain behavior & TS/CS: creating the
custom handler does NOT replace the default handler. This means both
handlers will run, and is a quirk of teams.py.

---------

Co-authored-by: Corina Gum <>

Author: corinagum

…n/teams/user-authentication/sso-setup.md …/teams/user-authentication/sso-setup.mdxteams.md/docs/main/teams/user-authentication/sso-setup.md renamed to teams.md/docs/main/teams/user-authentication/sso-setup.mdx teams.md/docs/main/teams/user-authentication/sso-setup.md renamed to teams.md/docs/main/teams/user-authentication/sso-setup.mdx

@@ -80,3 +80,7 @@ The Teams application manifest needs to be updated to reflect the settings confi
   }
 ```
 
+## Troubleshooting
+
+If you encounter SSO errors, see the [Troubleshooting](troubleshooting-sso) guide for common issues and solutions.
+

teams.md/docs/main/teams/user-authentication/troubleshooting-sso.mdx

@@ -0,0 +1,49 @@
+---
+sidebar_position: 2
+title: Troubleshooting
+summary: Common SSO errors and how to resolve them
+---
+
+import LangLink from '@site/src/components/LangLink';
+
+# 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
+
+| Code | Silent | Description |
+|------|--------|-------------|
+| `installappfailed` | No | Failed to install the app in the user's personal scope (group chat SSO flow). |
+| `authrequestfailed` | No | The SSO auth request failed after app installation. |
+| `installedappnotfound` | Yes | The bot app is not installed for the user or group chat. *(most common)* |
+| `invokeerror` | Yes | A generic error occurred during the SSO invoke flow. |
+| `resourcematchfailed` | Yes | The 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)* |
+| `oauthcardnotvalid` | Yes | The bot's OAuthCard could not be parsed. |
+| `tokenmissing` | Yes | AAD 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 <LangLink to="in-depth-guides/user-authentication#handling-sign-in-failures">Handling Sign-In Failures</LangLink> in the User Authentication guide.

teams.md/src/components/include/in-depth-guides/user-authentication/csharp.incl.md

@@ -88,6 +88,17 @@ teams.OnMessage("/signout", async context =>
     await context.Send("you have been signed out!");
 });
 ```
+<!-- signin-failure -->
+
+```cs
+teams.OnSignInFailure(async (context, cancellationToken) =>
+{
+    var failure = context.Activity.Value;
+    Console.WriteLine($"Sign-in failed: {failure?.Code} - {failure?.Message}");
+    await context.Send("Sign-in failed.", cancellationToken);
+});
+```
+
 <!-- regional-bot -->
 
 N/A

teams.md/src/components/include/in-depth-guides/user-authentication/python.incl.md

@@ -86,6 +86,20 @@ async def handle_signout_message(ctx: ActivityContext[MessageActivity]):
     await ctx.send("You have been signed out!")
 ```
 
+<!-- signin-failure -->
+
+```python
+@app.on_signin_failure()
+async def handle_signin_failure(ctx):
+    failure = ctx.activity.value
+    print(f"Sign-in failed: {failure.code} - {failure.message}")
+    await ctx.send("Sign-in failed.")
+```
+
+:::note
+In Python, registering a custom handler does **not** replace the built-in default handler. Both will run as part of the middleware chain.
+:::
+
 <!-- regional-bot -->
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';

teams.md/src/components/include/in-depth-guides/user-authentication/typescript.incl.md

@@ -81,6 +81,16 @@ app.message('/signout', async ({ send, signout, isSignedIn }) => {
 });
 ```
 
+<!-- signin-failure -->
+
+```ts
+app.on('signin.failure', async ({ activity, send }) => {
+  const { code, message } = activity.value;
+  console.log(`Sign-in failed: ${code} - ${message}`);
+  await send('Sign-in failed.');
+});
+```
+
 <!-- regional-bot -->
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';

teams.md/src/pages/templates/in-depth-guides/user-authentication.mdx

@@ -96,6 +96,16 @@ You can signout by calling the `signout` method, this will remove the token from
 
 <LanguageInclude section="signing-out" />
 
+## Handling Sign-In Failures
+
+When using SSO, if the token exchange fails Teams sends a `signin/failure` invoke activity to your app. The SDK includes a built-in default handler that logs a warning with actionable troubleshooting guidance. You can optionally register your own handler to customize the behavior:
+
+<LanguageInclude section="signin-failure" />
+
+:::tip
+The most common failure codes are `installedappnotfound` (bot app not installed for the user) and `resourcematchfailed` (Token Exchange URL doesn't match the Application ID URI). See [SSO Setup - Troubleshooting](/teams/user-authentication/sso-setup#troubleshooting-sso) for a full list of failure codes and troubleshooting steps.
+:::
+
 <LanguageInclude section="regional-bot" />
 
 ## Resources

teams.md/src/pages/templates/migrations/slack-bolt.mdx

@@ -75,7 +75,7 @@ There are two primary types of user authentication for Teams and Slack: authenti
 
 In Slack, if you want to use Slack REST APIs that require user-delegated scopes, you need to implement an OAuth 2.0 installation flow in your application to obtain and store Slack user tokens, even if the app was already installed by another user. In Teams, you can leverage Teams SSO to obtain user Entra tokens for calling Graph REST APIs. The Teams SDK integrates with Teams SSO and Azure Bot Token Service to handle token acquisition, storage, and refresh automatically for you.
 
-First, follow the instructions in the [Teams SSO guide](../../../../docs/main/teams/user-authentication/sso-setup.md).
+First, follow the instructions in the [Teams SSO guide](../../../../docs/main/teams/user-authentication/sso-setup.mdx).
 
 Then, configure the authentication in your code.