Skip to content

[Dev-Docs AI Improvement]: Enable SSO for Adaptive Cards Universal Actions in your bot #13663

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
docsautomation wants to merge 1 commit into
base: main
Choose a base branch
from
Open

[Dev-Docs AI Improvement]: Enable SSO for Adaptive Cards Universal Actions in your bot #13663

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 10 additions & 20 deletions ...tions-for-adaptive-cards/enable-sso-for-your-adaptive-cards-universal-action.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,24 +1,14 @@
---
Copy link
Collaborator

@SharanGarcha-MSFT SharanGarcha-MSFT Dec 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do not delete these. These are mandatory elements of the article.

title: SSO for Adaptive Cards Universal Action
description: Learn about Single sign-on (SSO) authentication in Teams and how to enable it in Adaptive Cards Universal Action in bots.
ms.author: surbhigupta
ms.topic: conceptual
ms.localizationpriority: medium
ms.date: 01/24/2023
ms.owner: ryanbliss
---

# Enable SSO for Adaptive Cards Universal Actions in your bot

With Single sign-on (SSO) in Teams, app users have the advantage of using Teams to access Adaptive Cards Universal Actions in a bot. After logging in to Teams using Microsoft or Microsoft 365 account, app users can use your app without the need to sign in again. Your app is available to app users on any device with access granted through Microsoft Entra ID.
With Single sign-on (SSO) in Teams, app users use Teams to access Adaptive Cards Universal Actions in a bot. After logging in to Teams using Microsoft or Microsoft 365 account, app users can use your app without needing to sign in again. Your app is available to app users on any device with access granted through Microsoft Entra ID.
Copy link
Collaborator

@SharanGarcha-MSFT SharanGarcha-MSFT Dec 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The phrasing “have the advantage of using” is more aligned with the Microsoft Writing Style Guide’s preference for natural, user-focused language.
“Without the need to sign in again” aligns with the “use plain language” guidance in the Writing Style Guide.
Please retain original version


For more information about Universal Actions for Adaptive Cards, see [Universal Actions for Adaptive Cards](Overview.md).

Adaptive Cards Universal Actions uses the bot as the common backend for handling actions and introduces a new action type. Bot uses Bot Framework to handle communication with the app users and to send and receive access token to the bot for SSO authentication. Similarly, Adaptive Cards Universal Actions also uses Bot Framework to enable SSO authentication.
Adaptive Cards Universal Actions uses the bot as the common backend for handling actions and introduces a new action type. Bot uses Bot Framework to handle communication with app users and to send and receive access token to the bot for SSO authentication. Similarly, Adaptive Cards Universal Actions also uses Bot Framework to enable SSO authentication.

Ensure that you enable the SSO for your bot before you enable SSO for your Adaptive Cards Universal Actions.
Ensure that you enable SSO for your bot before you enable SSO for your Adaptive Cards Universal Actions.

> [!div class="nextstepaction"]
>
> [Enable SSO for your bot](../../../bots/how-to/authentication/bot-sso-overview.md)

## SSO in Teams at runtime
Expand All @@ -27,14 +17,14 @@ SSO for Adaptive Cards Universal Actions in a bot can be enabled by obtaining ac

The following image shows how SSO works when a Teams app user attempts to access the Adaptive Cards Universal Actions in a bot:

:::image type="content" source="../../../assets/images/authentication/sso-runtime-seqd-adaptivecard.png" alt-text="Screenshot shows SSO flow for Adaptive Cards Universal Actions in a bot." lightbox="../../../assets/images/authentication/sso-runtime-seqd-adaptivecard.png":::
![Screenshot shows SSO flow for Adaptive Cards Universal Actions in a bot.](https://learn.microsoft.com/en-us/microsoftteams/platform/assets/images/authentication/sso-runtime-seqd-adaptivecard.png)
Copy link
Collaborator

@SharanGarcha-MSFT SharanGarcha-MSFT Dec 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dont remove the path. As part of the Acrolinx, you cant use en-us website, so we include path as shown in the original content


| # | Interaction | What's going on |
| --- | --- | --- |
| 1 | Teams client → Bot service | Teams sends an invoke `Action.Execute` request to the bot. <br> If the app user has previously signed in, a token is saved in the Bot Framework Token Store. The bot calls the Bot Framework Token Service that checks for an existing token for the app user in the Bot Framework Token Store. <br> • If the token exists, the app user is given access. <br> • If the token isn't available, the bot triggers the auth flow. |
| 2 | Microsoft Entra ID → Teams client | For the app user who's using the Adaptive Cards Universal Actions in a bot for the first time, the token exchange can occur only after the app user gives the consent. Teams client displays a message to the app user for giving consent. <br> In case the consent fails: <br> 1. The authentication falls back to the sign-in prompt and the app user must sign in to use the bot app. The sign-in button appears in Teams client and when the app user selects it, the Microsoft Entra sign-in page appears. <br> 2. The app user signs in and grants access to the Bot service. |
| 1 | Teams client → Bot service | Teams sends an invoke `Action.Execute` request to the bot. <br> If the app user has previously signed in, a token is saved in Bot Framework Token Store. The bot calls Bot Framework Token Service that checks for an existing token for the app user in Bot Framework Token Store. <br> • If the token exists, the app user is given access. <br> • If the token isn't available, the bot triggers the auth flow. |
| 2 | Microsoft Entra ID → Teams client | For the app user who's using Adaptive Cards Universal Actions in a bot for the first time, the token exchange can occur only after the app user gives consent. Teams client displays a message to the app user for giving consent. <br> In case the consent fails: <br> 1. The authentication falls back to the sign-in prompt and the app user must sign in to use the bot app. The sign-in button appears in Teams client and when the app user selects it, the Microsoft Entra sign-in page appears. <br> 2. The app user signs in and grants access to Bot service. |
Copy link
Collaborator

@SharanGarcha-MSFT SharanGarcha-MSFT Dec 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Retain The app user signs in and grants access to the Bot service.

This reads more natural, aligns with Microsoft’s preference for clarity and consistency, and treats “Bot service” as the specific service the user is granting access to.

| 3 | Teams Client → Bot service | Teams client resends the invoke `Action.Execute` request to the bot along with the token. <br> Bot service sends an invoke response with an OAuth card in response to `adaptiveCard/action` invoke call. Teams client sends the original `adaptiveCard/action` again to the bot along with the token. |
| 4 | Microsoft Entra ID → Teams client | Microsoft Entra ID sends invoke response with Adaptive Card to Teams client. Bot returns a nonerror response to the Teams client using either a card or message. |
| 4 | Microsoft Entra ID → Teams client | Microsoft Entra ID sends invoke response with Adaptive Card to Teams client. Bot returns a nonerror response to Teams client using either a card or message. |

For an Adaptive Cards Universal Actions in a bot, the bot app sends an OAuth card to Teams client. This card is used to get access token from Microsoft Entra ID using `tokenExchangeResource`. Following app user's consent, Teams client sends the token received from Microsoft Entra ID to the bot app using `tokenExchange`. The bot app can then parse the token to retrieve the app user's information, such as email address.

Expand All @@ -50,10 +40,10 @@ Bots can respond with sign-in request in response to `Action.Execute` for:

## Next step

> [!div class="nextstepaction"]
Copy link
Collaborator

@SharanGarcha-MSFT SharanGarcha-MSFT Dec 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We will need this to be retained for the developers to click next step. Please do not delete.

>
> [Add code to enable SSO for Adaptive Cards Universal Actions](sso-adaptive-cards-universal-action.md)

## See also

* [Work with Universal Actions for Adaptive Cards](Work-with-Universal-Actions-for-Adaptive-Cards.md)
* [Authentication flow in Adaptive Cards Universal Actions](authentication-flow-in-universal-action-for-adaptive-cards.md)
* [Authentication flow in Adaptive Cards Universal Actions](authentication-flow-in-universal-action-for-adaptive-cards.md)