Configure single sign-on with Azure Active Directory for Power Virtual Agents chatbots in Microsoft Teams
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.
Important
- SSO in the Power Virtual Agents app in Teams is only supported for Azure Active Directory v2 apps (Azure AD v2 apps). Other app types, such as Azure AD v1, do not support SSO in the Power Virtual Agents app in Microsoft Teams.
- If you have SSO configured for the web publication channel, you must follow this document for authentication to work in Teams bots, otherwise authentication in the Teams channel will fail without an error message.
- SSO is not supported when your bot is integrated with Dynamics 365 Customer Service.
Prerequisites
- Learn more about what you can do with Power Virtual Agents.
- 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 SSO
The steps required to configure SSO for the Power Virtual Agents app in Microsoft Teams include:
- Create your Azure AD app.
- Update your Azure AD app registration.
- 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:
- Publish your changes in the Power Virtual Agents web app.
- Test that SSO is working as expected in all the channels your bot is available.
Create your Azure AD app
Follow the instructions for 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:
- Add your Teams app ID to your Azure AD app registration to link the two together.
- Grant admin consent for your app registration so users don't have to consent every time.
- Define a custom scope for your bot to enable admin consent.
- 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:
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.
Expand Manage on the side pane, and then select Channels. Select the Microsoft Teams tile.
In the pane that appears to the side, select Edit detail, expand More and then copy the app ID by selecting Copy.
Note
If you haven't already enabled the Teams channel, you will see instead see a notice that you need to enable Teams. Select Turn on Teams and then re-try Step 1 to get the app ID.
Now you can add the app ID URI to your Azure AD app registration:
Go to the Azure AD portal and find the Azure AD app that you registered and configured as part of the prerequisites.
Select Expose an API on the side pane and set the Application ID URI to be in format of
api://botid-{teamsbotid}
, where you replace{teamsbotid}
with the app ID you copied.Select Save.
Grant admin consent
To grant admin consent:
In the app registration screen for your Azure AD app, go to API Permissions.
Select Grant admin consent for <your tenant name> and then Yes.
Important
To avoid users from having to consent to each application, a Global Administrator, Application Administrator, or a Cloud Application Administrator must grant tenant-wide consent to your app registrations.
Define a custom scope for your bot
To define a custom scope for your bot:
In the app registration screen for your Azure AD app, go to Expose an API on the side pane.
Select Add a scope.
Enter a name for the scope, along with the display information that should be shown to users when they come to the SSO screen.
Select Add a scope.
Enter a Scope name, Admin consent display name, Admin consent description.
Add authorized client app IDs
Note
Remember to replace the example IDs and values below with your own Azure AD configured values.
Now you'll need to add the Teams client app IDs, which are:
Teams mobile/desktop application:
1fec8e78-bce4-4aaf-ab1b-5451cc387264
Teams on the web:
5e3ce6c0-2b1f-4285-8d4b-75ee78787346
In the Expose an API section in the app registration screen for your Azure AD app, select Add a client application.
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.Select Add application.
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:
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.
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:
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.
Expand Manage on the side pane, and then select Channels. Select the Microsoft Teams tile.
Select Edit details.
Select More to see the Teams SSO configuration details. Scroll all the way to the bottom of the pane. 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.
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.
Select Availability options.
Select Download .zip to get the new manifest.
Important
If your users have used the manifest to install the bot, they will need to get a new manifest after this configuration is complete and install the bot again for the Teams SSO to work. The Teams manifest does not refresh automatically. Alternatively, if you submit for Admin approval, the manifest is updated automatically.
Note
Make sure to test your bot authentication functionality in all channels to ensure they are working as intended.
Feedback
Submit and view feedback for