Kertakirjautumisen määrittäminen Microsoft Entra ID:n avulla

Copilot Studio tukee kertakirjautumista (SSO). SSO:n avulla sivustosi asiakaspalvelijat voivat kirjata asiakkaita sisään, jos he ovat jo kirjautuneet sivulle tai sovellukseen, jossa asiakaspalvelija on otettu käyttöön.

Esimerkiksi asiakaspalvelija isännöidään yrityksen intranetissä tai sovelluksessa, johon käyttäjä on jo kirjautunut.

Kertakirjautumisen Copilot Studioissa määrittämisellä on neljä päävaihetta:

1. Mukautetun kaavion sovelluksen rekisteröinnin luominen Microsoft Entra ID:ssä.

2. Määritä mukautettu vaikutusalue asiakaspalvelija-tunnuksellesi.

3. Todennuksen määrittäminen Copilot Studioissa SSO-kirjautumisen käyttöönottamiseksi.

4. Määritä mukautetun kaavion HTML-koodi mahdollistamaan SSO-kirjautuminen.

edellytykset

• Loppukäyttäjän todennuksen ottaminen käyttöön Microsoft Entra ID:n avulla
• Lisää todennus aihe asiakaspalvelija
• Mukautetun pohjan käyttö

Muistiinpano

Jos haluat määrittää kertakirjautumisen käyttämällä muita OAuth 2.0 -toimittajia, katso kohta Kertakirjautumisen määrittäminen yleisten OAuth-palveluntarjoajien kanssa.

Tuetut kanavat

Seuraavassa taulukossa on esitetty kanavat, jotka tukevat tällä hetkellä SSO:ta. Voit ehdottaa tukea ylimääräisille kanaville Ideat foorumilla Copilot Studio .

Kanava	Tuettu
Azure Bot Service -kanavat	Ei tueta
Mukautettu verkkosivusto	Tuettu
Esittelysivusto	Ei tueta
Facebook	Ei tueta
Microsoft Teams1	Tuettu
Mobiilisovellus	Ei tueta
Customer Servicen monikanava2	Tuettu

1 Jos käytössä on myös Teams-kanava, sinun on noudatettava dokumentaatiossa olevan Microsoft Entra Määritä kertakirjautuminen tunnuksella Microsoft Teams agenteille -määritysohjeita. Jos Teamsin kertakirjautumisasetuksia ei määritetä kyseisen sivun ohjeiden mukaisesti, käyttäjiesi todennus epäonnistuu aina käytettäessä Teams-kanavaa.

² Vain live-keskustelukanavaa tuetaan. Lisätietoja on kohdassa Dynamics 365 Customer Servicen siirron määrittäminen.

Tärkeää

SSO:ta ei tällä hetkellä tueta, kun asiakaspalvelija on ollut joko:

• julkaistu Power Apps portaaliin
• Julkaistu SharePoint verkkosivustolle iframe-kehyksenä.

SSO:ta tuetaan kuitenkin asiakaspalvelija:lle, joka on julkaistu SharePoint verkkosivustolla SPFx-komponenttina.

Verkkosovellus

Sovelluksen rekisteröintien luominen mukautettua verkkosivustoa varten

Jos haluat ottaa SSO-kirjautumisen käyttöön, sinun on luotava kaksi erillistä sovelluksen rekisteröintiä:

• Todennussovelluksen rekisteröinti, joka mahdollistaa Microsoft Entra tunnuskäyttäjän todennuksen asiakaspalvelija
• Pohjaan perustuvan sovelluksen rekisteröinti, joka mahdollistaa SSO-kirjautumisen mukautetulle verkkosivustolle

Emme suosittele saman sovelluksen rekisteröinnin käyttämistä uudelleen sekä asiakaspalvelija että mukautetulle verkkosivustollesi turvallisuussyistä.

1. Lisätietoja todennussovelluksen rekisteröinnin luonnista on kohdassa Käyttäjän todennuksen määrittäminen Microsoft Entra ID:n avulla.

2. Luo pohjaan perustuvan sovelluksen rekisteröintiä vastaava toisen sovelluksen rekisteröinti seuraamalla uudelleen todennussovelluksen rekisteröinnin ohjeita.

3. Lisää pohjaan perustuvan sovelluksen rekisteröintitunnus todennussovelluksen rekisteröintiä varten.

Tunnuksenvaihdon URL-osoitteen lisääminen

Jos haluat päivittää Microsoft Entra ID:n todennusasetukset Copilot Studiossa, lisää tunnuksen vaihdon URL-osoite. Tällöin sovellus ja Copilot Studio voivat jakaa tietoja.

1. Siirry todennussovelluksen rekisteröinti-ikkunan Azure-portaalissa Julkaise ohjelmointirajapinta -kohtaan.

2. Valitse Vaikutusalueet-kohdassa Kopioi leikepöydälle -kuvake.

3. Valitse Copilot Studioin siirtymisvalikossa Asetukset, Suojaus ja sitten Todennus-ruutu.

4. Liitä Tunnuksen vaihdon URL-osoite (vaaditaan kertakirjautumisessa) -kenttään aiemmin kopioimasi vaikutusalue.

5. Valitse Tallenna.

Pohjaan perustuvan sovelluksen rekisteröinnin määrittäminen

1. Kun olet luonut pohjaan perustuvan sovelluksen rekisteröinnin, siirry kohtaan Todennus ja valitse sitten Lisää ympäristö.

2. Valitse Ympäristömääritykset-kohdassa Lisää ympäristö ja valitse sitten Verkko.

3. Syötä Uudelleenohjauksen URI-osoitteet -kohdassa verkkosivuston URL-osoite, esimerkiksi http://contoso.com/index.html.

   

4. Ota Implisiittinen myöntäminen ja hybridityönkulku -osassa käyttöön Käyttöoikeustietueet (käytetään implisiittisiin työnkulkuihin) sekä ID-tunnukset (käytetään implisiittisiin ja hybridityönkulkuihin).

5. Valitse Määritä.

asiakaspalvelija-tunnuksen päätepiste URL-osoitteen etsiminen

1. Avaa Copilot Studio asiakaspalvelija ja valitse sitten Kanavat.

2. Valitse Mobiilisovellus.

3. Valitse Tunnuksen päätepiste -kohdasta Kopioi.

   

SSO-kirjautumisen määrittäminen verkkosivustolle

Luo verkkosivusto uudelleenohjauksen URL-osoitteelle käyttämällä Copilot Studioin GitHub-säilössä annettua koodia. Kopioi koodi GitHub-säilöstä ja muokkaa sitä seuraavien ohjeiden mukaisesti.

Muistiinpano

GitHub-säilön koodi edellyttää, että käyttäjä valitsee sisäänkirjautumispainikkeen tai kirjautuu sisään eri sivuston avulla. Jos haluat ottaa käyttöön automaattisen sisäänkirjauksen, lisää funktion aysnc function main() alkuun seuraava koodi:

    (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. Siirry Yleiskatsaus-sivulle Azure-portaalissa ja kopioi sovelluksen (asiakkaan) tunnus ja hakemiston (vuokraajan) tunnus pohjaan perustuvan sovelluksen rekisteröinnistä.

   

2. Microsoftin todennuskirjaston (MSAL) määrittäminen:

   • Määritä Sovelluksen (asiakas) tunnus -tunnukselle clientId.
   • Määritä authority osoitteelle https://login.microsoftonline.com/ ja lisää loppuun Hakemiston (vuokraaja) tunnus.

   Esimerkki:

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

3. Määritä theURL-muuttuja aiemmin kopioidulle tunnuksen päätepisteen URL-osoitteelle. Esimerkki:

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

4. Muokkaa userId-arvo sisältämään mukautettu etuliite. Esimerkki:

   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. Tallenna tekemäsi muutokset.

Testaa asiakaspalvelija verkkosivullasi

1. Avaa verkkosivu selaimessa.

2. Valitse Sisäänkirjaus.

   

   Huomautus

   Jos selain estää ponnahdusikkunat tai käytät incognito- tai yksityistä selainikkunaa, sinua pyydetään kirjautumaan sisään. Muuten kirjautuminen valmistuu vahvistuskoodin käyttämisellä.

   Uusi selainvälilehti avautuu.

3. Siirry uuteen välilehteen ja kopioi vahvistuskoodi.

4. Siirry takaisin välilehdelle, jossa on asiakaspalvelija, ja liitä vahvistuskoodi asiakaspalvelija-keskusteluun.

Liittyvä sisältö

• Azure-sovelluksen rekisteröinti

Perinteinen

Tekninen yleiskatsaus

Seuraavassa kuvassa näkyy, miten käyttäjä kirjataan sisään ilman kirjautumiskehotusta (SSO) Copilot Studioissa.

1. asiakaspalvelija-käyttäjä kirjoittaa lauseen, joka käynnistää kirjautumisen aihe. Kirjautumisaihe on suunniteltu kirjaamaan käyttäjä sisään ja käyttämään käyttäjän todennettua tunnusta (User.AccessToken-muuttujaa).

2. Copilot Studio lähettää kirjautumiskehotteen, jotta käyttäjä voi kirjautua sisään määritetyllä tunnistetietopalvelullaan.

3. asiakaspalvelija:n mukautettu piirtoalue sieppaa kirjautumiskehotteen ja pyytää ID:ltä Microsoft Entra OBO (on-behalf) -tunnusta. Piirtoalue lähettää tunnuksen asiakaspalvelija.

4. Vastaanotettuaan OBO-tunnuksen asiakaspalvelija vaihtaa OBO-tunnuksen "käyttöoikeustietue" -tunnukseen ja täyttää muuttujan AuthToken käyttämällä käyttöoikeustietue arvoa. Myös muuttuja IsLoggedIn määritetään tässä yhteydessä.

Mukautetun kaavion sovelluksen rekisteröinnin luominen Microsoft Entra ID:ssä

Jos haluat ottaa SSO-kirjautumisen käyttöön, tarvitset kaksi erillistä sovelluksen rekisteröintiä:

• Yksi asiakaspalvelija:lle, jotta käyttäjän todennus ID: Microsoft Entra llävoidaan ottaa käyttöön.
• Yksi mukautettua kaaviota varten, joka ottaa käyttöön SSO-kirjautumisen.

Tärkeää

Et voi käyttää samaa sovelluksen rekisteröintiä uudelleen sekä asiakaspalvelija-käyttäjän todennuksessa että mukautetussa piirtoalustassa.

Luo sovelluksen rekisteröinti asiakaspalvelija canvasille

1. Kirjaudu sisään Azure-portaaliin.

2. Siirry Sovellusten rekisteröinnit -kohtaan valitsemalla kuvake tai tekemällä haku ylähakupalkissa.

   

3. Valitse Uusi rekisteröinti.

   

4. Anna rekisteröinnille nimi. Voi olla hyödyllistä käyttää sen asiakaspalvelija nimeä, jonka kangasta olet rekisteröimässä, ja sisällyttää "canvas", jotta se voidaan erottaa sovelluksen rekisteröinnistä todennusta varten.

   Jos esimerkiksi asiakaspalvelija on nimeltään Contoso Sales Help, voit antaa sovelluksen rekisteröinnille nimen ContosoSalesCanvas tai jotain vastaavaa.

5. Valitse kohdassa Tuetut tilityypit Tilit missä tahansa organisaation vuokraajassa (Mikä tahansa Microsoft Entra ID -hakemisto – palveluna tarjottava sovellus) ja henkilökohtaiset Microsoft-tilit (kuten Skype, Xbox).

6. Jätä Uudelleenohjauksen URI -osa vielä tyhjäksi, koska syötät kyseiset tiedot seuraavissa vaiheissa. Valitse Rekisteröi.

   

7. Kun rekisteröinti on valmis, Yleiskatsaus-sivu avautuu. Siirry kohtaan Luettelo. Vahvista, että accessTokenAcceptedVersion-arvo on 2. Jos näin ei ole, muuta sen arvoksi 2 ja valitse sitten Tallenna.

Uudelleenohjauksen URL-osoitteen lisääminen

1. Kun rekisteröinti on auki, siirry kohtaan Todennus ja valitse sitten Lisää ympäristö.

   

2. Valitse Määritä ympäristöjä -ikkunassa Verkko.

   

3. Lisää kohtaan Uudelleenohjauksen URI-osoitteet täysi URL-osoite sille sivulle, jolla keskustelupohjaasi isännöidään. Valitse Implisiittinen myöntäminen -osassa valintaruudut ID-tunnukset ja Käyttöoikeustunnukset.

4. Vahvista muutoksesi valitsemalla Määritä.

   

5. Siirry Ohjelmointirajapintaoikeuksiin. Valitse Myönnä järjestelmänvalvojan suostumus vuokraajalle <your tenant name> ja sitten Kyllä.

   Tärkeä

   Jotta käyttäjien ei tarvitsisi suostua jokaiseen sovellukseen, yleisen järjestelmänvalvojan, sovelluksen järjestelmänvalvojan tai pilvisovelluksen järjestelmänvalvojan on myönnettävä vuokraajanlaajuinen suostumus sovellusrekisteröinneillesi.

   

Määritä mukautettu vaikutusalue asiakaspalvelija

Määritä mukautettu vaikutusalue tarjoamalla ohjelmointirajapinta pohjaan perustuvan sovelluksen rekisteröinnille todennussovelluksen rekisteröinnin sisällä. Vaikutusalueiden avulla voit määrittää käyttäjä- ja järjestelmänvalvojan rooleja sekä käyttöoikeuksia.

Tämä vaihe luo luottamussuhteen todennusta varten luotavan todennussovelluksen rekisteröinnin ja mukautetun pohjasi sovellusrekisteröinnin välille.

1. Avaa sovellusrekisteröinti, jonka loit määrittäessäsi todennuksen.

2. Siirry API-käyttöoikeuksiin ja varmista, että asiakaspalvelija:lle on lisätty oikeat käyttöoikeudet. Valitse Myönnä järjestelmänvalvojan suostumus vuokraajalle <your tenant name> ja sitten Kyllä.

   Tärkeä

   Jotta käyttäjien ei tarvitsisi suostua jokaiseen sovellukseen, yleisen järjestelmänvalvojan, sovelluksen järjestelmänvalvojan tai pilvisovelluksen järjestelmänvalvojan on myönnettävä vuokraajanlaajuinen suostumus sovellusrekisteröinneillesi.

3. Siirry kohtaan Tarjoa ohjelmointirajapintaa ja valitse Lisää vaikutusalue.

   

4. Syötä nimi vaikutusalueelle sekä näyttötiedot, jotka näytetään käyttäjille, kun he saapuvat kertakirjautumisnäyttöön. Valitse Lisää vaikutusalue.

   

5. Valitse Lisää asiakassovellus.

6. Syötä Yleiskatsaus-sivun Sovelluksen (asiakas) tunnus pohjaan perustuvan sovelluksen rekisteröintiä varten Asiakastunnus-kenttään. Valitse luomasi luetellun vaikutusalueen valintaruutu.

7. Valitse Lisää sovellus.

Todennuksen määrittäminen Copilot Studioissa SSO-kirjautumisen käyttöönottamiseksi

Copilot Studioin todennuksenmäärityssivun Tunnuksenvaihdon URL -osoitetta käytetään OBO-tunnuksen vaihtamisessa pyydettyyn käyttöoikeustunnukseen Bot Frameworkin kautta.

Copilot Studio kutsuu Microsoft Entra ID:n suorittamaan varsinaisen vaihdon.

1. Kirjaudu Copilot Studio.

2. Varmista, että olet valinnut asiakaspalvelija, jolle haluat ottaa todennuksen käyttöön, valitsemalla ylävalikosta asiakaspalvelija -kuvakkeen ja valitsemalla oikea asiakaspalvelija.

3. Valitse siirtymisvalikon Asetukset-kohdasta Suojaus. Valitse sitten Todentaminen-kortti.

   

4. Kirjoita asiakaspalvelija:n todennussovelluksen rekisteröinnin Expose an API -terän koko laajuuden URI Token Exchange URL - kenttään . Kanavan URI-osoitteen muoto on api://1234-4567/scope.name.

   

   

5. Valitse Tallenna ja julkaise asiakaspalvelija-sisältö.

Määritä mukautetun pohjasi HTML-koodi mahdollistamaan SSO-kirjautuminen

Päivitä mukautettu canvas-sivu, jossa asiakaspalvelija sijaitsee, jotta voit siepata kirjautumis- kortti pyynnön ja vaihtaa OBO-tunnuksen.

1. Määritä Microsoft Authentication Library (MSAL) lisäämällä seuraava koodi <script>-välilehteen <head>-osassa.

2. Päivitä clientId Sovelluksen (asiakas) tunnus -arvolla pohjaan perustuvan sovelluksen rekisteröintiä varten. Korvaa <Directory ID> arvolla Hakemiston (vuokraaja) tunnus. Saat nämä tunnukset pohjaan perustuvan sovelluksen rekisteröinnin Yleiskatsaus-sivulta.

   <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. Lisää seuraava <skripti> <body>-osaan. Tämä skripti kutsuu menetelmää resourceUrl-osoitteen noutamiseen ja nykyisen tunnuksesi vaihtamiseen OAuth-kehotteen pyytämään tunnukseen.

   <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. Lisää seuraava <skripti> <body>-osaan. Menetelmässä main tämä koodi lisää ehdollisen # storeasiakaspalvelija: n yksilöllisellä tunnisteella. Se luo myös yksilöllisen tunnuksen userId-muuttujaksesi.

5. Päivitä <COPILOT ID> asiakaspalvelija-tunnuksellasi. Näet asiakaspalvelija-tunnuksesi siirtymällä käyttämäsi asiakaspalvelija Kanavat-välilehteen ja valitsemalla portaalista Mobiilisovellus Copilot Studio .

   <script>
       (async function main() {
   
           // Add your AGENT 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') {
                                           // The agent 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>
   

Täysi näytekoodi

Lisätietoja varten voit löytää täyden näytekoodin, joka sisältää jo MSAL:n ja kaupan ehdolliset skriptit GitHub-säilöstämme.