Konfigurowanie jednokrotnego logowania z Tożsamością Microsoft Entra

Copilot Studio obsługuje logowanie jednokrotne (SSO). Logowanie jednokrotne umożliwia agentom w witrynie internetowej logowanie klientów, jeśli są już zalogowani na stronie lub w aplikacji, w której wdrożono agent.

Na przykład, składnik agenta jest hostowany na firmowym intranecie lub w aplikacji, do której użytkownik jest już zalogowany.

Aby skonfigurować usługę SSO w programie, należy wykonać cztery podstawowe czynności w Copilot Studio:

1. Tworzenie rejestracji aplikacji w Tożsamości Microsoft Entra dla niestandardowych kanw.

2. Określanie zakresu niestandardoweego dla agenta.

3. Skonfiguruj uwierzytelnianie w Copilot Studio, aby włączyć SSO.

4. Skonfiguruj swój własny kod HTML kanwy, aby włączyć SSO.

Wymagania wstępne

• Włącz uwierzytelnianie użytkowników końcowych za pomocą Microsoft Entra ID
• Dodaj temat uwierzytelniania do agenta
• Używanie kanwy niestandardowej

Notatka

Aby konfigurować logowanie jednokrotne przy użyciu innych dostawców OAuth 2.0, zobacz Konfigurowanie logowania jednokrotnego u ogólnych dostawców OAuth.

Obsługiwane kanały

W poniższej tabeli przedstawiono szczegółowe kanały, które obecnie obsługują logowanie jednokrotne. Wsparcie dla dodatkowych kanałów można sugerować na Copilot Studio forum pomysłów.

Kanał	Obsługiwane
Kanały usługi Azure Bot Service	Nieobsługiwane
Niestandardowa witryna	Obsługiwane
Demonstracyjna witryna internetowa	Nieobsługiwane
Facebook	Nieobsługiwane
Microsoft Teams1	Obsługiwane
Aplikacja mobilna	Nieobsługiwane
Obsługa wielokanałowa klientów2	Obsługiwane

¹Jeśli masz również włączony kanał usługi Teams, należy postępować zgodnie z instrukcjami konfiguracji podanymi w dokumentacji Konfigurowanie logowania jednokrotnego z Tożsamością Microsoft Entra dla agentów w Microsoft Teams. Niepowodzenie skonfigurowania ustawień logowania jednokrotnego zespołów zgodnie z instrukcjami na tej stronie powoduje, że użytkownicy zawsze mają niepowodze uwierzytelniania się podczas używania kanału Teams.

² Obsługiwany jest tylko kanał rozmowy na żywo. Aby uzyskać więcej informacji, zobacz Konfigurowanie przekazania do aplikacji Dynamics 365 Customer Service.

Ważne

Logowanie jednokrotne nie jest obecnie obsługiwane, gdy agent został wybrany:

• Opublikowane w portalu Power Apps.
• Opublikowane w witrynie SharePoint jako element iframe.

Jednak logowanie jednokrotne jest obsługiwane dla elementu agenta, który został opublikowany w witrynie SharePoint sieci Web jako składnik SPFx.

Aplikacja sieci web

Tworzenie rejestracji aplikacji dla niestandardowej witryny internetowej

Aby włączyć logowanie jednokrotne, potrzeba dwóch osobnych rejestracji aplikacji:

• Rejestracja aplikacji uwierzytelnianie, która umożliwia uwierzytelnianie użytkownika Microsoft Entra ID dla agenta
• Rejestracja aplikacji kanwy, która umożliwia jednokrotne logowanie dla niestandardowej strony internetowej

Ze względów bezpieczeństwa nie zalecamy ponownego używania tej samej rejestracji aplikacji zarówno dla agent, jak i niestandardowej witryny internetowej.

1. Postępuj zgodnie z instrukcjami w konfiguracji uwierzytelniania użytkownika przy użyciu tożsamości Microsoft Entra, aby utworzyć rejestrację aplikacji uwierzytelniania.

2. Postępuj zgodnie z instrukcjami dotyczącymi rejestracji aplikacji uwierzytelniania, aby utworzyć drugą rejestrację aplikacji, która pełni rolę rejestracji aplikacji kanw.

3. Dodaj identyfikator rejestracji aplikacji kanwy do rejestracji aplikacji uwierzytelnienia.

Dodaj adres URL wymiany tokenów

Aby zaktualizować ustawienia uwierzytelnienia Tożsamość Microsoft Entra w Copilot Studio, należy dodać adres URL tokenu wymiany, aby umożliwić aplikacji i Copilot Studio udostępnianie informacji.

1. W portalu Azure Portal w rejestracji aplikacji uwierzytelniania przejdź do Ujawnij interfejs API.

2. W sekcji Zakresy wybierz ikonę Kopiuj do schowka.

3. W Copilot Studio, w menu nawigacyjnym w obszarze Ustawienia wybierz opcję Zabezpieczenia, a następnie wybierz kafelek Uwierzytelnianie.

4. W przypadku Token wymiany URL (wymagany w przypadku logowania jednokrotnego) wklej skopiowany wcześniej zakres.

5. Wybierz pozycję Zapisz.

Konfigurowanie rejestracji aplikacji kanwy

1. Po utworzeniu rejestracji aplikacji kanwy przejdź do pozycji Uwierzytelnianie, a następnie wybierz opcję Dodaj platformę.

2. W obszarze Konfiguracje platformy wybierz pozycje Dodaj platformę i Internet.

3. W obszarze Identyfikatory URI przekierowania wprowadź adres URL strony internetowej, na przykład http://contoso.com/index.html.

   

4. W sekcji Niejawne udzielenie i przepływy hybrydowe włącz opcje Tokeny dostępu (używane do przepływów jawnych) i Tokeny identyfikacyjne (używane do przepływów jawnych i hybrydowych).

5. Wybierz Skonfiguruj.

Znajdź adres URL punktu końcowego tokenu agenta

1. Otwórz agent Copilot Studio, a następnie wybierz Kanały.

2. Wybierz opcję Aplikacja mobilna.

3. W obszarze Punkt końcowy tokenu wybierz opcję Kopiuj.

   

Konfigurowanie jednokrotnego logowania na stronie sieci Web

Użyj kodu podanego w repozytorium GitHub usługi Copilot Studio, aby utworzyć stronę internetową dla adresu URL przekierowywania. Skopiuj kod z repozytorium GitHub i zmodyfikuj go, korzystając z poniższych instrukcji.

Uwaga

Kod znajdujący się w repozytorium GitHub wymaga, aby użytkownik wybierał przycisk logowania lub zalogować się z innej witryny. Aby włączyć automatyczny login, należy dodać na początku następującego kodu aysnc function main():

    (async function main() {
        if (clientApplication.getAccount() == null) {
           await clientApplication.loginPopup(requestObj).then(onSignin).catch(function (error) {console.log(error) });
        }
        // Add your BOT ID below 
        var theURL =

1. Przejdź do strony Omówienie w witrynie Azure Portal i skopiuj identyfikator aplikacji (klienta) oraz identyfikator katalogu (dzierżawcy) z rejestracji aplikacji kanwy.

   

2. Aby skonfigurować bibliotekę uwierzytelniania Microsoft (MSAL):

   • Przypisz clientId do Identyfikatora aplikacji (klient).
   • Przypisz authority do https://login.microsoftonline.com/ i dodaj Identyfikator katalogu (dzierżawca) do końca.

   Na przykład:

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

3. Ustaw zmienną theURL na adres URL punktu końcowego tokenu, który został wcześniej skopiowany. Na przykład:

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

4. Edytuj wartość userId, aby zawierała prefiks niestandardowy. Na przykład:

   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. Zapisz zmiany.

6. Sprawdź, czy pomyślnie skonfigurowano logowanie jednokrotne.

   Podczas testowania Twojego agenta, jeśli logowanie jednokrotne nie zostanie pomyślnie skonfigurowane, zostanie wyświetlony monit o zalogowanie się, co daje kod weryfikacyjny, który należy skopiować do okna czatu.

   Jeśli zostanie wyświetlony monit logowania, sprawdź, czy kroki od 1 do 5 tej procedury zostały poprawnie wykonane. Jeśli logowanie jednokrotne zostanie pomyślnie skonfigurowane, monit o zalogowanie się nie zostanie wyświetlony.

Powiązana zawartość

• Rejestracja aplikacji platformy Azure

Klasyczne

Omówienie techniczne

Na poniższej ilustracji pokazano, jak jest zalogowany użytkownik bez wyświetlenia monitu logowania (SSO) w programie Copilot Studio:

1. Użytkownik agenta wpisuje frazę wyzwalającą temat logowania jednokrotnego. Temat logowania zaprojektowano tak, aby logować użytkownika w programie i używać uwierzytelnionego tokenu użytkownika (zmienna User.AccessToken).

2. Copilot Studio wysyła monit o zalogowanie, aby umożliwić użytkownikowi zalogowanie się przy użyciu skonfigurowanego dostawcy tożsamości.

3. Niestandardowa kanwa agenta przechwytuje monit logowania i zażąda w imieniu użytkownika (OBO) tokenu z programu Microsoft Entra ID. Obszar roboczy wyśle token do programu agenta.

4. Po otrzymaniu tokenu OBO agent wymienia token OBO na „token dostępu” i wypełnia zmienną AuthToken przy użyciu wartości tokenu dostępu. Zmienna IsLoggedIn jest również ustawiana w tym samym czasie.

Tworzenie rejestracji aplikacji w Tożsamości Microsoft Entra dla niestandardowych kanw

Aby włączyć logowanie jednokrotne, potrzeba będzie dwóch osobnych rejestracji aplikacji:

• Jeden dla twojego agenta, aby umożliwić uwierzytelnianie użytkowników za pomocą Microsoft Entra ID.
• Jeden dla twojego kanwy niestandardowej, aby włączyć SSO.

Ważne

Nie możesz używać tej samej rejestracji aplikacji zarówno do uwierzytelniania użytkownika agenta, jak i do swojej własnej kanwy.

Utwórz rejestrację aplikacji dla kanwy agenta

1. Zaloguj się do Portal Azure.

2. Aby przejść do rejestracji aplikacji, należy wybrać ikonę lub użyć wyszukiwania na pasku wyszukiwania.

   

3. Wybierz Nowa rejestracja.

   

4. Wprowadź nazwę rejestracji. Warto użyć nazwy agenta, którego kanwę rejestrujesz, i dodać element "kanwa" do nazwy, aby łątwiej odróżnić element rejestracji aplikacji w celu uwierzytelnienia.

   Jeśli na przykład agent nosi nazwę "Contoso sales help", możesz nazwać rejestrację aplikacji „ContosoSalesCanvas” lub podobnie.

5. W Obsługiwane typy kont wybierz pozycję Konta w dowolnej dzierżawie organizacyjnej (dowolny katalog usługi Tożsamość Microsoft Entra — wielodostępny) i osobiste konta Microsoft (np. Skype, Xbox).

6. W tej chwili w sekcji Adres URI przekierowania należy pozostawić puste to pole, ponieważ te informacje należy wprowadzić w następnych krokach. Wybierz pozycję Zarejestruj.

   

7. Po zakończeniu rejestracji jest otwierana strona Przegląd. Przejdź do Manifest. Sprawdź, czy accessTokenAcceptedVersion jest ustawione na wartość 2. Jeśli nie, zmień go na 2, a następnie wybierz opcję Zapisz.

Dodaj URL przekierowania

1. Po otwarciu rejestracji przejdź do opcji Uwierzytelnianie, a następnie wybierz opcję Dodaj platformę.

   

2. W bloku Konfigurowania platform wybierz pozycję Internet.

   

3. W obszarze Identyfikatory URI przekierowania dodaj pełny adres URL strony, na której znajduje się kanwa czatu. W sekcji Niejawne uprawnienia zaznacz pola wyboru Identyfikatory tokenów oraz Tokeny dostępu.

4. Wybierz pozycję Konfiguruj, aby zastosować zmiany.

   

5. Przejdź do Uprawnień interfejsu API. Wybierz opcję Przyznawanie zgody administratora <Nazwa dzierżawy>, a następnie wybierz Tak.

   Ważne

   Aby użytkownicy nie musieli wyrażać zgody na każdą aplikację, administrator globalny, administrator aplikacji lub administrator aplikacji w chmurze może udzielić zgody całej dzierżawie na rejestracje aplikacji.

   

Określanie zakresu niestandardoweego dla agenta

Określ zakres niestandardowy, udostępniając interfejs API dla rejestracji aplikacji kanwy w ramach rejestracji uwierzytelniania aplikacji. Zakresy umożliwiają określenie ról użytkowników i administratorów oraz praw dostępu.

W tym kroku jest tworzona relacja zaufania między rejestracją aplikacji uwierzytelniania w celu uwierzytelnienia a rejestracją aplikacji dla niestandardowej kanwy.

1. Otwórz rejestrację aplikacji utworzoną podczas konfigurowania uwierzytelniania.

2. Przejdź do Uprawnień interfejsu API i upewnij się, że dla twojego agenta zostały dodane odpowiednie uprawnienia. Wybierz opcję Przyznawanie zgody administratora <Nazwa dzierżawy>, a następnie wybierz Tak.

   Ważne

   Aby użytkownicy nie musieli wyrażać zgody na każdą aplikację, administrator globalny, administrator aplikacji lub administrator aplikacji w chmurze może udzielić zgody całej dzierżawie na rejestracje aplikacji.

3. Wybierz opcję Uwidacznianie interfejsu API i następnie wybierz Dodaj zakres.

   

4. Nadaj zakresowi nazwę oraz wprowadź informacje wyświetlania, które powinny być prezentowane użytkownikom po otwarciu ekranu logowania jednokrotnego. Wybierz Dodaj zakres.

   

5. Wybierz Dodaj aplikację klienta.

6. Wprowadź Identyfikator klienta ze strony Przegląd dla rejestracji aplikacji kanwy w polu Identyfikator klienta. Zaznacz pole wyboru dla utworzonego zakresu.

7. Wybierz Dodaj aplikację.

Skonfiguruj uwierzytelnianie w Copilot Studio, aby włączyć SSO

Adres URL wymiany tokenu na stronie konfiguracji Copilot Studio jest używany do wymiany tokenu OBO na żądany token dostępu za pośrednictwem Bot Framework.

Copilot Studio wywołuje w Tożsamości Microsoft Entra, aby wykonywać rzeczywistą wymianę.

1. Zaloguj się w Copilot Studio.

2. Potwierdź, że wybrano agenta, dla którego ma zostać włączone uwierzytelnianie, przez wybranie ikony agenta w górnym menu i wybranie odpowiedniego agenta.

3. W menu nawigacji, w sekcji Ustawienia wybierz Zabezpieczenia. Następnie wybierz kartę Uwierzytelnianie w sieci Web.

   

4. Wprowadź kod URI pełnego zakresu z pola Udostępnij interfejs API dla rejestracji aplikacji uwierzytelniania agenta w polu Adres URL wymiany tokenu. Adres URI jest w formacie api://1234-4567/scope.name.

   

   

5. Następnie wybierz pozycje Zapisz i opublikuj treść agenta.

Skonfiguruj swój własny kod HTML kanwy, aby włączyć SSO

Zaktualizuj stronę niestandardowej kanwy, na której znajduje się agent, aby przechwycić prośbę o kartę logowania i przeprowadzić wymianę tokenu OBO.

1. Skonfiguruj bibliotekę uwierzytelniania Microsoft (MSAL), dodając poniższy kod w tagu <script> w sekcji <head>.

2. Zaktualizuj clientId za pomocą Identyfikatora aplikacji (klienta) umożliwiającego rejestrację aplikacji kanwy. Zamień <Directory ID>na Identyfikator katalogowy (dzierżawcy). Te identyfikatory są uzyskiwane na Stronie przeglądowej rejestracji aplikacji w obszarze roboczym.

   <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. Wprowadź następujący skrypt <script>w sekcji <body>. Skrypt wywołuje metodę w celu pobrania resourceUrl i zamiany bieżącego tokenu na token żądany przez monit uwierzytelniania 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. Wprowadź następujący skrypt <script>w sekcji <body>. W ramach metody main kod dodaje element warunkowy do elementu store z unikatowym identyfikatorem agenta. Powoduje to również wygenerowanie unikatowego identyfikatora jako zmiennej userId.

5. Zaktualizuj <COPILOT ID> za pomocą identyfikatora swojego agenta. Aby wyświetlić identyfikator agenta, należy przejść do karty Kanały dla używanego agenta i wybrać Aplikację mobilną w portalu Copilot Studio.

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

Pełny przykładowy kod

Więcej informacji można znaleźć w pełnym przykładowym kodzie, przy użyciu skryptów warunkowych MSAL i skryptów warunkowych, które są już dołączone do naszego repozytorium GitHub.