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

Ważne

Możliwości i funkcje Power Virtual Agents są teraz częścią Microsoft Copilot Studio w wyniku znacznych inwestycji w generatywną AI i poprawioną integracje z Microsoft Copilot.

Niektóre artykuły i zrzuty ekranów mogą odwoływać się do Power Virtual Agents podczas aktualizowania dokumentacji i zawartości szkoleniowej.

Copilot Studio obsługuje logowanie jednokrotne (SSO). Logowanie jednokrotne umożliwia pomocnikom w witrynie internetowej logowanie użytkowników, jeśli zalogowali się na stronie lub w aplikacji, w której wdrożono tego pomocnika.

Wymagania wstępne

• Włączanie uwierzytelniania użytkowników końcowych za pomocą Tożsamości Microsoft Entra.
  Logowanie jednokrotne jest obsługiwane dla Tożsamości Microsoft Entra. Inne typy kont, takie jak konto Microsoft lub inne konta OAuth, nie są obsługiwane.
• Dodawanie tematu uwierzytelniania do pomocnika.
• Używanie kanwy niestandardowej.

Na przykład pomocnik 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śl zakres niestandardowy dla swojego pomocnika.

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

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

Ważne

Logowanie jednokrotne nie jest obecnie obsługiwane, jeśli pomocnik był:

• Opublikowane w witrynie SharePoint.
• Opublikowane w portalu Power Apps.

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 Microsoft 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ł Teams, musisz postępować zgodnie z instrukcjami konfiguracji w dokumentacji Konfiguracja SSO dla kanału 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.

Aplikacja sieci web

Tworzenie rejestracji aplikacji dla niestandardowej witryny internetowej

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

• Rejestracja aplikacji uwierzytelniania, która umożliwia uwierzytelnianie użytkownika tożsamości Microsoft Entra w pomocniku
• Rejestracja aplikacji kanwy, która umożliwia jednokrotne logowanie dla niestandardowej strony internetowej

Ze względów bezpieczeństwa nie zaleca się ponownego korzystanie z tej samej rejestracji aplikacji zarówno dla pomocnika, jak i dla niestandardowej witryny sieci Web.

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. Ponownie postępuj zgodnie z tym samym instrukcjami, aby utworzyć drugą rejestrację aplikacji, która pełni rolę rejestracji aplikacji kanwy.
3. Wróć do tego artykułu.

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 punktu końcowego tokena swojego pomocnika

1. W usłudze Copilot Studio przejdź do obszaru Ustawienia i 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.

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: '692e92c7-xxxx-4060-76d3-b381798f4d9c',
               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://1c0.0.environment.api.powerplatform.com/powervirtualagents/bots/5a099fd/directline/token?api-version=2022-03-01-preview"
   

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.

Testowanie pomocnika przy użyciu strony sieci Web

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. Przejdź wstecz do karty z pomocnikiem i wklej kod walidacji do konwersacji pomocnika.

Powiązane artykuły

• Rejestracja aplikacji platformy Azure

Klasyczny

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 pomocnika wprowadza frazę wyzwalającą temat logowania. Temat logowania zaprojektowano tak, aby logować użytkownika w programie i używać uwierzytelnionego tokenu użytkownika (zmienna AuthToken).

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

3. Kanwa niestandardowa pomocnika przechwytuje monit logowania i żąda (w imieniu) tokenu OBO od tożsamości Microsoft Entra. Kanwa wyśle ten token do pomocnika.

4. Po otrzymaniu tokenu OBO pomocnik 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:

• Jedną dla pomocnika w celu włączenia uwierzytelniania użytkownika przy użyciu tożsamości Microsoft Entra.
• 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 pomocnika, jak i do swojej własnej kanwy.

Tworzenie rejestracji aplikacji dla kanwy pomocnika

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 pomocnika, którego kanwę się rejestruje i dołączenie ciągu „kanwa”, aby odróżnić ją od rejestracji aplikacji w celu uwierzytelnienia.

   Jeśli na przykład nazwa pomocnika to "Pomoc ds. sprzedaży Contoso", można nazwać rejestrację aplikacji "ContosoSalesKanwa".

5. Wybierz obsługiwane typy kont w Obsługiwane typy kont. Zalecamy wybranie opcji Kota w którymkolwiek katalogu organizacji (wszelkie katalogi Tożsamości Microsoft Entra — wielu dzierżawców) i osobiste konta Microsoft (na przykład 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.

   

Określanie zakresu niestandardowego dla pomocnika

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 Uprawnienia API i upewnij się, że do twojego pomocnika 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. Potwierdź, że wybrano pomocnika, dla którego ma zostać włączone uwierzytelnianie, przez wybranie ikony pomocnika w górnym menu i wybranie odpowiedniego pomocnika.

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

   

4. Wprowadź pełny zakres adresu URI z pola Udostępnij interfejs API rejestracji aplikacji uwierzytelniania do pola Adresu URL wymiany tokenu. Adres URI jest w formacie api://1234-4567/scope.name.

   

   

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

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

Zaktualizuj stronę niestandardowej kanwy, na której znajduje się pomocnik, aby przechwycić żądanie karty 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 ten dodaje warunek do kodu store użytkownika, z unikatowym identyfikatorem pomocnika. Powoduje to również wygenerowanie unikatowego identyfikatora jako zmiennej userId.

5. Zaktualizuj <COPILOT ID> przy użyciu identyfikatora pomocnika. Identyfikator swojego pomocnika można sprawdzić, przechodząc na kartę Kanały używanego pomocnika i wybierając Aplikację mobilne w portalu 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>
   

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.