-description: Learn how to enable authentication using third-party OAuth provider to a bot app in Teams using Azure AD.

-> You only need to register your bot if it is not hosted in Azure. If you [created a bot](/azure/bot-service/abs-quickstart?view=azure-bot-service-4.0&viewFallbackFrom=azure-bot-service-3.0&preserve-view=true) through the Azure portal then it is already registered with the service. If you created your bot through the [Bot Framework](https://dev.botframework.com/bots/new) or [Developer Portal](../../../concepts/build-and-test/teams-developer-portal.md) your bot isn't registered in Azure.

- :::image type="content" source="~/assets/images/manage-bot-label.png" alt-text="This screenshot shows how to create manage bot.":::

-In this procedure, you'll use an Azure AD provider; other Azure AD supported identity providers can also be used.

-1. Once it's created, Azure displays the **Overview** page for the app. Copy and save the following information to a file:

-Note-there are two options for Service Providers here- Azure AD V1 and Azure AD V2. The differences between the two providers are summarized [here](/azure/active-directory/azuread-dev/azure-ad-endpoint-comparison), but in general, V2 provides more flexibility with respect to changing bot permissions. Graph API permissions are listed in the scopes field, and as new ones are added, bots will allow users to consent to the new permissions on the next sign in. For V1, the bot consent must be deleted by the user for new permissions to be prompted in the OAuth dialog.

-1. Launch Visual Studio.

-1. From the toolbar, select **File -> Open -> Project/Solution** and open the bot project.

-1. Clone [py-auth-sample][teams-auth-bot-py] from the github repository.

- :::image type="content" source="../../../assets/images/authentication/auth-bot-teams-upload.png" alt-text="This screenshot shows an example of the bot after it is uploaded into Teams.":::

-| Tab, Bot and Message Extension (ME) SSO | This sample shows SSO for Tab, Bot and ME - search, action, linkunfurl. | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/app-sso/csharp) | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/app-sso/nodejs) | Not available |

-description: Enable Single sign-on (SSO) using Azure AD configuration and OAuth card support for Teams bot apps.

-# Use SSO authentication for bots

-Single sign-on (SSO) authentication in Microsoft Azure Active Directory (Azure AD) silently refreshes the authentication token to minimize the number of times users need to enter their sign in credentials. If users agree to use your app, they don't have to provide consent again on another device as they're signed in automatically. Tabs and bots have similar flow for SSO support, but bot [requests tokens](#request-a-bot-token) and [receives responses](#receive-the-bot-token) with a different protocol.

->[!NOTE]

->

-> * OAuth 2.0 is an open standard for authentication and authorization used by Azure AD and many other identity providers. A basic understanding of OAuth 2.0 is a prerequisite for working with authentication in Teams.

->

-> * Bot SSO is supported only in one-on-one chat.

-See the following video to learn about SSO support for bots:

-<br>

-> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RE4OASc]

-<br>

-## Bot SSO at runtime

-The following image illustrates the flow of SSO in bots:

-The following steps help you with authentication and bot application tokens:

-1. The bot sends a message to Teams with an OAuthCard that contains `tokenExchangeResource` to obtain an authentication token for the bot application. The user receives messages at all the active user endpoints.

- > [!NOTE]

- >

- > * A user can have more than one active endpoint at a time.

- > * The bot token is received from every active user endpoint.

- > * The app must be installed in personal scope for SSO support.

-1. If the current user is using your bot application for the first time, a request prompt appears to the user to do one of the following actions:

- * Provide consent, if necessary.

- * Handle step-up authentication, such as two-factor authentication.

-1. Teams requests the bot application token from the Azure AD endpoint for the current user.

-1. Azure AD sends the bot application token to the Teams application.

-1. Teams sends the token to the bot as part of the value object returned by the invoking with **sign in** or **tokenExchange**.

-

-1. The parsed token in the bot application provides the required information, such as the user's email address.

-

-## Develop an SSO Teams bot

-

-The following steps guide you to develop SSO Teams bot:

-1. [Register your app through the Azure AD portal](#register-your-app-through-the-azure-ad-portal).

-1. [Update your Teams application manifest for your bot](#update-your-teams-application-manifest-for-your-bot).

-1. [Add the code to request and receive a bot token](#add-the-code-to-request-and-receive-a-bot-token).

-### Register your app through the Azure AD portal

-The steps to register your app through the Azure AD portal are similar to the [tab SSO flow](../../../tabs/how-to/authentication/tab-sso-overview.md). The following steps guide you to register your app:

-1. Register a new application in the [Azure Active Directory ΓÇô App Registrations](https://go.microsoft.com/fwlink/?linkid=2083908) portal.

-1. Select **New Registration**. The **Register an application** page appears.

- :::image type="content" source="~/assets/images/authentication/SSO-bots-auth/app-registration.png" alt-text="Screenshot of the AAD app registrations. The menu entry titled New registration.":::

-1. In the **Register an application**, do the following steps:

- > [!NOTE]

- >

- > The users are not asked for consent and are granted access tokens right away, if the Azure AD app is registered in the same tenant where they are making an authentication request in Teams. However, the users must provide consent to the permissions, if the Azure AD app is registered in a different tenant.

- * Enter **Name** for your app.

- * Select **Supported account types**, such as single tenant or multitenant.

- * Select **Register**.

- :::image type="content" source="~/assets/images/authentication/SSO-bots-auth/register-application.png" alt-text="Screenshot of the AAD app registrations. The menu entry titled register an application.":::

-1. Go to overview page.

-1. Copy the value of **Application (client) ID**.

-1. Under **Manage**, go to **Expose an API**.

- > [!TIP]

- > To update your app manifest later, save the **Application (client) ID** value.

- > [!IMPORTANT]

- >

- > * If you are building a standalone bot, enter the Application ID URI as `api://botid-{YourBotId}`. Here *YourBotId* is your Azure AD application ID.

- > * If you are building an app with a bot and a tab, enter the Application ID URI as `api://fully-qualified-domain-name.com/botid-{YourBotId}`.

-1. Select **Add a scope**.

-1. In the panel that prompts, enter `access_as_user` as the **Scope name**.

- >[!NOTE]

- > The "access_as_user" scope used to add a client app is for "Administrators and users".

- >

- > You must be aware of the following important restrictions:

- >

- > * Only user-level Microsoft Graph API permissions, such as email, profile, offline_access, and OpenId are supported. If you need access to other Microsoft Graph scopes, such as `User.Read` or `Mail.Read`, see [Extend tab app with Microsoft Graph permissions and scope](../../../tabs/how-to/authentication/tab-sso-graph-api.md).

- > * Your application's domain name must be same as the domain name that you have registered for your Azure AD application.

- > * Multiple domains per app are currently not supported.

- > * Applications that use the `azurewebsites.net` domain are not supported because it is common and may be a security risk.

-1. In the **Who can consent?**, enter **Admins and users**.

-1. Enter the following details to configure the admin and user consent prompts with values that are appropriate for the `access_as_user`scope.

- * **Admin consent display name**: Teams can access the userΓÇÖs profile.

- * **Admin consent description**: Teams can call the appΓÇÖs web APIs as the current user.

- * **User consent display name**: Teams can access your profile and make requests on your behalf.

- * **User consent description**: Teams can call this appΓÇÖs APIs with the same rights as you have.

- :::image type="content" source="~/assets/images/authentication/SSO-bots-auth/add-a-scope.png" alt-text="Screenshot of the AAD app registrations. The menu entry titled add a scope.":::

-1. Ensure that the state is set to **Enabled**.

- :::image type="content" source="~/assets/images/authentication/SSO-bots-auth/enabled-state.png" alt-text="Screenshot of the AAD app registrations scope. The menu entry titled State":::

-1. Select **Add scope** to save the details. The domain part of the **Scope name** displayed must automatically match the **Application ID** URI set in the previous step, with `/access_as_user` appended to the end `api://subdomain.example.com/00000000-0000-0000-0000-000000000000/access_as_user`.

-1. In the **Authorized client applications**, identify the applications that you want to authorize for your appΓÇÖs web application.

-1. Select **Add a client application**.

- :::image type="content" source="~/assets/images/authentication/SSO-bots-auth/add-client-application.png" alt-text="Screenshot of the AAD app registrations. The menu entry titled add a client application.":::

-1. Enter each of the following client IDs and select the authorized scope you created in the previous step:

- * `1fec8e78-bce4-4aaf-ab1b-5451cc387264` for Teams mobile or desktop application.

- * `5e3ce6c0-2b1f-4285-8d4b-75ee78787346` for Teams web application.

- :::image type="content" source="~/assets/images/authentication/SSO-bots-auth/add-client-id.png" alt-text="Screenshot of the AAD app registrations. The menu entry titled add application.":::

-1. Go to **Authentication**.

-1. In **Platform configurations**, select **Add a platform**.

- :::image type="content" source="~/assets/images/authentication/SSO-bots-auth/platform-configuration.png" alt-text="Screenshot of the AAD app registrations platform configurations. The menu entry titled add a platform.":::

-1. Select **Web**.

- :::image type="content" source="~/assets/images/authentication/SSO-bots-auth/configure-platform.png" alt-text="Screenshot of the AAD app registrations configure platforms. The menu entry titled web. ":::

-1. Enter the **Redirect URIs** for your app.

- >[!NOTE]

- > This URI should be a fully qualified domain name. It's also followed by the API route where an authentication response is sent. If you're following any of the Teams samples, the URI is `https://token.botframework.com/.auth/web/redirect`. For more information, see [OAuth 2.0 authorization code flow](/azure/active-directory/develop/v2-oauth2-auth-code-flow).

- :::image type="content" source="~/assets/images/authentication/SSO-bots-auth/configure-web.png" alt-text="Screenshot of the AAD app registrations configure web. The menu entry titled redirect URIs.":::

-1. The following steps will help you to enable implicit grant:

- * Select **Authentication** from the left pane.

- * Select the **Access tokens** and **ID tokens** checkboxes.

- :::image type="content" source="~/assets/images/authentication/SSO-bots-auth/grant-flow.png" alt-text="Screenshot of the AAD app registrations. The menu entry titled grant flows.":::

- * Select **Save** to save the changes.

-1. Add necessary **API Permissions**.

- * Select **API permissions** from the left pane.

- * Select **Add a platform** to add any permissions that your app requires to downstream APIs, for example, User.Read.

-#### Update manifest in Microsoft Azure portal

-The following steps will guide you to update the bot manifest in Azure portal:

-1. Select **Manifest** from the left pane.

-1. Ensure the config item is set to **"accessTokenAcceptedVersion": 2**. If not, change it's value to **2**.

- :::image type="content" source="~/assets/images/bots/update-manifest.png" alt-text="Screenshot of the application manifest after you have successfully completed the registration of the application in AAD.":::

- >[!NOTE]

- > If you are already in testing your bot in Teams, you must sign out from this app and sign out from Teams. Then sign in again to see this change.

-1. Select **Save**.

-#### Update the Azure portal with the OAuth connection

-The following steps will guide you to update the Azure portal with the OAuth connection:

-1. In the Azure portal, go to [**AzureBot**](https://ms.portal.azure.com/#create/Microsoft.AzureBot).

-1. Go to **Configuration** on the left pane.

-1. Select **Add OAuth Connection Settings**.

- :::image type="content" source="~/assets/images/authentication/SSO-bots-auth/auth-setting2.png" alt-text="Screenshot of the AAD app registrations. The menu entry titled Add OAuth Connection Settings.":::

-1. The following steps will guide you to complete the **New Connection Setting** form:

- >[!NOTE]

- > **Implicit grant** may be required in the Azure AD application.

- * Enter **Name** in the **New Connection Setting** page.

- >[!NOTE]

- > The **Name** is referred to the settings of your bot service code in *step 5* of [Bot SSO at runtime](#bot-sso-at-runtime).

- * From the **Service Provider** dropdown menu, select **Azure Active Directory v2**.

- * Enter the client credentials, such as **Client Id** and **Client secret** for the Azure AD application.

- * For the **Token Exchange URL**, use the scope value defined in [Update your Teams application manifest for your bot](#update-your-teams-application-manifest-for-your-bot), for example, `api://botid-<your-app-id>/`. The Token Exchange URL indicates to the SDK that this Azure AD application is configured for SSO.

- * In the **Tenant ID**, enter *common*.

- * Add all the **Scopes** configured when specifying permissions to downstream APIs for your Azure AD application. With the Client ID and Client secret provided, the token store exchanges the token for a graph token with defined permissions.

- * Select **Save**.

- * Select **Apply**.

- :::image type="content" source="~/assets/images/authentication/Bot-connection-setting.png" alt-text="Screenshot of the AAD app registrations. The menu entry titled New Connection Setting.":::

-### Update your Teams application manifest for your bot

-If the application contains a standalone bot, then use the following code to add new properties to the Teams application manifest:

-```json

- "webApplicationInfo":

- {

- "id": "00000000-0000-0000-0000-000000000000",

- "resource": "api://botid-00000000-0000-0000-0000-000000000000"

- }

-```

-If the application contains a bot and a tab, then use the following code to add new properties to the Teams application manifest:

-```json

- "webApplicationInfo":

- {

- "id": "00000000-0000-0000-0000-000000000000",

- "resource": "api://subdomain.example.com/botid-00000000-0000-0000-0000-000000000000"

- }

-```

-**webApplicationInfo** is the parent of the following elements:

-* **id** - The client ID of the application. It's the application ID that you obtained as part of registering the application with Azure AD. Don't share this Application ID with multiple Teams apps. Create a new Azure AD app for each application manifest that uses `webApplicationInfo`.

-* **resource** - The domain and subdomain of your application. It's the same URI, including the `api://` protocol that you registered when creating your `scope` in [Register your app through the Azure AD portal](#register-your-app-through-the-azure-ad-portal). Don't include the `access_as_user` path in your resource. The domain part of this URI must match the domain and subdomains used in the URLs of your Teams application manifest.

-### Add the code to request and receive a bot token

-#### Request a bot token

-The request to get the token is a normal POST message request using the existing message schema. It's included in the attachments of an OAuthCard. The schema for the OAuthCard class is defined in [Microsoft Bot Schema 4.0](/dotnet/api/microsoft.bot.schema.oauthcard?view=botbuilder-dotnet-stable&preserve-view=true) and it's similar to a sign in card. Teams treats this request as a silent token acquisition if the `TokenExchangeResource` property is populated on the card. For the Teams channel, only the `Id` property, which uniquely identifies a token request, is honored.

->[!NOTE]

-> The Microsoft Bot Framework `OAuthPrompt` or the `MultiProviderAuthDialog` is supported for SSO authentication.

-If the user is using the application for the first time and user consent is required, the following dialog appears to continue with the consent experience:

-When the user selects **Continue**, the following events occur:

-* If the bot defines a sign in button, the sign in flow for bots is activated that is similar to the sign in flow from an OAuth card button in a message stream. The developer must decide which permissions require user's consent. This approach is recommended if you require a token with permissions beyond `openId`. For example, if you want to exchange the token for graph resources.

-* If the bot isn't providing a sign in button on the OAuth card, user consent is required for a minimal set of permissions. This token is useful for basic authentication and to get the user's email address.

-##### C# token request without a sign in button

-```csharp

- var attachment = new Attachment

- {

- Content = new OAuthCard

- {

- TokenExchangeResource = new TokenExchangeResource

- {

- Id = requestId

- }

- },

- ContentType = OAuthCard.ContentType,

- };

- var activity = MessageFactory.Attachment(attachment);

- // NOTE: This activity needs to be sent in the 1:1 conversation between the bot and the user.

- // If the bot supports group and channel scope, this code should be updated to send the request to the 1:1 chat.

- await turnContext.SendActivityAsync(activity, cancellationToken);

-```

-#### Receive the bot token

-The response with the token is sent through an invoke activity with the same schema as other invoke activities that the bots receive today. The only difference is the invoke name, `signin` or `tokenExchange`, and the **value** field. The **value** field contains the **Id**, a string of the initial request to get the token and the **token** field, a string value including the token.

->[!NOTE]

->

-> * You might receive multiple responses for a given request if the user has multiple active endpoints. You must deduplicate the responses with the token.

-> * With latest SDK updates, token exchange and deduplication is handled by `TeamsSSOTokenExchangeMiddleware`. If the activity name is `signin` or `tokenExchange`, the middleware attempts to exchange the token and deduplicate the incoming call by ensuring that only one exchange request is processed. For more information, see [`TeamsSSOTokenExchangeMiddleware`](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/bot-conversation-sso-quickstart/csharp_dotnetcore/BotConversationSsoQuickstart/AdapterWithErrorHandler.cs#L26).

-```csharp

- protected override async Task OnTokenResponseEventAsync(ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)

- {

- await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);

- }

-```

-### Token exchange failure

-If there's a token exchange failure, use the following code:

-```json

-{ΓÇïΓÇï

- "status": "<response code>",

- "body":

- {ΓÇïΓÇï

- "id":"<unique Id>",

- "connectionName": "<connection Name on the bot (from the OAuth card)>",

- "failureDetail": "<failure reason if status code is not 200, null otherwise>"

- }ΓÇïΓÇï

-}ΓÇïΓÇï

-```

-To understand what the bot does when the token exchange fails to trigger a consent prompt, see the following steps:

->[!NOTE]

-> No user action is required to be taken as the bot takes the actions when the token exchange fails.

-1. The client starts a conversation with the bot triggering an OAuth scenario.

-2. The bot sends back an OAuth card to the client.

-3. The client intercepts the OAuth card before displaying it to the user and checks if it contains a `TokenExchangeResource` property.

-4. If the property exists, the client sends a `TokenExchangeInvokeRequest` to the bot. The client must have an exchangeable token for the user, which must be an Azure AD v2 token and whose audience must be the same as `TokenExchangeResource.Uri` property. The client sends an invoke activity to the bot with the following code:

- ```json

- {

- "type": "Invoke",

- "name": "signin/tokenExchange",

- "value":

- {

- "id": "<any unique Id>",

- "connectionName": "<connection Name on the skill bot (from the OAuth card)>",

- "token": "<exchangeable token>"

- }

- }

- ```

-5. The bot processes the `TokenExchangeInvokeRequest` and returns a `TokenExchangeInvokeResponse` back to the client. The client must wait until it receives the `TokenExchangeInvokeResponse`.

- ```json

- {

- "status": "<response code>",

- "body":

- {

- "id":"<unique Id>",

- "connectionName": "<connection Name on the skill bot (from the OAuth card)>",

- "failureDetail": "<failure reason if status code is not 200, null otherwise>"

- }

- }

- ```

-6. If the `TokenExchangeInvokeResponse` has a `status` of `200`, then the client doesn't show the OAuth card. See the [normal flow image](/azure/bot-service/bot-builder-concept-sso?view=azure-bot-service-4.0#sso-components-interaction&preserve-view=true). For any other `status` or if the `TokenExchangeInvokeResponse` isn't received, then the client shows the OAuth card to the user. See the [fallback flow image](/azure/bot-service/bot-builder-concept-sso?view=azure-bot-service-4.0#sso-components-interaction&preserve-view=true). If there are any errors or unmet dependencies like user consent, this activity ensures that the SSO flow falls back to normal OAuthCard flow.

-### Update the auth sample

-Open [Teams auth sample](https://github.com/microsoft/BotBuilder-Samples/tree/master/samples/csharp_dotnetcore/46.teams-auth), and then complete the following steps to update it:

-1. Update the TeamsBot to handle the deduping of the incoming request by including the following code:

- ```csharp

- protected override async Task OnSignInInvokeAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)

- {

- await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);

- }

- protected override async Task OnTokenResponseEventAsync(ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)

- {

- await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);

- }

- ```

-

-2. Update `appsettings.json` to include the `botId`, password, and the connection name defined in [Update the Azure portal with the OAuth connection](#update-the-azure-portal-with-the-oauth-connection).

-3. Update the manifest and ensure that `token.botframework.com` is in the valid domains list. For more information, see [Teams auth sample](https://github.com/microsoft/BotBuilder-Samples/tree/master/samples/csharp_dotnetcore/46.teams-auth).

-4. Zip the manifest with the profile images and install it in Teams.

-## Code sample

-|**Sample name** | **Description** |**.NET** |**C#** |**Node.js** |

-|-|--|--|--|--|

-|Bot framework SDK | This sample code demonstrates how to get started with authentication in a bot for Microsoft Teams. |[View](https://github.com/microsoft/BotBuilder-Samples/tree/main/samples/csharp_dotnetcore/46.teams-auth)|[View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/bot-conversation-sso-quickstart/csharp_dotnetcore/BotConversationSsoQuickstart)|[View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/bot-conversation-sso-quickstart/js)|

-## Step-by-step guide

-Follow the [step-by-step guide](../../../sbs-bots-with-sso.yml), to build a bot with SSO authentication.

-description: Enable authentication for Microsoft Teams bot app with third-party OAuth provider using code samples.

-# Authentication flow for bots in Microsoft Teams

-OAuth 2.0 is an open standard for authentication and authorization used by Azure Active Directory and many other identity providers. A basic understanding of OAuth 2.0 is a prerequisite for working with authentication in Teams; [here's a good overview](https://aaronparecki.com/oauth-2-simplified/) that's easier to follow than the [formal specification](https://oauth.net/2/). Authentication flow for tabs and bots is a little different ΓÇö tabs are similar to websites so they can use OAuth 2.0 directly, while bots aren't and must do a few things differently, but the core concepts are identical.

-See the GitHub repo [Microsoft Teams Authentication Sample](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/app-auth/nodejs)

-for an example that demonstrates authentication flow for bots using Node.js and the [OAuth 2.0 authorization code grant type](https://oauth.net/2/grant-types/authorization-code/).

-

-1. The user sends a message to the bot.

-2. The bot determines if the user needs to sign in.

- In this example, the bot stores the access token in its user data store. It asks the user to sign in if it doesn't have a validated token for the selected identity provider. ([View code](https://github.com/OfficeDev/microsoft-teams-sample-auth-node/blob/469952a26d618dbf884a3be53c7d921cc580b1e2/src/utils/AuthenticationUtils.ts#L58-L76))

-3. The bot constructs the URL to the start page of the authentication flow, and sends a card to the user with a `signin` action. ([View code](https://github.com/OfficeDev/microsoft-teams-sample-auth-node/blob/469952a26d618dbf884a3be53c7d921cc580b1e2/src/dialogs/BaseIdentityDialog.ts#L160-L190))</br>

- Like other application auth flows in Teams, the start page must be in a domain that's on your `validDomains` list, and in the same domain as the post-login redirect page.

- > [!IMPORTANT]

- > The OAuth 2.0 authorization code grant flow calls for a `state` parameter in the authentication request, which contains a unique session token to prevent a [cross-site request forgery attack](https://en.wikipedia.org/wiki/Cross-site_request_forgery). The example uses a randomly-generated GUID.

-4. When the user selects the *signin* button, Teams opens a pop-up window and navigates to the start page.

- > [!NOTE]

- > The size of the pop-up window can be controlled through width and height query string parameters in the URL. For example, if you add width=600 and height=600, the size of the pop-up window is 600x600 pixels. The actual size of the pop-up window is capped as a percentage of the Teams main window size. If the Teams window is small, the pop-up window is smaller than the specified dimensions.

-5. The start page redirects the user to the identity provider's `authorize` endpoint. ([View code](https://github.com/OfficeDev/microsoft-teams-sample-auth-node/blob/469952a26d618dbf884a3be53c7d921cc580b1e2/public/html/auth-start.html#L51-L56))

-6. On the provider's site, the user signs in and grants access to the bot.

-7. The provider takes the user to the bot's OAuth redirect page with an authorization code.

-8. The bot redeems the authorization code for an access token, and **provisionally** associates the token with the user that initiated the sign-in flow. Below, we call this a *provisional token*.

- * In the example, the bot associates the value of the `state` parameter with the ID of the user that initiated the sign-in process so it can later match it with the `state` value returned by the identity provider. ([View code](https://github.com/OfficeDev/microsoft-teams-sample-auth-node/blob/469952a26d618dbf884a3be53c7d921cc580b1e2/src/AuthBot.ts#L70-L99))

- > [!IMPORTANT]

- > The bot stores the token it receives from the identity provider and associates it with a specific user, but it is marked as "pending validation".

- * The provisional token can't be used without further validation.

- 1. **Validate what's received from the identity provider.** The value of the `state` parameter must be confirmed against what was saved earlier.

- 1. **Validate what's received from Teams.** A [two-step authentication](https://en.wikipedia.org/wiki/Man-in-the-middle_attack) validation is performed to ensure that the user who authorized the bot with the identity provider is the same user who is chatting with the bot. This guards against [man-in-the-middle](https://en.wikipedia.org/wiki/Man-in-the-middle_attack) and [phishing](https://en.wikipedia.org/wiki/Phishing) attacks. The bot generates a verification code and stores it, associated with the user. The verification code is sent automatically by Teams as described below. ([View code](https://github.com/OfficeDev/microsoft-teams-sample-auth-node/blob/469952a26d618dbf884a3be53c7d921cc580b1e2/src/AuthBot.ts#L100-L113))

-9. The OAuth callback renders a page that calls `notifySuccess("<verification code>")`. ([View code](https://github.com/OfficeDev/microsoft-teams-sample-auth-node/blob/master/src/views/oauth-callback-success.hbs))

-10. Teams closes the pop-up window and sends the `<verification code>` sent to `notifySuccess()` back to the bot. The bot receives an [invoke](/bot-framework/dotnet/bot-builder-dotnet-activities#invoke) message with `name = signin/verifyState`.

-11. The bot checks the incoming verification code against the verification code stored with the user's provisional token. ([View code](https://github.com/OfficeDev/microsoft-teams-sample-auth-node/blob/469952a26d618dbf884a3be53c7d921cc580b1e2/src/dialogs/BaseIdentityDialog.ts#L127-L140))

-12. If they match, the bot marks the token as validated and ready for use. Otherwise, the auth flow fails, and the bot deletes the provisional token.

- > [!NOTE]

- > If you experience issues with authentication on mobile, ensure your JavaScript SDK is updated to version 1.4.1 or later.

-## Code sample

-Sample code showing the bot authentication process:

-| **Sample name** | **Description** | **Node.js** | **.NET** | **Python** |

-|--|-|--|-|--|

-| Teams authentication | This sample demonstrates authentication in Microsoft Teams apps. | [View](https://github.com/OfficeDev/microsoft-teams-sample-auth-node) | | |

-| Bot authentication | This sample demonstrates how to use authentication for a bot running in Microsoft Teams | [View](https://github.com/microsoft/BotBuilder-Samples/tree/main/samples/javascript_nodejs/46.teams-auth) | [View](https://github.com/microsoft/BotBuilder-Samples/tree/main/samples/csharp_dotnetcore/46.teams-auth) | [View](https://github.com/microsoft/BotBuilder-Samples/tree/main/samples/python/46.teams-auth)

-## See also

-[Add authentication to your Teams bot](add-authentication.md)

- :::image type="content" source="../../assets/images/authentication/bot-sso-icon.png" alt-text="SSO for bot app" link="../../bots/how-to/authentication/auth-aad-sso-bots.md":::

- :::image type="content" source="../../assets/images/authentication/mex-sso-icon.png" alt-text="SSO for messaging extension app" link="../../messaging-extensions/how-to/enable-SSO-auth-me.md":::

-> [!NOTE]

-> The Silent authentication page is moved to the Resources module. For more information, see [Silent authentication](../../tabs/how-to/authentication/auth-silent-aad.md).

-description: Enable authentication in Teams message extension app using third-party OAuth provider with Azure AD configuration and code sample.

-# Add authentication to your message extension

-> After adding authentication to the message extension, the user must add "**token.botframework.com**" to the "**validDomains**" section in the manifest.

-Your service should verify that the authentication code received in step 6 matches with step 5. The steps ensure that a malicious user doesn't try to spoof or compromise the sign in flow. The flow effectively "closes the loop" to finish the secure authentication sequence.

-[Single sign-on (SSO) support for message extensions](~/messaging-extensions/how-to/enable-sso-auth-me.md)

-description: Enable Single sign-on (SSO) in your Teams message extension app using Azure AD and code sample.

-# Enable SSO for message extensions

-Single sign-on (SSO) support is now available for message extensions and link unfurling. Enabling Single sign-on for message extensions by default refreshes the authentication token, which minimizes the number of times you need to enter the sign in credentials for Microsoft Teams.

-This document guides you on how to enable the SSO and store your authentication token, if necessary.

-## Prerequisites

-The prerequisite to enable SSO for message extensions and link unfurling are as follows:

-* You must have an [Azure](https://azure.microsoft.com/free/) account.

-* You must Configure your app through the Azure AD portal, and update Teams application manifest your bot as defined in [register your app through the Azure AD portal](../../bots/how-to/authentication/auth-aad-sso-bots.md#register-your-app-through-the-azure-ad-portal).

-> [!NOTE]

-> For more information on creating an Azure account and updating your app manifest, see [Single sign-on (SSO) support for bots](../../bots/how-to/authentication/auth-aad-sso-bots.md).

-## Enable SSO for message extensions and link unfurling

-After the prerequisites are completed, you can enable SSO for message extensions and link unfurling.

-To enable SSO:

-1. Update your bots [OAuth connection](../../bots/how-to/authentication/auth-aad-sso-bots.md#update-the-azure-portal-with-the-oauth-connection) details in the Microsoft Azure portal.

-2. Download the [message extensions sample](https://github.com/microsoft/BotBuilder-Samples/tree/main/samples/csharp_dotnetcore/52.teams-messaging-extensions-search-auth-config) and follow the setup instructions provided by the wizard.

- > [!NOTE]

- > Use your bots OAuth connection when setting up your message extensions.

-3. In the [TeamsMessagingExtensionsSearchAuthConfigBot.cs](https://github.com/microsoft/BotBuilder-Samples/tree/main/samples/csharp_dotnetcore/52.teams-messaging-extensions-search-auth-config/Bots/TeamsMessagingExtensionsSearchAuthConfigBot.cs) file, update the value from *auth* to *silentAuth* in the `OnTeamsMessagingExtensionQueryAsync` and / or `OnTeamsAppBasedLinkQueryAsync`.

- > [!NOTE]

- > We do not support other handlers SSO, except `OnTeamsMessagingExtensionQueryAsync` and `OnTeamsAppBasedLinkQueryAsync` from the TeamsMessagingExtensionsSearchAuthConfigBot.cs file.

-4. You receive the token in `OnTeamsMessagingExtensionQueryAsync` handler in the `turnContext.Activity.Value` payload or in the `OnTeamsAppBasedLinkQueryAsync`, depending on which scenario you're enabling the SSO for:

- ```json

- JObject valueObject=JObject.FromObject(turnContext.Activity.Value);

- if(valueObject["authentication"] !=null)

- {

- JObject authenticationObject=JObject.FromObject(valueObject["authentication"]);

- if(authenticationObject["token"] !=null)

- }

-

- ```

-

- If you're using the OAuth connection, add the following code to the TeamsMessagingExtensionsSearchAuthConfigBot.cs file to update or add the token in the store:

- ```C#

- protected override async Task<InvokeResponse> OnInvokeActivityAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)

- {

- JObject valueObject = JObject.FromObject(turnContext.Activity.Value);

- if (valueObject["authentication"] != null)

- {

- JObject authenticationObject = JObject.FromObject(valueObject["authentication"]);

- if (authenticationObject["token"] != null)

- {

- //If the token is NOT exchangeable, then return 412 to require user consent

- if (await TokenIsExchangeable(turnContext, cancellationToken))

- {

- return await base.OnInvokeActivityAsync(turnContext, cancellationToken).ConfigureAwait(false);

- }

- else

- {

- var response = new InvokeResponse();

- response.Status = 412;

- return response;

- }

- }

- }

- return await base.OnInvokeActivityAsync(turnContext, cancellationToken).ConfigureAwait(false);

- }

- private async Task<bool> TokenIsExchangeable(ITurnContext turnContext, CancellationToken cancellationToken)

- {

- TokenResponse tokenExchangeResponse = null;

- try

- {

- JObject valueObject = JObject.FromObject(turnContext.Activity.Value);

- var tokenExchangeRequest =

- ((JObject)valueObject["authentication"])?.ToObject<TokenExchangeInvokeRequest>();

- var userTokenClient = turnContext.TurnState.Get<UserTokenClient>();

- tokenExchangeResponse = await userTokenClient.ExchangeTokenAsync(

- turnContext.Activity.From.Id,

- _connectionName,

- turnContext.Activity.ChannelId,

- new TokenExchangeRequest

- {

- Token = tokenExchangeRequest.Token,

- },

- cancellationToken).ConfigureAwait(false);

- }

- #pragma warning disable CA1031 //Do not catch general exception types (ignoring, see comment below)

- catch

- #pragma warning restore CA1031 //Do not catch general exception types

- {

- //ignore exceptions

- //if token exchange failed for any reason, tokenExchangeResponse above remains null, and a failure invoke response is sent to the caller.

- //This ensures the caller knows that the invoke has failed.

- }

- if (tokenExchangeResponse == null || string.IsNullOrEmpty(tokenExchangeResponse.Token))

- {

- return false;

- }

- return true;

- }

-

- ```

-## Code sample

-This section provides Bot authentication v3 SDK sample.

-| **Sample name** | **Description** | **.NET** | **Node.js** | **Python** |

-||||-||

-| Bot authentication | This sample shows how to get started with authentication in a bot for Teams. | [View](https://github.com/microsoft/BotBuilder-Samples/tree/master/samples/csharp_dotnetcore/46.teams-auth) | [View](https://github.com/microsoft/BotBuilder-Samples/tree/master/samples/javascript_nodejs/46.teams-auth) | [View](https://github.com/microsoft/BotBuilder-Samples/tree/main/samples/python/46.teams-auth) |

-| Tab, Bot and Message Extension (ME) SSO | This sample shows SSO for Tab, Bot and ME - search, action, link unfurl. | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/app-sso/csharp) | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/app-sso/nodejs) | NA |

-|Tab, Bot, and Message extension| This sample shows how to check authentication in Bot,Tab, and Message extension with SSO | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/app-complete-auth/csharp) | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/app-complete-auth/nodejs) | NA |

-## See also

-* [Add authentication to your message extensions](add-authentication.md)

-* [Use SSO for bots](../../bots/how-to/authentication/auth-aad-sso-bots.md)

-* [Link unfurling](link-unfurling.md)

-# Extend tab app with Microsoft Graph permissions and scope

-2. Select **Manage** > **API permission** from the left pane.

-3. Select **+ Add permissions** to add Microsoft Graph API permissions.

-Before you update Teams app manifest, ensure that you've configure code to enable SSO in your tab app.

- > [!NOTE]

- >

- > - The manifest folder should be at the root of your project. For more information, see [Create a Microsoft Teams app package](../../../concepts/build-and-test/apps-package.md).

- > - For more information on learning how to create a manifest.json, see [Reference: Manifest schema for Microsoft Teams](../../../resources/schem).

-1. Open the manifest.json file

-> During debug, you can use ngrok to test your app in Azure AD. In that case, you need to replace the subdomain in `api://subdomain.example.com/00000000-0000-0000-0000-000000000000` with the ngrok url. You'll need to update the url whenever your ngrok subdomain changes For example, api://23c3-103-50-148-128.ngrok.io/bccfbe67-e08b-4ec1-a7fd-e0aaf41a097c.

-keywords: teams authentication tabs Microsoft Azure Active Directory (Azure AD) SSO access token app manifest

-<!--Single sign-on (SSO) allows a user to access an application or a web service after signing-in only once. The app users never have to go through authentication again.-->

-With SSO in Teams, app users have the advantage of using Teams to access apps. After logging into 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 Azure AD.

-For more information, see [Update code to enable SSO](tab-sso-code.md).

-## Enable SSO for a tab app

-This section describes the tasks involved in implementing SSO for a tab app. These tasks are language- and framework-agnostic.

-To enable SSO for a tab app:

-1. **Register with Azure AD**: Create an Azure AD app to generate an app ID and application ID URI. For generating access token, you configure scopes and authorize trusted client applications.

-2. **Update code**: Add the code to handle access token, calling `getAuthToken()` when an app user accesses your tab app, sending this token to your app's server code in the Authorization header, and validating the access token when it's received.

-<!--

-### Use cases for enabling SSO for tab app

-Here are some use cases where enabling SSO is beneficial. Call `getAuthToken()` in these scenarios to use Teams identity for obtaining access token for your app users:

-<!--

-```mermaid

-sequenceDiagram

- User->>Tab app: Opens Teams app

- Tab app->>Teams Client: 1. Call getAuthToken()

- Teams Client->>Sign-in and Consent: 2. Check if consent is required

- Sign-in and Consent->>Teams Client: Prompt for consent from new user

- Teams Client->>Azure AD: 3. Request access token from Azure AD

- Azure AD->>Teams Client: 4. Send access token to Teams Client

- Teams Client->>Tab app: 5. Respond to getAuthToken() with access token

- Tab app->>Tab app: 6. Parse access token to give access to user

-```

-<!--

-

- You can ask for consent using the Auth API. Another approach for getting Graph scopes is to present a consent dialog using our existing [third party OAuth provider authentication approach](~/tabs/how-to/authentication/auth-tab-aad.md#navigate-to-the-authorization-page-from-your-pop-up-page). This approach involves popping up an Azure AD consent dialog box.

- <details>

- <summary>To ask for additional consent using the Auth API, follow these steps:</summary>

- 1. The token retrieved using `getAuthToken()` must be exchanged on the server-side using Azure AD [on-behalf-of flow (OBO)](/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow) to get access to those other Graph APIs. Ensure you use the v2 Graph endpoint for this exchange.

- 2. If the exchange fails, Azure AD returns an invalid grant exception. It usually responds with one of the two error messages, `invalid_grant` or `interaction_required`.

- 3. When the exchange fails, you must ask for consent. Use the user interface (UI) to ask the app user to grant other consent. This UI must include a button that triggers an Azure AD consent dialog using [Silent authentication](~/concepts/authentication/auth-silent-aad.md).

- 4. When asking for more consent from Azure AD, you must include `prompt=consent` in your [query-string-parameter](~/tabs/how-to/authentication/auth-silent-aad.md#get-the-user-context) to Azure AD, otherwise Azure AD wouldn't ask for other scopes.

- - Instead of `?scope={scopes}`, use `?prompt=consent&scope={scopes}`

- - Ensure that `{scopes}` includes all the scopes you're prompting the user for, for example, `Mail.Read` or `User.Read`.

- 5. After the app user has granted more permissions, retry the OBO flow to get access to these other APIs.

- </details>

-<!--

-# Register your tab app in Azure AD

-## Enabling SSO on Azure AD

-Registering your tab app in Azure AD and enabling it for SSO requires making app configurations, such as generating app ID, defining API scope, and pre-authorize client IDs for trusted applications.

-> [!NOTE]

-> Microsoft Teams Toolkit registers the Azure AD application in an SSO project.

-### Before you register with Azure AD

-## Create an app registration in Azure AD

-Register a new app in Azure AD, and configure the tenancy and app's platform. You'll generate a new app ID that will be updated later in your Teams app manifest file.

- Your app is registered in Azure AD. You should now have app ID for your tab app.

-## Configure scope for access token

-### To expose an API

- - The application ID URI format should be: `api://fully-qualified-domain-name.com/{AppID}`.

- - `fully-qualified-domain-name.com` is the human-readable domain name from which your tab app is served. Your application's domain name and the domain name you register for your Azure AD application should be the same.

-### To configure API scope

-### To configure authorized client application

-1. Enter the appropriate Microsoft 365 client ID for the Teams Client for the applications that you want to authorize for your appΓÇÖs web application.

- > - The Microsoft 365 client IDs for mobile, desktop, and web applications for Teams, Office, and Outlook are the actual IDs that you should add.

- The client ID displays on the page.

-## Configure access token version

-You must define the access token version that is acceptable for your app. This configuration is made in the Azure AD application manifest.

-### To define the access token version

-When Azure AD receives a request for accessing a Microsoft Graph resource, it checks if the user (or tenant administrator) have given consent for this resource. If there's no record of consent from the user or administrator, Azure AD sends an error message to your web service.

-The server-side code should send a 403 Forbidden response to the client to show a message to the user. It is recommended that it should also log the error to the console, or record it in a log.

-1. The custom domain is not added to Azure AD. To add custom domain to Azure AD and register it, follow the [add a custom domain name to Azure AD](/azure/active-directory/fundamentals/add-custom-domain) procedure, and then follow the steps to [Configure scope for access token](tab-sso-register-aad.md#configure-scope-for-access-token) again.

-1. You are not signed in with Administrator credentials in the Microsoft 365 tenancy. Sign-in to Microsoft 365 as an administrator.