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

Tärkeää

Power Virtual Agents -ominaisuudet ja -toiminnot ovat nyt Microsoft Copilot Studion osa generatiiviseen tekoälyyn tehtyjen panostusten ja parannettujen Microsoft Copilot -integrointien jälkeen.

Joissakin artikkeleissa ja näyttökuvissa voidaan viitata Power Virtual Agentsiin, kun ohjeita ja koulutussisältöä päivitetään.

Copilot Studio tukee kertakirjautumista (SSO). Kertakirjautumisen avulla sivustosi avustajat voivat kirjata asiakkaat sisään, jos he ovat jo kirjautuneet sivulle tai sovellukseen, jossa avustaja on otettu käyttöön.

edellytykset

• Loppukäyttäjän todennuksen ottaminen käyttöön Microsoft Entra ID:n avulla.
  Kertakirjautumista tuetaan vain Microsoft Entra ID:ssä. Muita tilityyppejä, kuten Microsoft-tiliä tai muita OAuth-tilejä ei tueta.
• Todennusaiheen lisääminen avustajaan.
• Mukautetun pohjan käyttö.

Jos avustajaa esimerkiksi 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ä avustajalle mukautettu vaikutusalue.

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

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

Tärkeää

Kertakirjautumista ei tällä hetkellä tueta, kun avustaja on joko

• julkaistu SharePoint-sivustoon
• julkaistu Power Apps portaaliin

Tuetut kanavat

Seuraavassa taulukossa on esitetty kanavat, jotka tukevat tällä hetkellä SSO:ta. Voit ehdottaa lisäkanavien tukemista Microsoft Copilot Studioin ideafoorumilla.

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

¹ Jos sinulla on myös Teams-kanava käytössä, sinun on noudatettava Määritä SSO-kirjautuminen Teams-kanavalle -dokumentaation 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.

Verkkosovellus

Sovelluksen rekisteröintien luominen mukautettua verkkosivustoa varten

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

• Sovelluksen rekisteröinnin todennus ottaa avustajan Microsoft Entra ID -käyttäjän todennuksen käyttöön
• Pohjaan perustuvan sovelluksen rekisteröinti, joka mahdollistaa SSO-kirjautumisen mukautetulle verkkosivustolle

Saman sovelluksen rekisteröinnin käyttäminen sekä avustajallasi että mukautetulla verkkosivustollasi ei tietoturvasyistä ole suositeltavaa.

1. Lisätietoja todennussovelluksen rekisteröinnin luonnista on kohdassa Käyttäjän todennuksen määrittäminen Microsoft Entra ID:n avulla.
2. Noudata samoja ohjeita uudelleen luodaksesi toisen sovelluksen rekisteröinnin, joka toimii pohjaan perustuvan sovelluksen rekisteröintinä.
3. Palaa tähän artikkeliin.

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ä.

Avustajan tunnuksen päätepisteen URL-osoitteen löytäminen

1. Siirry Copilot Studioissa kohtaan Asetukset 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ä alla olevien ohjeiden mukaisesti.

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: '692e92c7-xxxx-4060-76d3-b381798f4d9c',
               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://1c0.0.environment.api.powerplatform.com/powervirtualagents/bots/5a099fd/directline/token?api-version=2022-03-01-preview"
   

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.

Avustajan testaaminen verkkosivusi avulla

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 avustajasi sisältävään välilehteen ja liitä vahvistuskoodi avustajakeskusteluun.

Liittyvät artikkelit

• Azure-sovelluksen rekisteröinti

Perinteinen

Tekninen yleiskatsaus

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

1. Avustajan käyttäjä kirjoittaa lauseen, joka käynnistää kirjautumisaiheen. Kirjautumisaihe on suunniteltu kirjaamaan käyttäjä sisään ja käyttämään käyttäjän todennettua tunnusta (AuthToken-muuttujaa).

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

3. Avustajan mukautettu pohja sieppaa kirjautumiskehotteen ja pyytää Microsoft Entra ID:ltä on-behalf-of (OBO) -tunnuksen. Pohja lähettää tunnuksen avustajalle.

4. Kun avustaja on vastaanottanut OBO-tunnuksen, avustaja vaihtaa sen "käyttöoikeustunnukseen" ja täyttää AuthToken-muuttujan käyttäen käyttöoikeustunnuksen 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 avustajalle ottamaan käyttöön käyttäjän todennus Microsoft Entra ID:n avulla.
• Yksi mukautettua kaaviota varten, joka ottaa käyttöön SSO-kirjautumisen.

Tärkeää

Samaa sovelluksen rekisteröintiä ei voi käyttää uudelleen sekä avustajien käyttäjän todennuksessa että mukautetussa kaaviossa.

Sovelluksen rekisteröinnin luominen avustajan pohjalle

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 avustajan nimeä, jonka pohjaa olet rekisteröimässä, ja sisällyttää nimeen "pohja" helpottamaan sen erottamista sovelluksen rekisteröinnistä todennusta varten.

   Jos avustajasi nimi esimerkiksi on Contoson myyntiapu, sovellusrekisteröinnin nimeksi voisi antaa ContosoSalesCanvas tai vastaavaa.

5. Valitse tilin tyyppi kohdasta Tuetut tilityypit. On suositeltavaa, että valitaan Tilit missä tahansa organisaation hakemistossa (mikä tahansa Microsoft Entra ID -hakemisto – palveluna tarjottava sopimus) 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ä avustajalle mukautettu vaikutusalue

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 kohtaan Ohjelmointirajapintaoikeudet ja varmista, että avustajallesi on lisätty oikeat 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. Vahvista, että olet valinnut sen avustajalle, jolle haluat ottaa todennuksen käyttöön, valitsemalla ylimmästä valikosta avustajakuvakkeen ja valitsemalla oikean avustajan.

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

   

4. Syötä täysi vaikutusalueen URI Tarjoa ohjelmointirajapintaa -ikkunasta avustajan todennussovelluksen rekisteröintiä varten Tunnuksen vaihdon URL -kenttään. Kanavan URI-osoitteen muoto on api://1234-4567/scope.name.

   

   

5. Valitse Tallenna ja julkaise sitten avustajan sisältö.

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

Päivitä mukautetun pohjan sivu, jolla avustaja sijaitsee, siepataksesi kirjautumiskorttipyynnön ja vaihtaaksesi OBO-tunnuksen.

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

2. Päivitä clientIdSovelluksen (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. main-menetelmässä tämä koodi lisää ehdon store-kauppaasi käyttäen avustajan yksilöllistä tunnusta. Se luo myös yksilöllisen tunnuksen userId-muuttujaksesi.

5. Päivitä <COPILOT ID> avustajasi tunnuksella. Löydät avustajasi tunnuksen siirtymällä käyttämäsi avustajan Kanavavälilehteen ja tekemällä Copilot Studio -sovelluksessa valinnan Mobiilisovellus.

   

   <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>
   

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.