Add end-user authentication to a Microsoft Copilot Studio bot
Important
Power Virtual Agents capabilities and features are now part of Microsoft Copilot Studio following significant investments in generative AI and enhanced integrations across Microsoft Copilot.
Some articles and screenshots may refer to Power Virtual Agents while we update documentation and training content.
You can enable user authentication directly within a Microsoft Copilot Studio bot conversation. User authentication means you can get a user's basic properties such as name and ID in bot variables, but also prompt a user to sign in using an authentication node, retrieve a user token for that user, and then use that token to retrieve the user's information from a back-end system.
Note
Bots created in the web app and in Microsoft Teams come with authentication pre-configured to use Only for Teams and Power Apps authentication.
You can also configure single sign-on (SSO) so your users don't need to sign in manually. For more information, see Configure SSO for web.
Prerequisites
- Learn more about what you can do with Microsoft Copilot Studio.
- Use variables
- Configure end-user authentication.
Add user authentication to a topic to allow your customers to sign in right in the conversation. You can then personalize the conversation with user variables and access back-end systems on the user's behalf.
Configure manual authentication with Microsoft Entra ID
You need to configure user authentication with Microsoft Entra ID before you can use authentication in your topics.
- Follow the instructions in Configure user authentication with Microsoft Entra ID.
- Return to this article.
Add user authentication with the Signin system topic
When you create a bot, Microsoft Copilot Studio automatically adds a system topic called Signin. To use it, you must set your bot's authentication to manual and require users to sign in. When a customer starts a conversation with the bot, the Signin topic triggers and prompts the user to sign in. You can customize the Signin topic as appropriate for your bot.
In the navigation menu under Settings, select Security.
Select the Authentication tile.
Select Manual (for custom website), and then select Require users to sign in.
Add user authentication with a custom topic
The Signin topic authenticates the user at the beginning of the conversation. To allow the user to sign in later, you can add an Authenticate node to any custom topic.
When customers enter their username and password, they might be prompted to enter a validation code. After they've logged in, they won't be prompted again, even if they reach another Authenticate node.
In the navigation menu under Settings, select Security.
Select the Authentication tile.
Turn off Require users to sign in.
In the navigation menu, select Topics, and then open the topic you want to add authentication to.
Select Add node (+), select Call an action, and then select Authenticate.
Test your topic with a user configured with your identity provider.
Tip
It's important that you create paths for both a successful sign-in and failure to sign in. A sign-in may fail for many reasons, including errors with the identity provider's sign-in experience.
Authentication variables
When you've configured user authentication for your bot, you can use authentication variables in your topics. The following table compares the availability of these variables based on the authentication option you chose.
Authentication Variable | No Authentication | Only for Teams and Power Apps | Manual |
---|---|---|---|
User.DisplayName | not available | available | available |
User.FirstName | not available | available | available |
User.LastName | not available | available | available |
User.PrincipalName | not available | available | available |
User.Email | not available | available | available |
User.Id | not available | available | available |
User.IsLoggedIn | not available | available | available |
User.AccessToken | not available | not available | available |
SignInReason | not available | available | available |
User.DisplayName
Warning
This variable isn't guaranteed to contain a value. Test with a user from your identity provider to ensure your topic works correctly.
The User.DisplayName
variable contains the display name that's stored in the identity provider. Use this variable to greet or refer to the user without their having to explicitly give their name to the bot, making the conversation more personalized.
Microsoft Copilot Studio automatically sets the value of User.DisplayName
from the name
claim provided by the identity provider, as long as the profile
scope was defined when manual authentication was configured. For more information about scope, see Add user authentication to chatbot topics.
User.Id
Warning
This variable isn't guaranteed to contain a value. Test with a user from your identity provider to ensure your topic works correctly.
The User.Id
variable contains the userID that's stored in the identity provider. Use this variable in Power Automate flows to call APIs that take the UserID as a value.
Microsoft Copilot Studio automatically sets the value of User.DisplayName
from the sub
claim provided by the identity provider.
User.IsLoggedIn
User.IsLoggedIn
is a boolean-type variable that stores the user's sign-in status. A value of true
indicates the user is signed in. You can use this variable to create branching logic in your topics that checks for a successful sign-in, or to fetch user information only if the user is signed in.
User.AccessToken
Warning
Make sure you're passing the User.AccessToken
variable only to trusted sources. It contains user authentication information, which, if compromised, could harm the user.
The User.AccessToken
variable contains the user's token, obtained after the user is signed in. You can pass this variable to Power Automate flows so they can connect to back-end APIs and fetch user information, or to take actions on the user's behalf.
Don't use User.AccessToken
in Message nodes or in flows that you don't trust.
SignInReason
SignInReason
is a choice-type variable that indicates when the user must sign in. It has two possible values:
SignInRequired
indicates the user must sign in at the beginning of the conversation using the Signin system topic. Require users to sign in must be turned on.Initializer
indicates that if the user hasn't signed in yet, and they reach a point in the conversation that uses authentication variables, they'll be prompted to sign in.
Related topics
You can also configure single sign-on (SSO) so your users don't need to sign in manually. For more information, see Configure SSO for web.
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for