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

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

Na przykład agent jest hostowany w 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. Zdefiniuj zakres niestandardowy dla swojego agent.

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łączanie uwierzytelniania użytkowników końcowych za pomocą Tożsamości Microsoft Entra
• Dodaj temat uwierzytelniający do swojego agent
• 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. Możesz zasugerować wsparcie dla dodatkowych kanałów 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

1 Jeśli masz również włączony kanał Teams, musisz postępować zgodnie z instrukcjami konfiguracji w temacie Konfigurowanie logowania jednokrotnego przy użyciu identyfikatora Microsoft Entra dla agentów w Microsoft Teams dokumentacji. 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ł:

• Opublikowane w portalu Power Apps.
• Opublikowane w SharePoint serwisie WWW jako element iframe.

Jednak logowanie jednokrotne jest obsługiwane w przypadku agent, który został opublikowany w witrynie SharePoint internetowej 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 uwierzytelniającej, która umożliwiauwierzytelnianie użytkownika identyfikatora Microsoft Entra dla użytkownika agent
• 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.

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.

Znajdowanie adresu URL punkt końcowy tokena agent

1. Otwórz Copilot Studio plik agent, a następnie wybierz pozycję 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/7ef988bf-xxxx-51af-01ab-2d7fd011db47'     
           },
   

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.

Przetestuj swój agent za pomocą swojej strony internetowej

1. Otwórz stronę sieci Web w przeglądarce.

2. Wybierz Zaloguj.

   

   Uwaga

   Jeśli przeglądarka blokuje wyskakujące okienka albo jest otwierane okno przeglądania InPrivate, jest wyświetlany monit o zalogowanie. W przeciwnym razie login kończy się przy użyciu kodu walidacji.

   Zostanie otwarta nowa karta przeglądarki

3. Przejdź do nowej karty i skopiuj kod walidacji.

4. Przełącz się z powrotem na zakładkę z agent i wklej kod weryfikacyjny do konwersacji agent.

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 agent wpisuje frazę, która powoduje wyzwolenie temat logowania. 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 agent przechwytuje monit logowania i żąda tokenu w imieniu (OBO) z Microsoft Entra identyfikatora. Kanwa wysyła token do agent.

4. Po otrzymaniu tokena OBO, agent wymienia token OBO na "token dostępu" i wypełnia AuthToken zmienną, używając wartości token 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 agent, aby umożliwić uwierzytelnianie użytkownika za pomocą Microsoft Entra identyfikatora.
• Jeden dla twojego kanwy niestandardowej, aby włączyć SSO.

Ważne

Nie można ponownie użyć tej samej rejestracji aplikacji zarówno do uwierzytelniania użytkownika agent, jak i do niestandardowej kanwy.

Tworzenie rejestracji aplikacji dla kanwy agent

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. Pomocne może być użycie nazwy agent, której kanwa jest rejestrowana, i dołączenie słowa "canvas", aby ułatwić oddzielenie go od rejestracji aplikacji w celu uwierzytelnienia.

   Jeśli na przykład agent nazywa się "Contoso pomoc w sprzedaży", możesz nazwać rejestrację aplikacji jako "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

   W celu uniknięcia udzielania zgody przez użytkowników dla każdej aplikacji, administrator globalny, administrator aplikacji lub administrator hmury musi przyznać zgodę na poziomie całej dzierżawy na rejestrację aplikacji.

   

Zdefiniuj zakres niestandardowy dla swojego agent

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 sekcji Uprawnienia interfejsu API i upewnij się, że dla Twojego agent zostały dodane odpowiednie uprawnienia . Wybierz opcję Przyznawanie zgody administratora <Nazwa dzierżawy>, a następnie wybierz Tak.

   Ważne

   W celu uniknięcia udzielania zgody przez użytkowników dla każdej aplikacji, administrator globalny, administrator aplikacji lub administrator hmury musi przyznać zgodę na poziomie całej dzierżawy na rejestrację 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. Upewnij się, że wybrano agent, dla którego chcesz włączyć uwierzytelnianie, wybierając ikonę agent w górnym menu i wybierając odpowiednią agent.

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

   

4. Wprowadź identyfikator URI pełnego zakresu z bloku Uwidacznianie interfejsu API dla rejestracji aplikacji uwierzytelniającej agent w polu Adres URL wymiany tokenów. Adres URI jest w formacie api://1234-4567/scope.name.

   

   

5. Wybierz pozycję Zapisz , a następnie opublikuj zawartość agent.

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

Zaktualizuj niestandardową stronę płótna, na której znajduje się agent, aby przechwycić żądanie logowania karta i wymienić token 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>. main W ramach metody ten kod dodaje warunek do Ur store z unikatowym identyfikatorem agent. Powoduje to również wygenerowanie unikatowego identyfikatora jako zmiennej userId.

5. Zaktualizuj <COPILOT ID> , podając swój identyfikator agent. Identyfikator agent można wyświetlić, przechodząc do karty Kanały dla używanej nazwy agent, a następnie wybierając pozycję Aplikacja mobilna 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.