diff --git a/teams.md/docs/main/teams/user-authentication/sso-setup.md b/teams.md/docs/main/teams/user-authentication/sso-setup.mdx similarity index 96% rename from teams.md/docs/main/teams/user-authentication/sso-setup.md rename to teams.md/docs/main/teams/user-authentication/sso-setup.mdx index 9e40f804b5..d7872a8e57 100644 --- a/teams.md/docs/main/teams/user-authentication/sso-setup.md +++ b/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. + diff --git a/teams.md/docs/main/teams/user-authentication/troubleshooting-sso.mdx b/teams.md/docs/main/teams/user-authentication/troubleshooting-sso.mdx new file mode 100644 index 0000000000..920898e707 --- /dev/null +++ b/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://`) +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. diff --git a/teams.md/src/components/include/in-depth-guides/user-authentication/csharp.incl.md b/teams.md/src/components/include/in-depth-guides/user-authentication/csharp.incl.md index 1222be1cf3..05e62f5b75 100644 --- a/teams.md/src/components/include/in-depth-guides/user-authentication/csharp.incl.md +++ b/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!"); }); ``` + + +```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); +}); +``` + N/A \ No newline at end of file diff --git a/teams.md/src/components/include/in-depth-guides/user-authentication/python.incl.md b/teams.md/src/components/include/in-depth-guides/user-authentication/python.incl.md index c1fecee3ae..d1c51f6e3e 100644 --- a/teams.md/src/components/include/in-depth-guides/user-authentication/python.incl.md +++ b/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!") ``` + + +```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. +::: + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; diff --git a/teams.md/src/components/include/in-depth-guides/user-authentication/typescript.incl.md b/teams.md/src/components/include/in-depth-guides/user-authentication/typescript.incl.md index 2df8cf15f8..b26b8a40e9 100644 --- a/teams.md/src/components/include/in-depth-guides/user-authentication/typescript.incl.md +++ b/teams.md/src/components/include/in-depth-guides/user-authentication/typescript.incl.md @@ -81,6 +81,16 @@ app.message('/signout', async ({ send, signout, isSignedIn }) => { }); ``` + + +```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.'); +}); +``` + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; diff --git a/teams.md/src/pages/templates/in-depth-guides/user-authentication.mdx b/teams.md/src/pages/templates/in-depth-guides/user-authentication.mdx index d1bb92a949..876abb8353 100644 --- a/teams.md/src/pages/templates/in-depth-guides/user-authentication.mdx +++ b/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 +## 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: + + + +:::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. +::: + ## Resources diff --git a/teams.md/src/pages/templates/migrations/slack-bolt.mdx b/teams.md/src/pages/templates/migrations/slack-bolt.mdx index 959e4c726e..3b8c98a3a1 100644 --- a/teams.md/src/pages/templates/migrations/slack-bolt.mdx +++ b/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.