Konfigurer enkel pålogging med Microsoft Entra ID

Opprett appregistreringer for det egendefinerte nettstedet

For å aktivere SSO må du opprette to separate appregistreringer:

• En godkjenningsappregistrering, som muliggjør Microsoft Entra ID brukergodkjenning for agenten din
• En registrering av lerretsapp som aktiverer enkel pålogging for den egendefinerte nettsiden

Vi anbefaler ikke å bruke den samme appregistreringen på nytt for både agenten og det tilpassede nettstedet av sikkerhetsgrunner.

1. Følg instruksjonene i Konfigurer brukergodkjenning med Microsoft Entra ID for å opprette en registrering av godkjenningsapper.

2. Opprett en annen appregistrering som skal fungere som registreringen av canvas-appen.

Legg til nettadresse for tokenutveksling

Hvis du vil oppdatere innstillingene for Microsoft Entra ID godkjenning i Copilot Studio, må du legge til url-adressen for tokenutveksling for å la appen og Copilot Studio dele informasjon.

1. Gå til Eksponer en API i Azure-portalen på registreringssiden for godkjenningsappen.

2. Velg ikonet Kopier til utklippstavle under Omfang.

3. I Copilot Studio velger du >Sikkerhet< c1> i navigasjonsmenyen under Sikkerhet og deretter Authenticationflisen.

4. For Nettadresse for tokenutveksling (obligatorisk for SSO) limer du inn området du kopierte tidligere.

5. Velg Lagre.

Konfigurer klient-ID-en for lerretsappen for å vise en API-meny

1. Gå til Overview i Azure-portalen på registreringssiden for godkjenningsappen.

2. Kopier program-ID (klient)-verdien under Essensielt.

3. Velg Administrer>Eksponer en API i navigasjonsfeltet.

4. Velg Legg til et klientprogram under Autoriserte klientprogrammer, og lim deretter inn den kopierte klient-ID-en.

5. Velg Lagre.

Konfigurere registreringen av lerretsappen

1. Når du har opprettet registreringen av lerretsappen, kan du gå til Godkjenning og deretter velge Legg til en plattform.

2. Velg Legg til en plattform under Plattformkonfigurasjoner, og velg deretter Enkeltsideapp.

3. Angi nettadressen til nettsiden under URI-er for omdirigering, for eksempel http://contoso.com/index.html.

   

4. Aktiver både ID-tokener (brukes for implisitt flyt og hybridflyt) og Tilgangstokener (brukes for implisitt flyt) i Implisitt tildeling og hybridflyt.

5. Velg Konfigurer.

Finn nettadressen til tokenendepunktet for agenten

1. Åpne agenten i Copilot Studio, og velg deretter Channels.

2. Velg Mobilapp.

3. Velg Kopier under Tokenendepunkt.

   

Konfigurer SSO på nettsiden

Bruk koden som er angitt i Copilot Studio GitHub repo til å opprette en nettside for nettadressen for omadressering. Kopier koden fra GitHub repo og endre den ved hjelp av følgende instruksjoner.

1. Gå til Overview-siden i Azure-portalen, og kopier Application (klient) ID og Directory (tenant) ID fra registreringen av lerretsappen.

   

2. Slik konfigurerer du Microsoft Authentication Library (MSAL):

   • Tilordne clientId til Program-ID (klient).
   • Tilordne authority til https://login.microsoftonline.com/, og legg til Katalog-ID (leier) på slutten.

   Eksempel:

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

3. Sett variabelen theURL til nettadressen for tokenendepunkt du kopierte tidligere. Eksempel:

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

4. Rediger verdien til userId for å ta med et tilpasset prefiks. Eksempel:

   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. Lagre endringene.

6. Verifiser at du har konfigurert SSO.

   Når du tester agenten, blir du bedt om å logge på hvis SSO ikke er konfigurert, noe som gir deg en valideringskode du må kopiere til chattevinduet.

   Hvis du ser en instruksjon for pålogging, må du kontrollere at du har fullført trinn 1 til 5 i denne fremgangsmåten på riktig måte. Hvis enkel pålogging er konfigurert, blir du ikke bedt om å logge på.

   Notat

   Koden i GitHub repo krever at brukerne velger påloggingsknappen. I produksjon vil du kanskje erstatte knappefunksjonaliteten med en mer passende hendelse, for eksempel å navigere til en side.

Relatert innhold

• Azure App registrering

Teknisk oversikt

Illustrasjonen nedenfor viser hvordan en bruker er logget på uten å se en påloggingsledetekst (SSO) i Copilot Studio:

1. Agentbrukeren skriver inn et uttrykk som utløser et påloggingsemne. Påloggingsemnet er utformet for å logge brukeren på og bruke brukerens godkjente token (User.AccessToken-variabel).

2. Copilot Studio sender en påloggingsmelding slik at brukeren kan logge på med den konfigurerte identitetsleverandøren.

3. Agentens kundelerret fanger opp påloggingsledeteksten og ber om et på vegne av (OBO)-tokenet fra Microsoft Entra ID. Lerretet sender tokenet til agenten.

4. Når på-vegne-av-tokenet er mottatt, bytter agenten på-vegne-av-tokenet med et «tilgangstoken» og fyller ut AuthToken-variabelen med verdien fra tilgangstokenet. Variabelen IsLoggedIn angis også på dette tidspunktet.

Opprette en appregistrering i Microsoft Entra ID for det egendefinerte lerretet

For å aktivere SSO trenger du to separate appregistreringer:

• En for agenten din for å aktivere brukergodkjenning med Microsoft Entra ID.
• Én for at det egendefinerte lerretet skal kunne aktivere SSO.

Opprett en appregistrering for agentens arbeidsflate

1. Logg på Azure-portalen.

2. Gå til App registrations, enten ved å velge ikonet eller søke i det øverste søkefeltet.

   

3. Velg Ny registrering.

   

4. Angi et navn på registreringen. Det kan være nyttig å bruke navnet på agenten du registrerer lerretet for, og ta med «lerret» for å skille det fra appregistreringen for godkjenning.

   Hvis agenten for eksempel kalles «Contoso-salgshjelp», kan du kalle appregistreringen «ContosoSalesCanvas» eller noe lignende.

5. Under Støttede kontotyper velger du Accounts i alle organisatoriske leiere (Alle Microsoft Entra ID kataloger – multitenant) og personlige Microsoft-kontoer (for eksempel Skype, Xbox).

6. La delen URI for omdirigering være tom nå, siden du skriver inn informasjonen i de neste trinnene. Velg Registrer.

   

7. Når registreringen er fullført, åpnes den på Oversikt-siden. Gå til Manifest. Bekreft at accessTokenAcceptedVersion er satt til 2. Hvis den ikke gjør det, endrer du den til 2 og velger deretter Lagre.

Legg til URI for omdirigering

1. Når registreringen er åpen, går du til Godkjenning og velger deretter Legg til en plattform.

   

2. På Konfigurer plattformer-bladet velger du Nett.

   

3. Under URI-er for omdirigering legger du til den fullstendige nettadressen til siden der nettpratlerretet er driftet. Under Implisitt tillatelse merker du av i boksene ID-tokener og Tilgangstokener.

4. Velg Konfigurer for å bekrefte endringene.

   

5. Gå til API-tillatelser. Velg Gi administratorsamtykke for <ditt leiernavn> og deretter Ja.

   Viktig!

   For å unngå at brukerne må samtykke til hvert enkelt program, må noen som har fått tilordnet minst rollen Programadministrator eller Skyprogramadministrator gi samtykke for hele leieren til programregistreringene.

   

Definer et egendefinert omfang for agenten

Angi et egendefinert omfang ved å eksponere en API for registreringen av lerretsappen i registreringen av godkjenningsappen. Omfang lar deg bestemme bruker- og administratorroller samt tilgangsrettigheter.

Dette trinnet oppretter en klareringsrelasjon mellom registreringen av godkjenningsappen og appregistreringen for det egendefinerte lerretet.

1. Åpne appregistreringen som du opprettet da du konfigurerte godkjenning.

2. Gå til API-tillatelser, og kontroller at de riktige tillatelsene er lagt til for agenten. Velg Gi administratorsamtykke for <ditt leiernavn> og deretter Ja.

   Viktig!

   For å unngå at brukerne må samtykke til hvert enkelt program, må noen som har fått tilordnet minst rollen Programadministrator eller Skyprogramadministrator gi samtykke for hele leieren til programregistreringene.

3. Gå til Vis en API, og velg Legg til et omfang.

   

4. Skriv inn et navn for omfanget, sammen med visningsinformasjonen som skal vises for brukere når de kommer til SSO-skjermbildet. Velg Legg til omfang.

   

5. Velg Legg til et klientprogram.

6. Angi Program-ID (klient) fra Oversikt-siden for registreringen av lerretsapp, i Klient-ID-feltet. Merk av i avmerkingsboksen for det oppførte omfanget du opprettet.

7. Velg Legg til program.

Konfigurer godkjenning i Copilot Studio for å aktivere SSO

URL-adressen for Token Exchange på konfigurasjonssiden for Copilot Studio-godkjenning brukes til å utveksle OBO-tokenet for det forespurte tilgangstokenet gjennom botrammeverket.

Copilot Studio kaller inn Microsoft Entra ID for å utføre den faktiske utvekslingen.

1. Logg på Copilot Studio.

2. Kontroller at du har valgt agenten du vil aktivere godkjenning for, ved å velge agentikonet i den øverste menyen og velge riktig agent.

3. Velg Sikkerhet under Innstillinger på navigasjonsmenyen. Velg deretter Godkjenning-kortet.

   

4. Skriv inn den fullstendige omfangs-URI-en fra Siden Vis en API for agentens godkjenningsappregistrering i feltet Url-adresse for tokenutveksling . URI-en er i formatet api://1234-4567/scope.name.

   

   

5. Velg Lagre, og publiser deretter agentinnholdet.

Konfigurer den egendefinerte HTML-lerretskoden for å aktivere enkel pålogging

Oppdater den egendefinerte lerretssiden der agenten er plassert, for å fange opp forespørselen om påloggingskort og utveksle OBO-token.

1. Konfigurer Microsoft Authentication Library (MSAL) ved å legge til følgende kode i en <script>-kode i <head>-delen.

2. Oppdater clientId med Program-ID (klient) for registreringen av lerretsappen. Erstatt <Directory ID> med Katalog-ID (tenant). Du får disse ID-ene fra Oversikt-siden for registreringen av lerretsappen.

   <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. Sett inn følgende <skript> i <tekst>-delen. Dette skriptet kaller opp en metode for å hente resourceUrl og utveksle det gjeldende tokenet med et token som forespørres av OAuth-ledeteksten.

   <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. Sett inn følgende <skript> i <tekst>-delen. I main-metoden legger denne koden til en betingelse i store, med agentens unike identifikator. Det genereres også en unik ID som userId-variabelen.

5. Oppdater <BOT ID> med ID-en til agenten. Hvis du vil se agentens ID i Copilot Studio, går du til Channels-siden for agenten din og velger Mobile-appen.

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

Fullstendig eksempelkode

Hvis du vil ha mer informasjon, kan du finne den fullstendige eksempelkoden, med MSAL og lagre betingede skript som allerede er inkludert at vår GitHub repo.