ENABLE-AUTHENTICATION.md

Enable user authentication

Copilot Studio Kit supports testing custom Agents with user authentication using Entra ID v2 (Azure Active Directory v2) as the service provider with SSO enabled. These instructions include all the steps required to enable end user authentication on your agent in Copilot Studio, create and configure the required applications in Azure Portal and finally create the agent configuration in Copilot Studio Kit.

Prerequisites

• Copilot Studio Kit has been installed

Create authentication application for Copilot Studio Kit

Related instructions in Microsoft Learn: https://learn.microsoft.com/en-us/microsoft-copilot-studio/configure-sso?tabs=classic#create-an-app-registration-in-microsoft-entra-id-for-your-custom-canvas

1. Navigate to Azure Portal
2. Navigate to App registrations in Azure Portal
3. Select New registration
4. Enter a name for your application. We will call this application "KitAuthApp".
5. Under Supported account types, select Accounts in any organizational tenant (Any Microsoft Entra ID directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox).
6. Leave the Redirect URI section blank for now. We will be entering that information later in the next steps.
7. Select Register, you will be sent to the "Overview"-page of your new application.
8. Make note of the "Directory (tenant) ID" and "Application (client) ID". We will need these when creating agent registration in Copilot Studio Kit and associating the Copilot Studio with the Copilot Studio Kit app.
9. Expand Manage and select Authentication
10. Under Platform configurations, select Add a platform, and then select Single-page application.
11. Under Redirect URIs, enter your Dataverse environment URL (https://<hostname>.crm.dynamics.com/)
12. In the Implicit grant and hybrid flows-section, turn on both Access tokens (used for implicit flows) and ID tokens (used for implicit and hybrid flows).
13. Select Configure to confirm your changes.
14. Go to API Permissions.
15. Select Grant admin consent for , and then select Yes. If the button isn't available, you might need to ask a tenant administrator to do enter it for you.

Create authentication application for Copilot Studio

Related instructions in Microsoft Learn: https://learn.microsoft.com/en-us/microsoft-copilot-studio/configuration-authentication-azure-ad

1. Navigate to Azure Portal
2. Navigate to App registrations in Azure Portal
3. Select New registration
4. Enter a name for your application. We will call this application "CopilotStudioAuthApp".
5. Under Supported account types, select Accounts in any organizational tenant (Any Microsoft Entra ID directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox).
6. Leave the Redirect URI section blank for now. We will be entering that information later in the next steps.
7. Select Register, you will be sent to the "Overview"-page of your new application.
8. Make note of the "Directory (tenant) ID" and "Application (client) ID". We will need these when enabling end user authentication in Copilot Studio.
9. Expand Manage and select Authentication
10. Under Platform configurations, select Add a platform, and then select Web.
11. Under Redirect URIs, enter "https://token.botframework.com/.auth/web/redirect", and select Configure. This action takes you back to the Platform configurations page.
12. Under Redirect URIs for the Web platform, select Add URI.
13. Enter "https://europe.token.botframework.com/.auth/web/redirect", and select Save.
14. In the Implicit grant and hybrid flows section, select both Access tokens (used for implicit flows) and ID tokens (used for implicit and hybrid flows).
15. Select Save
16. Under Manage, select Certificates & secrets.
17. In the Client secrets section, select New client secret.
18. Enter a description. Preferably something descriptive.
19. Select the expiry period.
20. Select Add to create the secret.
21. Make note of the secret's "Value". We will need this when enabling end user authentication in Copilot Studio.
22. Under Manage, select API permissions.
23. Select Add a permission, and then select Microsoft Graph.
24. Select Delegated permissions.
25. Expand OpenId permissions and turn on "openid" and "profile".
26. (Optional, required for SharePoint knowledge source) Expand Files and turn on Files.Read.All
27. (Optional, required for SharePoint knowledge source) Expand Sites and turn on Sites.Read.All
28. Select Add permissions
29. Select Grant admin consent for , and then select Yes. If the button isn't available, you might need to ask a tenant administrator to do enter it for you.
30. Select Expose an API and select Add a scope
31. Select Save and continue
32. In Scope name, enter descriptive name. We will use copilot.studio.scope.
33. Under Who can consent?, select Admins and users
34. Enter descriptive name and description in Admin consent display name and Admin consent description
35. Ensure State is Enabled
36. Select Add scope
37. Make note of the full scope name under Scopes. We will need this later when enabling end user authentication in Copilot Studio. (api://xxx/copilot.studio.scope)
38. Select Add a client application
39. In Client ID, enter the Client ID of the "KitAuthApp" that we created earlier.
40. Verify that the scope in Authorized scopes is the one that you created earlier (copilot.studio.scope). Turn on (check) that scope.
41. Select Add application.

Enable end user authentication on your custom agent

Related instructions in Microsoft Learn: https://learn.microsoft.com/microsoft-copilot-studio/configure-sso and https://learn.microsoft.com/microsoft-copilot-studio/nlu-generative-answers-sharepoint-onedrive#advanced-authentication-scenarios

1. Navigate to Copilot Studio
2. Open Settings
3. Select Security
4. Select Authentication
5. Select Authenticate manually
6. Enable Require users to sign in
7. Do not change Redirect URL, make sure Service provider is Azure Active Directory v2.
8. In Client ID, enter the Client ID of CopilotStudioAuthApp
9. In Client secret, enter the Client secret created for CopilotStudioAuthApp
10. In Token exchange URL, enter the full name of the scope (api://xxx/copilot.studio.scope) that we created for CopilotStudioAuthApp
11. (Optional, required for SharePoint knowledge source) In Scopes, add Files.Read.All
12. (Optional, required for SharePoint knowledge source) In Scopes, add Sites.Read.All
13. Click Save, then Save again from the dialog.
14. Close Settings
15. Click Publish, then Publish again from the dialog.

Create agent configuration with end user authentication enabled

Related instructions in the Copilot Studio Kit repository: https://github.com/microsoft/Power-CAT-Copilot-Studio-Kit/blob/main/CONFIGURE_COPILOTS.md

1. Navigate to Copilot Studio Kit
2. Select Agents from the navigation.
3. Click New
4. Enter Name
5. From Configuration Type(s) select Test Automation
6. Fill Direct Line Settings-section, enter either Token Endpoint or enable Channel Security and enter Direct Line secret.
7. In User Authentication-section, for User Authencation select Entra ID v2
8. For Client ID, enter the Client ID of KitAuthApp
9. For Tenant ID enter the Directory ID of KitAuthApp
10. For Scope, enter the full scope name (api://xxx/copilot.studio.scope) created for CopilotStudioAuthApp
11. Click Save & Close

Now you are ready to start testing your agent with end user authentication enabled!

To recap what we did here:

• Created app registration specifically for Copilot Studio Kit authentication purpose
• Created app registration for Copilot Studio authentication
• Linked the applications so that Copilot Studio Kit is able to authenticate to Direct Line via Copilot Studio authentication application
• Enabled authentication in custom agent in Copilot Studio
• Created agent configuration in Copilot Studio Kit with end user authentication enabled