Configure single sign-on with Microsoft Entra ID

Create app registrations for your custom website

To configure SSO, create two separate app registrations:

• An authentication app registration for Microsoft Entra ID user authentication in your agent.
• A canvas app registration for your custom web page.

For security reasons, don't reuse the same app registration for both your agent and your custom website.

1. To create an authentication app registration, follow the instructions in Configure user authentication with Microsoft Entra ID.

2. Create a second app registration to serve as your canvas app registration.

Add token exchange URL

Use the full scope URI that the authentication app registration exposes as the token exchange URL. If you didn't create a custom scope, follow Configure user authentication with Microsoft Entra ID first.

1. In the Azure portal on your authentication app's registration page, go to Expose an API.

2. Under Scopes, select the Copy to clipboard icon.

3. In Copilot Studio, in the navigation menu under Settings, select Security, and then select the Authentication tile.

4. For Token exchange URL (required for SSO), paste the scope you copied earlier.

5. Select Save, and then publish your agent.

Authorize the canvas app to use the authentication app's scope

1. In the Azure portal, open your canvas app registration and go to Overview.

2. Copy the Application (client) ID value under Essentials.

3. Open your authentication app registration, and then select Manage > Expose an API.

4. Under Authorized client applications, select Add a client application.

5. In Client ID, paste the canvas app's client ID.

6. Under Authorized scopes, select the scope you created for token exchange, and then select Add application.

Configure your canvas app registration

1. Open your canvas app registration and go to Authentication.

2. Under Platform configurations, select Add a platform, and then select SPA.

3. Under Redirect URIs, enter the URL for your web page. For example, https://www.contoso.com/index.html.

4. 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).

5. Select Configure.

Configure SSO in your web page

Use the complete Microsoft Entra ID SSO sample, including its libraries and Web Chat middleware. Follow the sample's README and update the configuration placeholders in index.html.

1. In the Azure portal, open your canvas app registration.

2. On Overview, copy the Application (client) ID and Directory (tenant) ID.

   

3. Replace the sample's client ID and tenant ID placeholders with the values from the canvas app registration. Don't use the authentication app's client ID here.

4. Replace the token endpoint placeholder with the agent's token endpoint URL.

5. If you customize the user ID, keep it within the sample's 64-character limit.

6. Save your changes.

7. Host the page at the redirect URL you registered. Sign in by using the sample's sign-in button, and then start a conversation that requires authentication.

   When token exchange succeeds, the agent doesn't ask you to sign in again or copy a validation code into the chat. If it does, check the canvas app identifiers, authorized scope, token exchange URL, and agent publication.

   Note

   The sample's sign-in button establishes the initial signed-in session. In production, your app must manage that initial sign-in. Keep the fallback sign-in card available if token exchange fails.

The following procedures configure a custom website canvas for an agent created in the Teams plan. They aren't the configuration procedure for the Microsoft Teams channel.

Technical overview

SSO in a custom canvas uses the following token-exchange flow:

1. The agent user enters a phrase that triggers a sign-in topic. The sign-in topic is designed to sign the user in and use the user's authenticated token (User.AccessToken variable).

2. Copilot Studio sends a sign-in prompt to allow the user to sign in by using their configured identity provider.

3. The agent's custom canvas intercepts the sign-in prompt and requests an on-behalf-of (OBO) token from Microsoft Entra ID. The canvas sends the token to the agent.

4. The agent exchanges the OBO token for an access token and stores it in User.AccessToken. The User.IsLoggedIn variable is also set at this time.

Create an app registration in Microsoft Entra ID for your custom canvas

To configure SSO, you need two separate app registrations:

• One for your agent's user authentication with Microsoft Entra ID.
• One for SSO in your custom canvas.

Create an app registration for the agent's canvas

1. Sign in to the Azure portal.

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

3. Select New registration.

4. Enter a name for the registration. Use the name of the agent whose canvas you're registering and include "canvas" to help separate it from the app registration for authentication.

   For example, if your agent is called "Contoso sales help," you might name the app registration as "ContosoSalesCanvas" or something similar.

5. Under Supported account types, select Accounts in any organizational tenant (Any Microsoft Entra ID directory - Multitenant) and personal Microsoft accounts (for example, Skype, XBOX).

6. Leave the Redirect URI section blank for now, as you enter that information in the next steps. Select Register.

7. After the registration is completed, it opens to the Overview page. Go to Manifest. Confirm that accessTokenAcceptedVersion is set to 2. If it isn't, change it to 2 and then select Save.

Add the redirect URL

1. With the registration open, go to Authentication and then select Add a platform.

2. On the Configure platforms panel, select Web.

3. Under Redirect URIs, add the full URL to the page where your chat canvas is hosted. Under the Implicit grant section, select the Id Tokens and Access Tokens checkboxes.

4. Select Configure to confirm your changes.

5. Go to API Permissions. Select Grant admin consent for <your tenant name> and then Yes.

   Important

   To avoid users having to consent to each application, someone assigned at least the Application Administrator or Cloud Application Administrator role can grant tenant-wide consent to your application registrations.

Define a custom scope for your agent

Define a custom scope on the authentication app registration, and authorize the canvas app to use it. Learn more about scopes in the Microsoft identity platform developer glossary.

This step creates a trust relationship between the authentication app registration for authentication and the app registration for your custom canvas.

1. Open the app registration that you created when you configured authentication.

2. Go to API Permissions and ensure that you add the correct permissions for your agent. Select Grant admin consent for <your tenant name> and then Yes.

   Important

   To avoid users having to consent to each application, someone assigned at least the Application Administrator or Cloud Application Administrator role can grant tenant-wide consent to your application registrations.

3. Go to Expose an API and select Add a scope.

4. Enter a name for the scope, along with the display information that users see when they come to the SSO screen. Select Add scope.

5. Select Add a client application.

6. Enter the Application (client) ID from the Overview page for the canvas app registration into the Client ID field. Select the check box for the listed scope that you created.

7. Select Add application.

Configure authentication in Copilot Studio for SSO

Use Token exchange URL in the Copilot Studio authentication configuration to exchange the OBO token for the requested access token through Bot Framework.

Copilot Studio calls into Microsoft Entra ID to perform the actual exchange.

1. Sign in to Copilot Studio.

2. Open the agent you want to configure.

3. In the navigation menu, under Settings, select Security. Then select the Authentication card.

4. In Token exchange URL, enter the full scope URI from the Expose an API page of the authentication app registration. The format is api://<AuthenticationAppClientId>/<ScopeName>.

5. Select Save and then publish the agent content.

Configure your custom canvas HTML for SSO

Use the complete Microsoft Entra ID SSO sample instead of combining partial script fragments. The sample includes the Microsoft Authentication Library (MSAL) setup, Web Chat middleware, and token-exchange handling.

1. Follow the sample's README to configure the canvas app's Application (client) ID and Directory (tenant) ID.

2. Configure the token endpoint URL for your agent. Don't construct a token endpoint from the agent ID.

3. Keep the sign-in card fallback when silent token acquisition or token exchange fails.

4. Host the page at the redirect URL you registered. Sign in by using the sample's button, and then trigger an agent topic that requires authentication. Confirm that successful token exchange avoids a second sign-in prompt or validation code.

Full sample code

Learn more at the Microsoft Entra ID SSO sample. Use the app registration and configuration instructions that match the version of the sample you deploy.