Configure user authentication in Power Virtual Agents

Select the version of Power Virtual Agents you're using here:

Authentication allows users to sign in, giving your bot access to a restricted resource or information. Users can sign in with an Azure Active Directory (Azure AD) account, or with any OAuth2 identity provider such as Google or Facebook.

You can add user authentication to your bot when you edit a topic.

Power Virtual Agents supports the following authentication providers:

  • Azure Active Directory v1
  • Azure Active Directory v2
  • Any identity provider that complies with the OAuth2 standard.

Important

Changes to the authentication configuration will only take effect after you publish your bot. Make sure to plan ahead before you make authentication changes to your bot.

Prerequisites

Choose an authentication option

Power Virtual Agents supports several authentication options. Choose the one that meets your needs.

To change your bot's authentication settings, go to Manage on the side pane, and then go to the Security tab and select the Authentication card.

Screenshot of the Security page under the Manage menu, highlighting the Authentication card.

The following authentication options are available:

  • No authentication
  • Only for Teams
  • Manual (for any channel including Teams)

Screenshot of the Authentication pane showing the three authentication options.

No Authentication

No authentication is the standard configuration for bots that aren't created from Teams. Users can't sign in, and your bot can access only public information and resources.

Only for Teams

Important

When the Only for Teams option is selected, all channels except the Teams channel will be disabled.

Additionally, the Only for Teams option is not available if your bot is integrated with Dynamics 365 Customer Service.

Teams authentication, optimized for the Teams channel, is the standard configuration for bots that are created from Teams. It automatically sets up Azure AD authentication for Teams without the need for any manual configuration. Since Teams authentication itself identifies the user, users aren't prompted to sign in while they're in Teams, unless your bot needs expanded scope.

Only the Teams channel is available if you select this option. If you need other channels but still want authentication for your bot, choose Manual authentication.

If you select the Only for Teams option, the following variables are available in the authoring canvas:

  • UserID
  • UserDisplayName

For more information about these variables and how to use them, see Add user authentication to a Power Virtual Agents bot.

AuthToken and IsLoggedIn variables aren't available with this option. If you need an authentication token, use the Manual option.

If you change from Manual to Only for Teams authentication, and your topics contain the variables AuthToken or IsLoggedIn, they're displayed as Unknown variables after the change. Make sure to correct any topics with errors before you publish your bot.

Manual (for any channel including Teams)

You can configure any Azure AD, Azure AD V2, or OAuth2-compatible identity provider with this option. The following variables are available in the authoring canvas after you configure manual authentication:

  • UserID
  • UserDisplayName
  • AuthToken
  • IsLoggedIn

For more information about these variables and how to use them, see Add user authentication to a Power Virtual Agents bot.

Once the configuration is saved, make sure to publish your bot so the changes take effect.

Note

Authentication changes only take effect after the bot is published.

Required user sign in and bot sharing

Require users to sign in determines whether a user needs to sign in before talking with the bot. It's available only with Only for Teams and Manual authentication. We highly recommended that you turn on this setting when your bot needs to access sensitive or restricted information.

Screenshot of the Authentication pane showing the Require user to sign in option.

If you turn off this option, your bot won't ask users to sign in until it encounters a topic that requires them to.

When you turn on this option, it creates a system topic called Require users to sign in. This topic is only relevant for the Manual authentication setting. Users are always authenticated on Teams.

The Require users to sign in topic is automatically triggered for any user who talks to the bot without being authenticated. If the user fails to sign in, the topic redirects to the Escalate system topic.

The topic is read-only and can't be customized. To see it, select Go to the authoring canvas.

Control who can chat with the bot in the organization

Your bot's authentication and Require user to sign in setting in combination determines whether you can share the bot to control who in your organization can chat with it. The authentication setting doesn't affect sharing a bot for collaboration.

  • No authentication: Any user who has a link to the bot (or can find it; for example, on your website) can chat with it. You can't control which users in your organization can chat with the bot.

  • Only for Teams: The bot works only on the Teams channel. Since the user will always be signed in, the Require users to sign in setting is turned on and can't be turned off. You can use bot sharing to control who in your organization can chat with the bot.

  • Manual (for any channel including Teams):

    • If the service provider is either Azure Active Directory or Azure Active Directory V2, you can turn on Require users to sign in to control who in your organization can chat with the bot using bot sharing.

    • If the service provider is Generic OAuth2, you can turn Require users to sign in on or off. When it's turned on, a user who signs in can chat with the bot. You can't control which specific users in your organization may chat with the bot using bot sharing.

When a bot's authentication setting can't control who can chat with it, if you select Share on the bot's homepage a message informs you that anyone can chat with your bot.

Screenshot of a message stating everyone in the organization can chat with the bot because of its authentication setting.

Register a new app with your identity provider

Before you can configure manual authentication in Power Virtual Agents, you need to register a new app with your identity provider and get a Client ID and client secret. This section describes how to do that with the Azure portal for Azure AD. If you have a different identity provider, you should consult its setup instructions.

Make sure to configure the redirect URL to https://token.botframework.com/.auth/web/redirect, and that the assigned API permissions and scopes for the app are the same permissions you need the bot to access.

Important

Your app registration redirect URL must be https://token.botframework.com/.auth/web/redirect.
Ensure that the app has the correct API permissions and its related scopes.

Use Azure Active Directory as your identity provider

Create an app registration

  1. Sign in to the Azure portal, using an admin account on the same tenant as your bot.

  2. Go to App registrations, either by selecting the icon or searching in the top search bar.

  3. Create a new Application Registration.

  4. Select New registration and enter a name for the registration.
    It can be helpful to use the name of your bot. For example, if your bot is called "Contoso sales help", you might name the app registration "ContosoSalesReg" or something similar.

  5. Select Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox).

  6. Leave the Redirect URI section blank for now. You'll enter that information in the next steps.

  7. Select Register.

Add the redirect URL

  1. Once the registration is complete, the Overview page opens. Go to Authentication and then select Add a platform.

  2. Under Platform configurations select Add a platform, then select Web.

  3. Under Redirect URIs, enter https://token.botframework.com/.auth/web/redirect.

  4. Under the Implicit grant and hybrid flows section, turn on both ID tokens (used for implicit and hybrid flows) and Access tokens (used for implicit flows).

  5. Select Configure to confirm your changes.

Generate a client secret

  1. Go to Certificates & Secrets.

  2. Under the Client secrets section, select New client secret.

  3. (Optional) Enter a description. One will be provided if you leave it blank.

  4. Select the expiry period. Select the shortest period that's relevant for the life of your bot.

  5. Select Add to create the secret.

  6. Store the secret's Value in a temporary place. You'll need it when you configure your bot's authentication.

Important

If you navigate away from the page, the secret's Value is obfuscated and you'll need to generate a new client secret.

Configure manual authentication

  1. Sign in to Power Virtual Agents. If you're using Azure AD as your identity provider, make sure to sign in on the same tenant where you created the app registration.

  2. Open your bot.

  3. Select Manage on the side pane, and then go to the Security tab and select the Authentication card.

    Screenshot of selecting the Authentication card.

  4. Select Manual (for any channel including Teams).

    Screenshot of selecting the manual authentication option.

  5. Enter the required information.
    The information you need to enter depends on your setup and provider. If you have questions about what to enter, contact your administrator or identity provider.

  6. Select Save to finish the configuration.

Manual authentication fields

The following are all the fields you may see when you're configuring manual authentication. Which fields you'll see depends on your choice for service provider.

Authorization URL template

The URL template for authorization, as defined by your identity provider; for example, https://login.microsoftonline.com/common/oauth2/v2.0/authorize

To find this information when you're using Azure AD as your identity provider: Go to the app registration's Overview page and select Endpoints. The URL template for authorization is shown as OAuth 2.0 token endpoint (v2).

Authorization URL query string template

The query template for authorization, as provided by your identity provider. Keys in the query string template will vary depending on the identity provider.

When you're using Azure AD, enter ?client_id={ClientId}&response_type=code&redirect_uri={RedirectUrl}&scope={Scopes}&state={State}.

Client ID

Your client ID, obtained from the identity provider.

To find this information when you're using Azure AD as your identity provider: Go to the app registration's Overview page. The Client ID is shown as Application (client) ID.

Client secret

Your client secret, obtained when you created the identity provider app registration. If you navigate away from the Certificates & secrets page before you record the client secret, its Value is obfuscated and you'll need to create a new one.

To find this information when you're using Azure AD as your identity provider: Generate a new client secret.

Refresh body template

The template for the refresh body.

When you're using Azure AD as your identity provider, enter refresh_token={RefreshToken}&redirect_uri={RedirectUrl}&grant_type=refresh_token&client_id={ClientId}&client_secret={ClientSecret}.

Refresh URL query string template

The refresh URL query string separator for the token URL, usually a question mark (?).

Refresh URL template

The URL template for refresh; for example, https://login.microsoftonline.com/common/oauth2/v2.0/token. For Azure apps, replace the base URL with your Azure app URL.

To find this information when you're using Azure AD as your identity provider: Go to the app registration's Overview page and select Endpoints. The refresh URL template is shown as OAuth 2.0 token endpoint (v2).

Scope list delimiter

The separator character for the scope list. When you're using Azure AD as your identity provider, enter a comma (,).

Empty spaces aren't supported in this field. You can use them in the Scopes field if the identity provider requires it. In that case, enter a comma (,) in Scope list delimiter, and enter spaces in the Scopes field.

Scopes

The list of scopes that you want users to have after they've signed in.

Use spaces to separate multiple scopes, only set necessary scopes, and follow the least privilege access control principle.

To find this information when you're using Azure AD as your identity provider: Go to the API permissions page under API / Permissions.

For custom scopes that are defined by an exposed API, you'll need to use the full URI, including the exposed Application ID URI. On the Expose an API page, add the Application ID URI and ending slash (/) at the beginning of the scope name. For example, if your custom scope name is app.scope.sso, and the Application ID URI is api://1234-4567, then you would enter api://1234-4567/app.scope.sso as the scope.

Service provider

The service provider you want to use for authentication.

If you're using Azure AD as your identity provider, we recommend using "Azure Active Directory" or "Azure Active Directory V2" for easier configuration.

For more information, see OAuth generic providers.

Tenant ID

Your Azure AD tenant ID. Refer to Use an existing Azure AD tenant to learn how to find your tenant ID.

Token body template

The template for the token body.

When you're using Azure AD as your identity provider, enter code={Code}&grant_type=authorization_code&redirect_uri={RedirectUrl}&client_id={ClientId}&client_secret={ClientSecret}.

Token exchange URL (required for SSO)

This is an optional field used when you're configuring single sign-on.

Token URL template

The URL template for tokens, as provided by your identity provider; for example, https://login.microsoftonline.com/common/oauth2/v2.0/token. For Azure apps, replace the base URL with your Azure app URL.

To find this information when using Azure AD as your identity provider: Go to the app registration's Overview page and select Endpoints. The token URL template is shown as OAuth 2.0 token endpoint (v2).

Token URL query string template

The query string separator for the token URL, usually a question mark (?).

When you're using Azure AD as your identity provider, enter a question mark (?).

Test your configuration

After the setup steps are complete, save your configuration and test it by creating a new topic using authentication.

Remove the authentication configuration

  1. Edit your bot and select Manage on the side pane, and then go to the Security tab and select the Authentication card.
  2. Select No authentication.
  3. Publish the bot.

If authentication variables are being used in a topic, they'll become Unknown variables. Go to the Topics page to see which topics have errors and fix them before publishing.