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

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.

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.

Wymagania wstępne

• Włączanie uwierzytelniania użytkownika końcowego za pomocą Microsoft Entra identyfikatora
• Dodawanie tematu uwierzytelniania do drugiego pilota
• Korzystanie z niestandardowego płótna

Uwaga

Aby skonfigurować logowanie jednokrotne przy użyciu innych OAuth dostawców 2.0, zobacz Konfigurowanie logowania jednokrotnego przy użyciu dostawców ogólnych 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 Microsoft Copilot Studio forum pomysłów.

Kanał	Obsługiwane
Kanały usługi Azure Bot Service	Nieobsługiwane
Niestandardowa strona internetowa	Obsługiwane
Strona demonstracyjna	Nieobsługiwane
Facebook	Nieobsługiwane
Microsoft Teams1	Obsługiwane
Aplikacja mobilna	Nieobsługiwane
Obsługa wielokanałowa dla Customer Service2	Obsługiwane

1 Jeśli masz również włączony kanał usługi Teams, musisz postępować zgodnie z instrukcjami konfiguracji w temacie Konfigurowanie logowania jednokrotnego z identyfikatorem Microsoft Entra dla copilotó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.

2 Obsługiwany jest tylko kanał czatu 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, jeśli pomocnik był:

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

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

Aplikacja internetowa

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. Postępuj zgodnie z instrukcjami, aby ponownie utworzyć rejestrację aplikacji uwierzytelniającej, aby utworzyć drugą rejestrację aplikacji, która służy jako rejestracja aplikacji kanwy.

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

1. W Copilot Studio otwórz pomocnika, a następnie wybierz opcję 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ć automatyczne logowanie, dodaj następujący kod na początku 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: '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ązana zawartość

• 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 jest przeznaczony do logowania użytkownika i używania uwierzytelnionego tokenu (User.AccessToken zmiennej) użytkownika.

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:

• Jeden dla drugiego pilota, aby umożliwić uwierzytelnianie użytkownika za pomocą Microsoft Entra identyfikatora.
• 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. W obszarze Obsługiwane typy kont wybierz pozycję Konta w dowolnej dzierżawie organizacyjnej (Dowolny Microsoft Entra katalog identyfikatorów — 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 Konfigurowanie platform wybierz pozycję Sieć Web.

   

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ślanie 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>. Ten skrypt wywołuje metodę w celu pobrania resourceUrl i wymiany bieżącego tokenu na token żądany przez monit. 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.