Konfigurace jednotného přihlašování s Microsoft Entra ID

Důležité

Schopnosti a funkce Power Virtual Agents jsou nyní součástí Microsoft Copilot Studio po významných investicích do generativní umělé inteligence a vylepšených integracích napříč Microsoft Copilot.

Některé články a snímky obrazovky mohou odkazovat na Power Virtual Agents, zatímco aktualizujeme dokumentaci a obsah školení.

Copilot Studio podporuje jednotné přihlašování (SSO). SSO umožňuje kopilotům na webu přihlásit zákazníky, pokud jsou již přihlášeni ke stránce nebo aplikaci, kde je kopilot nasazen.

Předpoklady

• Zapněte ověřování koncového uživatele s Microsoft Entra ID.
  Jednotné přihlašování je podporováno jen pro Microsoft Entra ID. Jiné typy účtů jako Microsoft nebo jiné účty OAuth nejsou podporovány.
• Přidejte téma ověřování do kopilota.
• Použijte vlastní plátno.

Kopilot je například hostován na podnikovém intranetu nebo v aplikaci, ke které je uživatel již přihlášen.

Existují čtyři hlavní kroky konfigurace jednotného přihlášení pro Copilot Studio:

1. Vytvoření registrace aplikace v Microsoft Entra ID pro vlastní plátno.

2. Definice vlastního rozsahu pro svého kopilota.

3. Nakonfigurujte ověření v Copilot Studio pro povolení SSO

4. Nakonfigurujte svůj vlastní kód HTML plátna tak, aby umožňoval jednotné přihlášení.

Důležité

Jednotné přihlašování není aktuálně podporováno, pokud byl kopilot buď:

• Publikován na webu SharePoint.
• Publikován na portálu Power Apps.

Podporované kanály

Následující tabulka podrobně popisuje kanály, které aktuálně podporují jednotné přihlašování. Podporu pro další kanály můžete navrhnout ve fóru nápadů Microsoft Copilot Studio.

Kanál	Podporováno
Kanály Azure Bot Service	Nepodporováno
Vlastní web	Podporováno
Ukázkový web	Nepodporováno
Facebook	Nepodporováno
Microsoft Teams1	Podporováno
Mobilní aplikace	Nepodporováno
Omnikanál pro Customer Service2	Podporováno

¹ Pokud máte také povolený kanál Teams, musíte postupovat podle pokynů pro konfiguraci v dokumentaci Konfigurace jednotného přihlašování pro kanál Teams. Pokud nenakonfigurujete nastavení jednotného přihlášení pro Teams podle pokynů na této stránce, vašim uživatelům při používání kanálu Teams vždy selže ověření.

² Podporován je pouze kanál živého chatu. Další informace: Konfigurace předávání do Dynamics 365 Customer Service.

Webová aplikace

Vytvoření registrací aplikací pro váš vlastní web

Chcete-li povolit jednotné přihlašování, musíte vytvořit dvě samostatné registrace aplikace:

• Registrace ověřovací aplikace, která zapne ověření uživatele pomocí Microsoft Entra ID pro vašeho kopilota
• Registrace aplikace plátna, která umožňuje jednotné přihlášení pro vaši vlastní webovou stránku

Z bezpečnostních důvodů nedoporučujeme znovu používat stejnou registraci aplikace pro kopilota i vlastní web.

1. Chcete-li vytvořit registraci ověřovací aplikace, postupujte podle pokynů v části Konfigurace ověřování uživatele pomocí Microsoft Entra ID.
2. Znovu postupujte podle stejných pokynů a vytvořte druhou registraci aplikace, která slouží jako registrace vaší aplikace plátna.
3. Vraťte se k tomuto článku.

Konfigurace registrace aplikace plátna

1. Po vytvoření registrace aplikace plátna přejděte na Ověřování a poté vyberte Přidat platformu.

2. V části Konfigurace platformy vyberte Přidat platformu a poté vyberte Web.

3. V části Adresy URL pro přesměrování zadejte adresu URL své webové stránky, například http://contoso.com/index.html.

   

4. V části Implicitní udělení oprávnění a hybridní toky zapněte Tokeny ID (používané pro implicitní a hybridní toky) a Přístupové tokeny (používané pro implicitní toky).

5. Vyberte Konfigurovat.

Vyhledání adresy URL koncového bodu tokenu kopilota

1. V Copilot Studio jděte na Nastavení a pak vyberte Kanály.

2. Vyberte Mobilní aplikaci.

3. V sekci Koncový bod tokenu vyberte možnost Kopírovat.

   

Konfigurace jednotného přihlašování na webové stránce

Použijte kód uvedený v úložišti GitHub pro Copilot Studio pro vytvoření webové stránky pro přesměrování URL. Zkopírujte kód z úložiště GitHub a upravte jej podle pokynů uvedených níže.

1. Vraťte se na stránku Přehled v Azure Portal a zkopírujte ID aplikace (klienta) a ID adresáře (klientu) z vaší registrace aplikace plátna.

   

2. Postup konfigurace knihovny Microsoft Authentication Library (MSAL):

   • Přiřaďte clientIdID aplikace (klienta).
   • Přiřaďte authorityhttps://login.microsoftonline.com/ a přidejte svůj ID adresáře (klienta) na konec.

   Příklad:

   var clientApplication;
       (function (){
       var msalConfig = {
           auth: {
               clientId: '692e92c7-xxxx-4060-76d3-b381798f4d9c',
               authority: 'https://login.microsoftonline.com/7ef988bf-xxxx-51af-01ab-2d7fd011db47'     
           },
   

3. Nastavte proměnnou theURL na adresu URL koncového bodu tokenu, kterou jste zkopírovali dříve. Příklad:

   (async function main() {
   
       var theURL = "https://1c0.0.environment.api.powerplatform.com/powervirtualagents/bots/5a099fd/directline/token?api-version=2022-03-01-preview"
   

4. Upravte hodnotu userId, aby zahrnovala vlastní předponu. Příklad:

   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. Uloží vaše změny.

Otestování kopilota pomocí webové stránky

1. Otevřete webovou stránku v prohlížeči.

2. Vyberte volbu Přihlásit se.

   

   Poznámka:

   Pokud prohlížeč blokuje vyskakovací okna nebo používáte anonymní nebo soukromé okno pro prohlížení, budete vyzváni k přihlášení. V opačném případě se přihlášení dokončí pomocí ověřovacího kódu.

   Otevře se na nová karta prohlížeče.

3. Přejděte na novou kartu a zkopírujte ověřovací kód.

4. Přepněte zpět na kartu s kopilotem a vložte ověřovací kód do konverzace kopilota.

Související články

• Registrace aplikace Azure

Klasické

Technický přehled

Následující obrázek ukazuje, jak je uživatel přihlášen, aniž by se mu zobrazila výzva k přihlášení (SSO) v Copilot Studio:

1. Uživatel kopilota zadá frázi, která spustí téma přihlášení. Téma přihlášení je navrženo tak, aby se uživatel přihlásil a používal ověřený token (proměnná AuthToken).

2. Copilot Studio odešle výzvu k přihlášení, která uživateli umožní přihlásit se pomocí svého nakonfigurovaného poskytovatele identity.

3. Vlastní plátno kopilota zachytí výzvu k přihlášení a požádá o token jménem (OBO) od Microsoft Entra ID. Plátno odešle token kopilotovi.

4. Po obdržení tokenu OBO kopilot vymění token OBO za „přístupový token“ a vyplní proměnnou AuthToken pomocí hodnoty přístupového tokenu. Proměnná IsLoggedIn je také nastavena v tomto okamžiku.

Vytvoření registrace aplikace v Microsoft Entra ID pro vlastní plátno

Chcete-li povolit jednotné přihlašování, budete potřebovat dvě samostatné registrace aplikace:

• Jeden pro kopilota, pomocí kterého povolíte ověření uživatele s Microsoft Entra ID.
• Jeden pro vaše vlastní plátno pro povolení jednotného přihlášení.

Důležité

Nemůžete znovu použít stejnou registraci aplikace jak pro ověření uživatele vašeho kopilot, tak pro vaše vlastní plátno.

Vytvoření registrace aplikace v plátnu kopilota

1. Přihlaste se k portálu Azure.

2. Přejděte do Registrace aplikací, a to buď výběrem ikony, nebo hledáním v horní liště vyhledávání.

   

3. Vyberte Nová registrace.

   

4. Zadejte název registrace. Může být užitečné použít jméno kopilot, jehož plátno registrujete, a zahrnout „plátno“, které pomůže oddělit ho od registrace aplikace pro ověření.

   Pokud se například váš kopilot jmenuje „Contoso sales help“, můžete registraci aplikace pojmenovat „ContosoSalesCanvas“ nebo podobně.

5. Vyberte typ účtu v poli Podporované typy účtů. Doporučujeme vybrat Účty v libovolném organizačním adresáři (Libovolný adresář Microsoft Entra –ID s více tenanty) a osobní účty Microsoft (např. Skype, Xbox).

6. Nechte část Adresa URI pro přesměrování prozatím prázdnou, protože tento údaj zadáte v dalších krocích. Vyberte Zaregistrovat.

   

7. Jakmile je registrace dokončena, otevře se stránka Přehled. Přejděte na Manifest. Potvrďte, že accessTokenAcceptedVersion je nastaven na 2. Pokud není, změňte ho na 2 a vyberte Uložit.

Přidání adresy URL pro přesměrování

1. Když je registrace otevřená, přejděte na Ověřování a poté vyberte Přidat platformu.

   

2. V podokně Konfigurace platforem vyberte Web.

   

3. V části Adresy URI pro přesměrování přidejte úplnou adresu URL na stránku, kde je hostováno vaše plátno chatu. V části Implicitní udělení oprávnění vyberte zaškrtávací políčka Identifikační tokeny a Přístupové tokeny.

4. Výběrem možnosti Konfigurovat potvrďte změny.

   

5. Přejděte na Oprávnění API. Vyberte Udělit souhlas správce pro <your tenant name> a potom Ano.

   Důležité

   Aby uživatelé nemuseli udělovat souhlas s každou aplikací, musí globální správce, správce aplikací nebo správce cloudových aplikací udělit souhlas celého klienta k registracím vaší aplikace.

   

Definice vlastního rozsahu kopilota

Definujte vlastní rozsah vystavením rozhraní API pro registraci aplikace plátna v rámci registrace ověřovací aplikace. Rozsahy umožňují určit uživatelské a administrátorské role a přístupová práva.

Tento krok vytvoří vztah důvěryhodnosti mezi registrací ověřovací aplikace pro ověřování a registrací aplikace pro vaše vlastní plátno.

1. Otevřete registraci aplikace, kterou jste vytvořili, když jste nakonfigurovali ověřování.

2. Přejděte na Oprávnění API a ujistěte se, že jsou pro vašeho kopilota přidána správná oprávnění. Vyberte Udělit souhlas správce pro <your tenant name> a potom Ano.

   Důležité

   Aby uživatelé nemuseli udělovat souhlas s každou aplikací, musí globální správce, správce aplikací nebo správce cloudových aplikací udělit souhlas celého klienta k registracím vaší aplikace.

3. Přejděte do Vystavit rozhraní API a vyberte Přidat rozsah.

   

4. Zadejte název oboru spolu s informacemi o zobrazení, které by se měly uživatelům zobrazit, když přijdou na obrazovku jednotného přihlášení. Vyberte Přidat rozsah.

   

5. Vyberte Přidat klientskou aplikaci.

6. Zadejte ID aplikace (klienta) ze stránky Přehled pro registraci aplikace plátna do pole ID klienta. Zaškrtněte políčko pro uvedený rozsah, který jste vytvořili.

7. Vyberte Přidat aplikaci.

Nakonfigurujte ověření v Copilot Studio pro povolení SSO

Adresa URL pro výměnu tokenů na konfigurační stránce ověřování Copilot Studio se používá k výměně tokenu OBO za požadovaný přístupový token prostřednictvím bot framework.

Copilot Studio volá do Microsoft Entra ID k provedení samotné výměny.

1. Přihlaste se ke službě Copilot Studio.

2. Výběrem ikony kopilota v horní nabídce a výběrem správného kopilota potvrďte, že jste vybrali kopilota, pro kterého chcete povolit ověřování.

3. V navigační nabídce pod Nastavení vyberte Zabezpečení. Poté vyberte kartu Ověřování.

   

4. Zadejte celý rozsah URI z podokna Zpřístupnění rozhraní API pro registraci ověřovací aplikace kopilota v poli Adresa URL pro výměnu tokenů. Adresa URI je ve formátu api://1234-4567/scope.name.

   

   

5. Vyberete Uložit a publikujte obsah kopilota.

Nakonfigurujte svůj vlastní kód HTML plátna tak, aby umožňoval jednotné přihlášení

Aktualizujte vlastní stránku plátna, kde se kopilot nachází, abyste zachytili požadavek na přihlašovací kartu a vyměnili token OBO.

1. Nakonfigurujte knihovnu Microsoft Authentication Library (MSAL) přidáním následujícího kódu do a značky <script> v části <head>.

2. Aktualizujte clientId na ID aplikace (klienta) pro registraci aplikace plátna. Nahraďte <Directory ID> Za ID adresáře (tenanta). Tato ID získáte ze stránky Přehled pro registraci aplikace plátna.

   

   <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. Vložte následující <script> do části <body>. Tento skript volá metodu k načtení souboru resourceUrl a výměně aktuálního tokenu za token požadovaný výzvou OAuth.

   <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. Vložte následující <script> do části <body>. V rámci metody main tento kód přidá podmínku k vašemu store s jedinečným identifikátorem kopilota. Vygeneruje také jedinečné ID jako proměnnou userId.

5. Aktualizace <COPILOT ID> na ID kopilota. ID kopilota můžete vidět na kartě Kanály pro kopilota, kterého používáte, a výběr Mobilní aplikace na portálu Copilot Studio.

   

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

Celý ukázkový kód

Pro další informace můžete vyhledat úplný ukázkový kód s MSAL a podmíněnými skripty, které jsou již zahrnuty v našem úložišti GitHub.