Kertakirjautumisen määrittäminen Microsoft Entra ID avulla

Sovelluksen rekisteröintien luominen mukautettua verkkosivustoa varten

Jos haluat ottaa kertakirjautumisen käyttöön, luo kaksi erillistä sovelluksen rekisteröintiä:

• todentamissovelluksen rekisteröinti joka mahdollistaa Microsoft Entra ID käyttäjän todentamisen agentillesi.
• Pohjaan perustuvan sovelluksen rekisteröinti, joka mahdollistaa SSO-kirjautumisen mukautetulle verkkosivustolle

Suojaussyistä älä käytä samaa sovelluksen rekisteröintiä uudelleen sekä agentillesi että mukautetulle sivustollesi.

1. Luo todennussovelluksen rekisteröinti noudattamalla ohjeita artikkelissa Käyttäjän todentamisen määrittäminen Microsoft Entra -tunnuksella.

2. Luo toinen sovelluksen rekisteröinti, joka toimii pohjaan perustuvan sovelluksen rekisteröintinä.

Tunnuksenvaihdon URL-osoitteen lisääminen

Jos haluat päivittää Microsoft Entra ID -todennusasetukset Copilot Studiossa, lisää tunnuksen vaihdon URL-osoite, jotta sovelluksesi ja Copilot Studio voivat jakaa tietoja.

1. Siirry todennussovelluksen rekisteröintisivun Azure-portaalissa kohtaan Expose aPI.

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

3. Valitse Copilot Studiossa Settings -kohdan siirtymisvalikosta Security ja valitse sitten Authentication -ruutu.

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

5. Valitse Tallenna.

Pohjaan perustuvan sovelluksen asiakastunnuksen määrittäminen ohjelmointirajapintavalikon julkaisemista varten

1. Siirry Azure-portaalissa todennussovelluksesi rekisteröintisivulla kohtaan Yleiskatsaus.

2. Kopioi Sovelluksen (asiakkaan) tunnus -arvo kohdasta Essentials.

3. Valitse siirtymispalkissaOhjelmointirajapinnan paljastamisen>.

4. Valitse Valtuutetut asiakassovellukset-kohdassa Lisää asiakassovellus ja liitä kopioitu asiakastunnus.

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

3. Kirjoita Uudelleenohjauksen URI-osoitteet -kohtaan verkkosivusi URL-osoite. Esimerkki: 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ä.

Agentin tunnuksen päätepiste-URL-osoitteen löytäminen

1. Avaa Copilot Studiossa agenttisi ja valitse sitten Kanavat.

2. Valitse Mobiilisovellus.

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

   

SSO-kirjautumisen määrittäminen verkkosivustolle

Luo uudelleenohjauksen URL-osoite käyttämällä Copilot Studio Samples GitHub -säilössä annettua koodia. Kopioi koodi GitHub-säilöstä ja muokkaa sitä noudattamalla seuraavia ohjeita.

1. Siirry Azure portaalin Overview -sivulle ja kopioi Application (asiakas) -tunnus ja Directory (vuokraaja) -tunnus pohjasovelluksen rekisteröinnistä.

   

2. Microsoft Authentication Library (MSAL) määrittäminen:

   • Määritä sovelluksesi (asiakas) tunnukseen .
   • Aseta authority osoitteeseen https://login.microsoftonline.com/ ja lisää loppuun Hakemiston (vuokralaisen) tunnus.

   Esimerkki:

   var clientApplication;
       (function (){
       var msalConfig = {
           auth: {
               clientId: '00001111-aaaa-2222-bbbb-3333cccc4444',
               authority: 'https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'     
           },
   

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.

6. Varmista, että kertakirjautumisen määrittäminen onnistui.

   Jos kertakirjautumista ei määritetä onnistuneesti agenttia testattaessa, sinua kehotetaan kirjautumaan sisään. Sisäänkirjautumisprosessi antaa sinulle vahvistuskoodin, joka sinun on kopioitava keskusteluikkunaan.

   Jos näet kirjautumiskehotteen, tarkista, että tämän menettelyn vaiheet 1–5 on suoritettu oikein. Jos SSO on määritetty onnistuneesti, sinua ei pyydetä kirjautumaan sisään.

   Muistiinpano

   GitHub säilön koodi edellyttää, että käyttäjät valitsevat kirjautumispainikkeen. Tuotantoympäristössä haluat ehkä korvata painiketoiminnon asianmukaisemmalla tapahtumalla, kuten sivulle siirtymisellä.

Liittyvä sisältö

• Azure-sovelluksen rekisteröinti

Tekninen yleiskatsaus

Seuraavasta kuvasta näet, miten käyttäjä kirjautuu sisään ilman kirjautumiskehotetta (SSO) Copilot Studiossa:

1. Agentin 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 (User.AccessToken-muuttujaa).

2. Copilot Studio lähettää sisäänkirjautumiskehotteen, jotta käyttäjä voi kirjautua sisään määritetyn tunnistetietopalvelun avulla.

3. Agentin mukautettu pohja sieppaa kirjautumiskehotteen ja pyytää valtuutustokenia Microsoft Entra ID:n puolesta. Kaavio lähettää tunnuksen agentille.

4. OBO-tunnuksen vastaanottamisen jälkeen agentti vaihtaa OBO-tunnuksen "käyttöoikeustietueelle" ja täyttää muuttujan AuthToken käyttämällä käyttöoikeustietueen arvoa. Myös muuttuja IsLoggedIn määritetään tässä yhteydessä.

Sovelluksen rekisteröinnin luominen Microsoft Entra ID mukautettua pohjaa varten

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

• Yksi agentillesi käyttäjän autentikoinnin mahdollistamiseksi Microsoft Entra ID:n avulla.
• Yksi mukautettua kaaviota varten, joka ottaa käyttöön SSO-kirjautumisen.

Sovelluksen rekisteröinnin luominen agentin kaaviolle

1. Kirjaudu sisään Azure-portaaliin.

2. Siirry kohtaan App registrations joko valitsemalla kuvake tai etsimällä yläreunan hakupalkista.

   

3. Valitse Uusi rekisteröinti.

   

4. Anna rekisteröinnille nimi. Käytä sen agentin nimeä, jonka kangasta olet rekisteröimässä ja johon sisältyy "kangas", jotta voit erottaa sen sovelluksen rekisteröinnistä todentamista varten.

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

5. Valitse kohdassa Tukevat tilityypitTilit missä tahansa organisaation vuokraajassa (Any Microsoft Entra ID directory – Multitenant) ja henkilökohtaiset Microsoft-tilit (esim. 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öt -paneelissa Verkko.

   

3. Lisää kohtaan Uudelleenohjauksen URI-osoitteet täysi URL-osoite sille sivulle, jolla keskustelun kaaviota 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 antaa suostumusta jokaiseen sovellukseen, sovelluksen järjestelmänvalvojan tai pilvisovelluksen järjestelmänvalvojan on myönnettävä vuokraajanlaajuinen suostumus sovellusrekisteröinneillesi.

   

Mukautetun vaikutusalueen määrittäminen agentille

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 kaavion sovellusrekisteröinnin välille.

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

2. Siirry kohtaan Ohjelmointirajapintaoikeudet ja varmista, että agentillesi 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 antaa suostumusta jokaiseen sovellukseen, 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. Anna vaikutusalueen nimi sekä näyttötiedot, jotka käyttäjät näkevät tullessaan 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 luettelon vaikutusalueen valintaruutu.

7. Valitse Lisää sovellus.

Todentamisen määrittäminen Copilot Studiossa kertakirjautumisen käyttöönottamiseksi

Käytä Token Exchange -URL-osoitetta Copilot Studion todennuksen määrityssivulla, kun haluat vaihtaa OBO-tunnuksen pyydettyä käyttöoikeustietuetta varten bottikehyksen kautta.

Copilot Studio kutsuu Microsoft Entra ID todellisen vaihdon suorittamiseksi.

1. Kirjaudu sisään Copilot Studioon.

2. Vahvista, että olet valinnut agentin, jolle haluat ottaa todennuksen käyttöön, valitsemalla ylimmästä valikosta agenttikuvake ja valitsemalla oikea agentti.

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

   

4. Anna koko alan URI API:n paljastaminen -sivulta agentin todentamissovelluksen rekisteröintiin Token exchange URL -kentässä. Kanavan URI-osoitteen muoto on api://1234-4567/scope.name.

   

   

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

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

Päivitä sen mukautetun kaavion sivu, jolla agentti sijaitsee, siepataksesi kirjautumiskorttipyynnön ja vaihtaaksesi OBO-tunnuksen.

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

2. Päivitä clientIdSovelluksen (asiakas) tunnus -arvolla pohjaan perustuvan sovelluksen rekisteröintiä varten. Korvaa <Directory ID> arvolla Hakemiston (vuokraaja) tunnus. Hae 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 agentin yksilöllistä tunnusta. Se luo myös yksilöllisen tunnuksen userId-muuttujaksesi.

5. Päivitä <BOT ID> agenttisi tunnuksella. Jos haluat nähdä agenttisi tunnuksen Copilot Studiossa, siirry agentin Channels -sivulle ja valitse Mobile-sovellus.

   <script>
       (async function main() {
   
           // Add your BOT 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

Koko mallikoodi löytyy, kun käytössä on MSAL ja tallenna Copilot Studio Samples GitHub -säilöön jo sisältyvät ehdolliset komentosarjat.