Eenmalige aanmelding met Microsoft Entra ID configureren

Copilot Studio ondersteunt eenmalige aanmelding (SSO) Met eenmalige aanmelding (SSO) kunnen copilots op uw website klanten aanmelden als ze al zijn aangemeld bij de pagina of app waarop de copilot is geïmplementeerd.

De copilot wordt bijvoorbeeld op het bedrijfsintranet gehost of in een app waarbij de gebruiker al is aangemeld.

Er zijn vier hoofdstappen om SSO te configureren voor Copilot Studio:

1. Maak een app-registratie maken in Microsoft Entra ID voor uw aangepaste canvas.

2. Een aangepast bereik voor uw copilot definiëren.

3. Configureer verificatie in Copilot Studio om SSO in te schakelen.

4. Configureer de HTML-code voor uw aangepaste canvas om SSO in te schakelen.

Vereisten

• De verificatie van eindgebruikers inschakelen met Microsoft Entra ID
• Een verificatieonderwerp toevoegen aan uw copilot
• Een aangepast canvas gebruiken

Notitie

Als u SSO wilt configureren met andere OAuth 2.0-providers, raadpleegt u Eenmalige aanmelding configureren met generieke OAuth-providers.

Ondersteunde kanalen

De volgende tabel bevat details over de kanalen die momenteel SSO ondersteunen. U kunt ondersteuning voorstellen voor extra kanalen bij het Microsoft Copilot Studio-ideeënforum.

Channel	Ondersteund
Azure Bot Service-kanalen	Niet ondersteund
Aangepaste website	Ondersteund
Demowebsite	Niet ondersteund
Facebook	Niet ondersteund
Microsoft Teams1	Ondersteund
Mobiele app	Niet ondersteund
Omnichannel voor Customer Service2	Ondersteund

¹Als ook het Teams-kanaal is ingeschakeld, moet u de configuratie-instructies in de documentatie Eenmalige aanmelding met Microsoft Entra ID configureren voor copilots in Microsoft Teams volgen. Als u de SSO-instellingen van Teams niet configureert volgens de instructies op die pagina, mislukt de verificatie van uw gebruikers altijd wanneer ze het Teams-kanaal gebruiken.

² Alleen het livechat-kanaal wordt ondersteund. Meer informatie, zie Overdracht aan Dynamics 365 Customer Service configureren.

Belangrijk

SSO wordt momenteel niet ondersteund wanneer een copilot:

• Is gepubliceerd naar een Power Apps-portal.
• Gepubliceerd op een SharePoint-website als een iframe.

Eenmalige aanmelding wordt echter wel ondersteund voor een copilot die op een SharePoint-website is gepubliceerd als een SPFx-component.

Webapp

App-registraties maken voor uw aangepaste website

Om SSO in te schakelen, moet u twee afzonderlijke app-registraties maken:

• Een verificatieapp-registratie, waarmee Microsoft Entra ID-gebruikersverificatie voor uw copilot mogelijk wordt gemaakt
• Een registratie voor een canvas-app waarmee SSO voor uw aangepaste webpagina wordt ingeschakeld

Om veiligheidsredenen raden we u af dezelfde app-registratie opnieuw te gebruiken voor zowel uw copilot als uw aangepaste website.

1. Volg de instructies in Gebruikersverificatie configureren met Microsoft Entra ID voor het maken van een verificatieapp-registratie.

2. Volg de instructies voor het maken van een registratie van een verificatie-app om een ​tweede app-registratie te maken die dient als uw canvas-app-registratie.

3. Voeg de registratie-id van de canvas-app toe aan de registratie van de verificatie-app.

URL voor uitwisselen van token toevoegen

Om de Microsoft Entra ID-verificatie-instellingen in Copilot Studio bij te werken, moet u de URL voor tokenuitwisseling toevoegen om uw app en Copilot Studio informatie te laten uitwisselen.

1. Ga in de Azure-portal op de blade voor registratie van de verificatie-app naar Een API beschikbaar maken.

2. Selecteer onder Bereik het pictogram Kopiëren naar klembord.

3. Selecteer in Copilot Studio in het navigatiemenu onder instellingen Beveiliging en vervolgens de tegel Verificatie.

4. Plak bij URL voor tokenuitwisseling (vereist voor SSO) het bereik dat u eerder hebt gekopieerd.

5. Selecteer Opslaan.

Uw registratie voor een canvas-app configureren

1. Nadat u uw registratie voor een canvas-app hebt gemaakt, gaat u naar Verificatie en selecteert u vervolgens Een platform toevoegen.

2. Selecteer onder Platformconfiguraties Een platform toevoegen en selecteer vervolgens Web.

3. Voer onder Omleidings-URI's de URL voor uw webpagina in, bijvoorbeeld http://contoso.com/index.html.

   

4. Schakel onder de sectie Impliciete toekenning en hybride stromen zowel Toegangstokens (gebruikt voor impliciete stromen) als Id-tokens (gebruikt voor impliciete en hybride stromen) in.

5. Selecteer Configureren.

Zoek de eindpunttoken van uw copilot

1. Open in Copilot Studio uw copilot en selecteer vervolgens Kanalen.

2. Selecteer Mobiele app.

3. Selecteer onder Tokeneindpunt de optie Kopiëren.

   

Eenmalige aanmelding configureren in uw webpagina

Gebruik de code die in de GitHub-opslagplaats van Copilot Studio wordt geboden om een webpagina te maken voor de omleidings-URL. Kopieer de code uit de GitHub-opslagplaats en wijzig deze met behulp van de volgende instructies.

Notitie

De code in de GitHub-repository vereist dat de gebruiker een aanmeldingsknop selecteert of zich vanaf een andere site aanmeldt. Om automatisch aanmelden mogelijk te maken, voegt u de volgende code toe aan het begin van aysnc function main():

    (async function main() {
        if (clientApplication.getAccount() == null) {
           await clientApplication.loginPopup(requestObj).then(onSignin).catch(function (error) {console.log(error) });
        }
        // Add your BOT ID below 
        var theURL =

1. Ga naar de pagina Overzicht in Azure-portal en kopieer de waarde voor Toepassings-id (client) en Directory-id (tenant) uit uw registratie voor een canvas-app.

   

2. De Microsoft-verificatiebibliotheek (MSAL) configureren:

   • Wijs clientId toe aan uw Client-id van toepassing.
   • Wijs authority toe aan https://login.microsoftonline.com/ en voeg uw (Tenant-)id van de map toe aan het einde.

   Bijvoorbeeld:

   var clientApplication;
       (function (){
       var msalConfig = {
           auth: {
               clientId: '00001111-aaaa-2222-bbbb-3333cccc4444',
               authority: 'https://login.microsoftonline.com/7ef988bf-xxxx-51af-01ab-2d7fd011db47'     
           },
   

3. Stel de variabele theURL in op de eerder gekopieerde URL van het tokeneindpunt. Bijvoorbeeld:

   (async function main() {
   
       var theURL = "https://<token endpoint URL>"
   

4. Bewerk de waarde van userId om een aangepast voorvoegsel op te nemen. Bijvoorbeeld:

   var userId = clientApplication.account?.accountIdentifier != null ? 
           ("My-custom-prefix" + clientApplication.account.accountIdentifier).substr(0, 64) 
           : (Math.random().toString() + Date.now().toString()).substr(0,64);
   

5. Sla uw wijzigingen op.

Uw copilot via uw webpagina testen

1. Open uw webpagina in uw browser.

2. Selecteer Aanmelden.

   

   Opmerking

   Als uw browser pop-ups blokkeert of als u een incognito- of privé-browservenster gebruikt, wordt u gevraagd in te loggen. Anders wordt de aanmelding voltooid met behulp van een validatiecode.

   Er wordt een nieuw browsertabblad geopend.

3. Schakel over naar het nieuwe tabblad en kopieer de validatiecode.

4. Schakel terug naar het tabblad met uw copilot en plak de validatiecode in het copilotgesprek.

Gerelateerde inhoud

• Azure-app-registratie

Klassiek

Technisch overzicht

De volgende afbeelding laat zien hoe een gebruiker wordt aangemeld zonder een aanmeldingsprompt (SSO) te zien in Copilot Studio:

1. De copilot-gebruiker voert een zin in die een aanmeldingsonderwerp triggert. Het aanmeldingsonderwerp is om de gebruiker aan te melden en het geverifieerde token (User.AccessToken-variabele) van de gebruiker te gebruiken.

2. Copilot Studio verzendt een aanmeldingsprompt zodat de gebruiker zich kan aanmelden bij zijn/haar geconfigureerde identiteitsprovider.

3. Het aangepaste canvas van de copilot onderschept de aanmeldingsaanwijzing en vraagt om een namens-token (on behalf of, OBO) van Microsoft Entra ID. Het canvas stuurt het token naar de copilot.

4. Na ontvangst van het OBO-token wisselt de copilot het OBO-token in voor een 'toegangstoken' en vult de AuthToken-variabele in met de waarde van het toegangstoken. De variabele IsLoggedIn wordt nu ook ingesteld.

Een appregistratie maken in Microsoft Entra ID voor uw aangepaste canvas

Om SSO in te schakelen, hebt u twee afzonderlijke app-registraties nodig:

• Eén voor uw copilot om gebruikersverificatie in te schakelen met Microsoft Entra ID.
• Eén voor uw aangepaste canvas om SSO in te schakelen.

Belangrijk

U kunt dezelfde app-registratie niet opnieuw gebruiken voor zowel de gebruikersverificatie van uw copilot als uw aangepaste canvas.

Een app-registratie maken voor het canvas van de copilot

1. Meld u aan bij de Azure-portal.

2. Ga naar App-registraties, door het pictogram te selecteren of te zoeken in de bovenste zoekbalk.

   

3. Selecteer Nieuwe registratie.

   

4. Geef een naam op voor de registratie. Het kan handig zijn om de naam te gebruiken van de copilot waarvan u het canvas registreert en 'canvas' in de naam op te nemen om het te kunnen onderscheiden van de app-registratie voor verificatie.

   Als uw copilot bijvoorbeeld ′Contoso-verkoophulp′ heet, kunt u de app-registratie een naam geven als ContosoSalesCanvas of iets soortgelijks.

5. Selecteer onder Ondersteunde accounttypen de optie Accounts in een organisatietenant (alle Microsoft Entra ID-directory's - multitenant) en persoonlijke Microsoft-accounts (zoals Skype, Xbox).

6. Laat de sectie Omleidings-URI leeg voor nu, aangezien u die gegevens in de volgende stappen invoert. Selecteer Registreren.

   

7. Zodra de registratie is voltooid, wordt de pagina Overzicht geopend. Ga naar Manifest. Bevestig dat accessTokenAcceptedVersion ingesteld op 2. Als dit niet het geval is, wijzigt u dit in 2 en selecteert u vervolgens Opslaan.

De omleidings-URL toevoegen

1. Ga met de registratie geopend naar Verificatie en selecteer vervolgens Een platform toevoegen.

   

2. In de blade Platformen configureren selecteert u Web.

   

3. Voeg onder Omleidings-URI's de volledige URL toe voor de pagina waar uw chatcanvas wordt gehost. Onder de sectie Impliciete toewijzing schakelt u de selectievakjes Id-tokens en Toegangstokens in.

4. Selecteer Configureren om uw wijzigingen te bevestigen.

   

5. Ga naar API-machtigingen. Selecteer Beheerderstoestemming verlenen voor <uw tenantnaam> en Ja.

   Belangrijk

   Als u wilt voorkomen dat gebruikers voor elke toepassing toestemming moeten geven, moet een globale beheerder, toepassingsbeheerder of cloudtoepassingsbeheerder tenantbrede toestemming verlenen aan uw app-registraties.

   

Een aangepast bereik voor uw copilot definiëren

Definieer een aangepast bereik door een API voor de canvasapp-registratie binnen de verificatieapp-registratie beschikbaar te maken. Bereiken stellen u in staat om gebruikers- en beheerdersrollen en toegangsrechten te bepalen.

In deze stap maakt u een vertrouwensrelatie tussen de verificatieapp-registratie voor verificatie en de app-registratie voor uw aangepaste canvas.

1. Open de app-registratie die u hebt gemaakt bij het configureren van verificatie.

2. Ga naar API-machtigingen en zorg ervoor dat de juiste machtigingen voor uw copilot zijn toegevoegd. Selecteer Beheerderstoestemming verlenen voor <uw tenantnaam> en Ja.

   Belangrijk

   Als u wilt voorkomen dat gebruikers voor elke toepassing toestemming moeten geven, moet een globale beheerder, toepassingsbeheerder of cloudtoepassingsbeheerder tenantbrede toestemming verlenen aan uw app-registraties.

3. Ga naar Een API beschikbaar maken en selecteer Een bereik toevoegen.

   

4. Voer een naam in voor het bereik, samen met de weergave-informatie die aan gebruikers moet worden getoond wanneer ze naar het SSO-scherm gaan. Selecteer Bereik toevoegen.

   

5. Selecteer Een clienttoepassing toevoegen.

6. Geef de toepassings-id (client) van de pagina Overzicht voor de registratie van de canvas-app op in het veld Klant-id. Schakel het selectievakje in voor het vermelde bereik dat u hebt gemaakt.

7. Selecteer Toepassing toevoegen.

Verificatie in Copilot Studio configureren om SSO in te schakelen

De URL voor tokenuitwisseling op de Copilot Studio-pagina voor verificatieconfiguratie wordt gebruikt om het OBO-token uit te wisselen voor het aangevraagde toegangstoken via het bot framework.

Copilot Studio roept Microsoft Entra ID aan om de daadwerkelijke uitwisseling uit te voeren.

1. Aanmelden bij Copilot Studio.

2. Bevestig dat u de copilot hebt geselecteerd waarvoor u verificatie wilt inschakelen door het copilot-pictogram in het bovenste menu te selecteren en de juiste copilot te kiezen.

3. Selecteer in het navigatiemenu onder Instellingen de optie Beveiliging. Selecteer vervolgens de kaart Verificatie.

   

4. Voer de volledige URI van het blade Een API beschikbaar maken voor de registratie van de authenticatie-app van de copilot in het veld URL voor uitwisseling van tokens in. De URI heeft de indeling van api://1234-4567/scope.name.

   

   

5. Selecteer Opslaan en publiceer de copilotcontent.

De HTML-code voor uw aangepaste canvas configureren om SSO in te schakelen

Werk de aangepaste canvaspagina bij waar de copilot zich bevindt om de aanmeldingskaartaanvraag te onderscheppen en het OBO-token uit te wisselen.

1. Configureer MSAL (Microsoft Authentication Library) door de volgende code toe te voegen aan een code <script> in de sectie <head>.

2. Werk clientId bij met de toepassings-id (client) voor de canvasapp-registratie. Vervang <Directory ID> door de directory-id (tenant). Deze id's krijgt u van de pagina Overzicht voor de canvasapp-registratie.

   <head>
    <script>
      var clientApplication;
        (function () {
          var msalConfig = {
              auth: {
                clientId: '<Client ID [CanvasClientId]>',
                authority: 'https://login.microsoftonline.com/<Directory ID>'
              },
              cache: {
                cacheLocation: 'localStorage',
                storeAuthStateInCookie: false
              }
          };
          if (!clientApplication) {
            clientApplication = new Msal.UserAgentApplication(msalConfig);
          }
        } ());
    </script>
   </head>
   

3. Voeg het volgende <script> in de sectie <body> in. Dit script roept een methode aan om de resourceUrl op te halen en wisselt uw huidige token in voor een token dat wordt aangevraagd door de OAuth-prompt.

   <script>
   function getOAuthCardResourceUri(activity) {
     if (activity &&
          activity.attachments &&
          activity.attachments[0] &&
          activity.attachments[0].contentType === 'application/vnd.microsoft.card.oauth' &&
          activity.attachments[0].content.tokenExchangeResource) {
            // asking for token exchange with Microsoft Entra ID
            return activity.attachments[0].content.tokenExchangeResource.uri;
      }
   }
   
   function exchangeTokenAsync(resourceUri) {
     let user = clientApplication.getAccount();
      if (user) {
        let requestObj = {
          scopes: [resourceUri]
        };
        return clientApplication.acquireTokenSilent(requestObj)
          .then(function (tokenResponse) {
            return tokenResponse.accessToken;
            })
            .catch(function (error) {
              console.log(error);
            });
            }
            else {
            return Promise.resolve(null);
      }
   }
   </script>
   

4. Voeg het volgende <script> in de sectie <body> in. In de main-methode voegt deze code een voorwaarde toe aan uw store, met de unieke id van uw copilot. Daarnaast wordt een unieke id als uw userId-variabele gegenereerd.

5. Werk <COPILOT ID> bij met de id van uw copilot. U kunt de id van uw copilot bekijken door naar het tabblad Kanalen te gaan voor de copilot die u gebruikt en Mobiele app te selecteren in de Copilot Studio-portal.

   <script>
       (async function main() {
   
           // Add your COPILOT ID below 
           var BOT_ID = "<BOT ID>";
           var theURL = "https://powerva.microsoft.com/api/botmanagement/v1/directline/directlinetoken?botId=" + BOT_ID;
   
           const {
               token
           } = await fetchJSON(theURL);
   
           var directline = await fetchJSON(regionalChannelSettingsURL).then(res=> res.channelUrlsById.directline); 
   
           const directLine = window.WebChat.createDirectLine({
               domain: `${directline}v3/directline`,
               token
           });
   
           var userID = clientApplication.account?.accountIdentifier != null ?
               ("Your-customized-prefix-max-20-characters" + clientApplication.account.accountIdentifier).substr(0, 64) :
               (Math.random().toString() + Date.now().toString()).substr(0, 64); // Make sure this will not exceed 64 characters 
           const store = WebChat.createStore({}, ({
               dispatch
           }) => next => action => {
               const {
                   type
               } = action;
               if (action.type === 'DIRECT_LINE/CONNECT_FULFILLED') {
                   dispatch({
                       type: 'WEB_CHAT/SEND_EVENT',
                       payload: {
                           name: 'startConversation',
                           type: 'event',
                           value: {
                               text: "hello"
                           }
                       }
                   });
                   return next(action);
               }
               if (action.type === 'DIRECT_LINE/INCOMING_ACTIVITY') {
                   const activity = action.payload.activity;
                   let resourceUri;
                   if (activity.from && activity.from.role === 'bot' &&
                       (resourceUri = getOAuthCardResourceUri(activity))) {
                       exchangeTokenAsync(resourceUri).then(function(token) {
                           if (token) {
                               directLine.postActivity({
                                   type: 'invoke',
                                   name: 'signin/tokenExchange',
                                   value: {
                                       id: activity.attachments[0].content.tokenExchangeResource.id,
                                       connectionName: activity.attachments[0].content.connectionName,
                                       token,
                                   },
                                   "from": {
                                       id: userID,
                                       name: clientApplication.account.name,
                                       role: "user"
                                   }
                               }).subscribe(
                                   id => {
                                       if (id === 'retry') {
                                           // copilot was not able to handle the invoke, so display the oauthCard
                                           return next(action);
                                       }
                                       // else: tokenexchange successful and we do not display the oauthCard
                                   },
                                   error => {
                                       // an error occurred to display the oauthCard
                                       return next(action);
                                   }
                               );
                               return;
                           } else
                               return next(action);
                       });
                   } else
                       return next(action);
               } else
                   return next(action);
           });
   
           const styleOptions = {
   
               // Add styleOptions to customize Web Chat canvas
               hideUploadButton: true
           };
   
           window.WebChat.renderWebChat({
                   directLine: directLine,
                   store,
                   userID: userID,
                   styleOptions
               },
               document.getElementById('webchat')
           );
       })().catch(err => console.error("An error occurred: " + err));
   </script>
   

Volledige voorbeeldcode

Voor meer informatie kunt u de volledige voorbeeldcode inclusief de MSAL en al ingevoegde voorwaardelijke scripts opslaan op onze GitHub-opslagplaats.