Configure single sign-on with Azure Active Directory for Power Virtual Agents chatbots in Microsoft Teams

• 12/7/2020
• 6 minutes to read
• • i
  • c

The Power Virtual Agents app in Microsoft Teams supports single sign-on (SSO), which means chatbots can sign the user in silently, without having the user sign in again.

When using Teams the user is already signed-in, so Power Virtual Agents chatbots can use this information for scenarios that require user-specific information like a user's name or other details.

Prerequisites

• Register a new app with Azure AD
• Add an authentication topic to your bot
• Make sure your bot and Azure AD app are under the same tenant

Configure single sign-on

The steps required to configure SSO for the Power Virtual Agents app in Microsoft Teams include:

1. Create your Azure AD app.
2. Update your Azure AD app registration.
3. Update the Azure AD authentication created in the Power Virtual Agents web app.

This topic describes how to do these three steps. After you've finished these steps, you should:

1. Publish your changes in the Power Virtual Agents web app.
2. Test that SSO is working as expected in all the channels your bot is available.

Create your Azure AD app

Follow the instructions for Single sign-on (SSO) support for tabs to create your Azure AD app.

Update your Azure AD app registration

You will need to update your Azure AD app registration by doing the following tasks:

1. Add your Teams app ID to your Azure AD app registration to link the two together.
2. Grant admin consent for your app registration so users don't have to consent every time.
3. Define a custom scope for your bot to enable admin consent.
4. Add authorized client apps to allow your app registration to interface with the Teams web and desktop apps.

Add your Teams app ID to your Azure AD app registration

You will need to get your Teams app ID:

1. Log in to the Power Virtual Agents web app at https://web.powerva.microsoft.com and open the bot that you want to configure SSO for.

2. Expand Manage on the side navigation pane, and then select Channels. Select the Microsoft Teams tile.

3. In the panel that appears to the side, select Submit for admin approval and then copy the app ID by selecting Copy.

   

Now you can add the app ID URI to your Azure AD app registration:

1. Go to the Azure AD portal and find the Azure AD app that you registered and configured as part of the prerequisites.

2. Select Expose an API on the side navigation panel and set the Application ID URI to be in format of api://botid-{teamsbotid}, where you replace {teamsbotid} with the app ID you copied.

3. Select Save.

   

Grant admin consent

To grant admin consent:

1. In the app registration screen for your Azure AD app, go to API Permissions on the side navigation panel.

2. Select Grant admin consent for <your tenant name> and then Yes.

   

Define a custom scope for your bot

To define a custom scope for your bot:

1. In the app registration screen for your Azure AD app, go to Expose an API on the side navigation panel.

2. Select Add a scope.

   

3. Enter a name for the scope, along with the display information that should be shown to users when they come to the SSO screen.

4. Select Add a scope.

5. Enter a Scope name, Admin consent display name, Admin consent description.

   

Add authorized client app IDs

Now you'll need to add the Teams client app IDs, which are:

• 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)

• 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams on the web)

1. In the Expose an API section in the app registration screen for your Azure AD app, select Add a client application.

2. Enter the first client app ID, 1fec8e78-bce4-4aaf-ab1b-5451cc387264, into the Client ID field. Select the checkbox for the listed scope that you created.

3. Select Add application.

   

4. Repeat from Step 1, this time using 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 as the second client app ID and make sure to select the scope checkbox.

The Expose an API page should have these values:

Update the Azure AD authentication created in the Power Virtual Agents web app

You'll now need to update the Azure AD authentication settings in the Power Virtual Agents web app that you configured as part of the prerequisites.

You'll need to add the token exchange URL to allow Teams and Power Virtual Agents to share information, and you'll need to do the final configuration of the SSO information.

To add the token exchange url:

1. Go to the Azure AD authentication you configured when following the steps to create the new Azure AD authentication in the Power Virtual Agents web app.

2. Add the Token Exchange URL as described in the Configure SSO with Azure AD topic, under the Configure authentication in Power Virtual Agents to Enable SSO heading.

   

To add Teams SSO configuration information in the Power Virtual Agents bot:

1. Log in to the Power Virtual Agents web app at https://web.powerva.microsoft.com and open the bot that you want to configure SSO for.

2. Expand Manage on the side navigation pane, and then select Channels. Select the Microsoft Teams tile.

3. Select Edit details.

4. Select More to see the Teams SSO configuration details. Scroll all the way to the bottom of the panel. Add the following information:

   • AAD application's client ID: Add the Application ID from the Overview page of the Azure AD app registration. This ID is the same client ID that was added in the Client ID field when creating the Azure AD authentication in the Power Virtual Agents web app.

   • Resource URI: This URI is the Application ID URI from the Expose an API page in the Azure AD app registration.

5. Save and close.

   

These steps update the manifest file for the bot. Now you can download the manifest file (as a .zip file) and upload to Teams for test or distribution, or submit for your admin approval. For more information, see the Add bot to Microsoft Teams in Teams topic.

1. Select Download manifest to get the new manifest.