Add user authentication to topics

You can enable user authentication directly within an agent conversation. You can assign a user's basic properties, such as name and ID, to variables. You can also prompt a user to sign in using an authentication node in a topic, which retrieves a user token, and then use that token to retrieve the user's information from a back-end system.

Note

Agents created in Copilot Studio and in Microsoft Teams are automatically configured for Microsoft Entra ID authentication.

You can also configure single sign-on (SSO) so your users don't need to sign in manually. Learn more in Configure single sign-on with Microsoft Entra ID.

Prerequisites

• Variables overview
• Configure user authentication in Copilot Studio

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

Web app

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.

Add user authentication with the Sign in system topic

When you create an agent, Copilot Studio automatically adds a system topic called Sign in. To use it, you must set your agent's authentication to manual and require users to sign in. When a customer starts a conversation with the agent, the Sign in topic triggers and prompts the user to sign in. You can customize the Sign in topic as appropriate for your agent.

Important

We recommend that the Sign in topic is only used to provide the authentication method provided by Copilot Studio. It shouldn't be modified to call any other actions or flows, or other authentication methods.

1. Open your agent in Copilot Studio, select Settings at the top of the page, and then select Security.
2. Select Authentication.
3. Select Authenticate manually, and then select Require users to sign in.
4. Configure all manual authentication fields, as required.
5. Select Save.

Add user authentication with a custom topic

The Sign in 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 user name and password, they might be prompted to enter a validation code. After they sign in, they're not prompted again, even if they reach another Authenticate node.

1. Select Settings at the top of the page, and then select Security.

2. Select the Authentication tile.

   Note

   You must select Authenticate manually to add user authentication to a custom topic.

3. Select Authenticate manually and clear the Require users to sign in checkbox.

4. Configure all manual authentication fields, as required.

5. Select Save.

6. Select Topics at the top of the page.

7. Select Add node ( ) > Advanced > Authenticate.

8. 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 might fail for many reasons, including errors with the identity provider's sign-in experience.

Teams plan

If your authentication option is set to Authenticate with Microsoft, you don't need to explicitly add authentication to your topics. In this configuration, any user in Microsoft Teams is automatically signed in via their Teams credentials and they don't need to explicitly sign in with an authentication card. If your authentication option is set to Manual, then you must add an Authenticate node (even for the Teams channel).

Note

If your authentication option is set to Authenticate with Microsoft, you can't explicitly add authentication to your topics.

Add user authentication to a topic

The Authenticate node prompts a user to sign in with a sign-in card. Once a user signs in, they aren't prompted again, even if they reach another Authenticate node.

After the user enters their user name and password in the prompt (hosted by the identity provider), they might be prompted to enter a validation code, depending on the channel. Some channels, such as Microsoft Teams, don't require a validation code from the user.

When your agent has SSO configured, the user isn't prompted to sign in.

To add an Authenticate node to your topic:

1. Go to the Topics page for the agent you want to edit.

2. Open the topic to which you want to add the authentication template.

   Note

   If your agent is connected to Dynamics 365 Customer Service, the Authentication node can't be part of the conversation path the agent follows when initially greeting users; otherwise, the sign-in card is shown twice. Instead, add the Authenticate node to another topic that a user response triggers.

3. Select Add node (+) to add a message node. Enter what the agent should say to indicate that a sign-on experience is about to occur.

4. Underneath the message node, select Add node (+), select Call an action, and then select Authenticate.

   

   Note

   The Authenticate node is only available in the action picker at the end of a dialog tree (as a leaf node). You can't add it in the middle of a dialog. Once added, you can add other nodes below it.

   New nodes appear automatically: a parent Authenticate node, followed by nodes for a success path and a failure path.

User.AccessToken usage without an Authenticate node

The User.IsLoggedIn and User.AccessToken variables are available even if you don't use the template provided by the Call an action menu entry. If you pass the User.AccessToken variable without first having the user go through the Authenticate node, the user is prompted to sign in at that step.

Passing the User.AccessToken variable can be useful if you always expect the user to be signed in, or if your user is being redirected from a different topic. Use the template provided by the Call an action entry to handle cases where the user fails to sign in.

Note

If the user signs out in the middle of a conversation, they're prompted to sign in again if the topic comes to a node that uses the User.AccessToken variable.

Success path

The success path corresponds to User.IsLoggedIn = True and accounts for when the user is successfully signed in.

If you have logic that uses the User.AccessToken variable (for example, to connect to a back-end system by using a flow to retrieve a user's information), place it under this path.

Failure path

The failure path corresponds to any condition other than IsLoggedIn = True. In most cases, the failure path occurs because the user failed to sign in, used the wrong password, or canceled the sign-in experience.

Add any logic you want to handle this case. As an example, there are options for retrying or to escalate to a live agent. Customize the failure path's actions for your particular scenario and usage.

Testing your topic

Make sure to test your topic by using a real user configured in your identity provider. Ensure both the sign-in success and failure paths are exercised. By doing so, there are no surprises if your user fails to sign in or there's an error with the identity provider's sign-in experience.

Authentication variables

Web app

When you configure user authentication for your agent, you can use authentication variables in your topics. The following table compares the availability of these variables based on the authentication option you choose.

Authentication variable	No authentication	Authenticate with Microsoft	Authenticate manually
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 might not 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 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 agent, making the conversation more personalized.

Copilot Studio automatically sets the value of User.DisplayName from the name claim provided by the identity provider, as long as the profile scope is defined when manual authentication is configured. Learn more in Configure user authentication with Microsoft Entra ID.

User.Id

Warning

This variable might not contain a value. Test with a user from your identity provider to ensure your topic works correctly.

The User.Id variable contains the user ID stored in the identity provider. Use this variable in Power Automate flows to call APIs that take the UserID as a value.

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 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 pass 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 signs in. You can pass this variable to Power Automate flows so they can connect to back-end APIs and fetch user information, or 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 by using the Sign in system topic. Require users to sign in must be turned on.

• Initializer indicates that when a user isn't signed in, and they reach a point in the conversation that uses authentication variables, they're prompted to sign in.

Teams plan

If you configure your agent with either Authenticate with Microsoft or Manual authentication, you have a set of authentication variables available in your topics. Learn more in Configure user authentication in Copilot Studio.

The following table compares authentication variable availability by authentication configuration option:

Authentication variable	No authentication	Authenticate with Microsoft	Manual
User.DisplayName	Not available	Available	Available
User.Id	Not available	Available	Available
User.IsLoggedIn	Not available	Not available	Available
User.AccessToken	Not available	Not available	Available

UserDisplayName variable

The User.DisplayName variable contains the user's display name stored in the identity provider. You can use this variable to greet or refer to the customer without them having to explicitly tell it to the agent, making it more personalized.

This field value is obtained from the Microsoft Entra ID name claim. For OAuth providers, this value is stored in the name claim. Copilot Studio automatically extracts this field into the variable, so ensure you have profile as part of your authentication scope setup.

UserID variable

The User.Id variable contains the user's ID stored in the identity provider. Power Automate flows can use this value to call APIs that take the UserID as a value. This field value is obtained from the Microsoft Entra ID sub claim. For OAuth providers, this value is stored in the sub claim. Copilot Studio automatically extracts this field into the variable.

Warning

The User.DisplayName and User.Id variables might not be filled, and instead these variables might be empty strings depending on the user configuration in the identity provider. Test with a user from your identification provider to ensure your topics work correctly, even if these variables are empty.

IsLoggedIn variable

The User.IsLoggedIn variable indicates whether the user is signed in (either as a result of signing in or already being signed in, also known as the log-in success path) or not signed in (which would result in the log-in failure path).

User.IsLoggedIn is a Boolean variable containing the signed-in status of the user. You can use this variable to create branching logic in your topics that checks for a successful sign-in (for example, in the template already provided as part of adding the Authenticate node), or to opportunistically fetch user information only if the user is signed in.

User.AccessToken variable

The User.AccessToken variable contains the user's token, obtained after the user signs in. Pass this variable to Power Automate flows so they can connect to back-end APIs and fetch the user's information, or take actions on the user's behalf.

Warning

Make sure you pass the User.AccessToken variable only to trusted sources. It contains user authentication information, which, if compromised, could harm the user.

Don't use User.AccessToken inside Message nodes, or on flows that you don't trust.

Testing authentication variables

By default, the Test bot pane uses the account of the currently signed-in user to populate the User.DisplayName and User.Id variables. However, when testing topics that use authentication, you might want to use other values for these variables (or even a blank value).

For example, you might want to test how special characters are used, or what happens if the variable is empty.

The following table lists the commands to populate these variables. These commands only apply to the Test bot pane; you can't use them in a published agent deployed to a channel.

Enter the desired command into the Test bot pane just as you would if you were normally chatting with the agent. You receive a confirmation message from the agent if you're successful. If your agent doesn't use authentication, you receive an error.

If you reset the Test bot pane (or you make changes to a topic that cause the Test bot to reset automatically), you need to send the commands again.

Variable	Custom value command	Empty (blank) value command
User.DisplayName	/debug set bot.UserDisplayName "Value"	/debug set bot.UserDisplayName ""
User.Id	Not available	/debug set bot.UserID ""

Important

For security reasons, you can't populate the User.Id variable with a custom value (other than an empty or blank value).