Kertakirjautumisen määrittäminen Microsoft Entra ID avulla

Sovelluksen rekisteröintien luominen mukautettua verkkosivustoa varten

Jos haluat ottaa SSO-kirjautumisen käyttöön, sinun on luotava 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

Emme suosittele saman sovellusrekisteröinnin käyttämistä uudelleen sekä agentillesi että mukautetulle verkkosivustollesi turvallisuussyistä.

1. Luo todennussovelluksen rekisteröinti noudattamalla ohjeita kohdassa Käyttäjätodentamisen määrittäminen Microsoft Entra ID avulla.

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

Tunnuksenvaihdon URL-osoitteen lisääminen

Jotta Microsoft Entra ID-todennusasetukset voidaan päivittää Copilot Studiossa, sinun on lisättävä 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 todennussovelluksen rekisteröintisivun Azure-portaalissa kohtaan Overview.

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

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-osoitteen verkkosivu Copilot Studio GitHub -säilössä annettua koodia. Kopioi koodi GitHub säilöstä ja muokkaa sitä seuraavien ohjeiden mukaisesti.

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, sinua kehotetaan kirjautumaan sisään, jolloin saat 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ä on kirjautunut 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ää kirjautumiskehotteen, jonka avulla käyttäjä voi kirjautua sisään määritetyllä tunnistetietopalvelullaan.

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

4. Kun agentti on vastaanottanut OBO-tunnuksen, botti 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ä.

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. Voi olla hyödyllistä käyttää sen agentin nimeä, jonka kaaviota olet rekisteröimässä, ja sisällyttää nimeen "kaavio". Tämä auttaa erottamaan sen sovelluksen rekisteröinnistä todennusta 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öjä -ikkunassa 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. 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.

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

Copilot Studion todennuksen määrityssivun Token Exchange URL käytetään OBO-tunnuksen vaihtamiseen pyydetylle käyttöoikeustietueelle botin kehyksen 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. 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 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

Jos haluat lisätietoja, löydät koko mallikoodin, jonka MSAL- ja store-ehdolliset komentosarjat ovat jo alle GitHub-säilössämme.