Konfigurieren von Single Sign-On mit Microsoft Entra ID

Wichtig

Power Virtual Agents-Fähigkeiten und -Funktionen sind jetzt Teil von Microsoft Copilot Studio nach erheblichen Investitionen in generative KI und verbesserte Integrationen in Microsoft Copilot.

Einige Artikel und Screenshots beziehen sich möglicherweise auf Power Virtual Agents während wir Dokumentation und Schulungsinhalte aktualisieren.

Copilot Studio unterstützt einmaliges Anmelden (SSO). SSO erlaubt Copiloten auf Ihrer Website, Kundschaft anzumelden, wenn sie bereits auf der Seite oder in der App angemeldet ist, auf der der Copilot bereitgestellt wird.

Anforderungen

• Aktivieren Sie Endbenutzerauthentifizierung mit Microsoft Entra ID.
  SSO wird nur für Microsoft Entra ID unterstützt. Andere Kontotypen wie Microsoft-Konten oder andere OAuth-Konten werden nicht unterstützt.
• Fügen Sie ein Authentifizierungsthema zu Ihrem Copiloten hinzu.
• Verwenden Sie ein benutzerdefiniertes Canvas.

Beispielsweise wird der Copilot im Unternehmensintranet oder in der App gehostet, bei der der Benutzende bereits angemeldet ist.

Es gibt vier Hauptschritte zum Konfigurieren von SSO für Copilot Studio:

1. Erstellen Sie eine App-Registrierung in Microsoft Entra ID für Ihren benutzerdefinierten Canvas.

2. Leben Sie einen benutzerdefinierten Bereich für Ihren Copiloten fest.

3. Konfigurieren Sie Authentifizierung in Copilot Studio, um SSO zu aktivieren.

4. Konfigurieren Sie Ihren benutzerdefinierten Canvas-HTML-Code, um SSO zu aktivieren.

Wichtig

SSO wird derzeit nicht unterstützt, wenn ein Copilot entweder:

• Auf eine SharePoint-Website veröffentlicht ist.
• Auf ein Power Apps-Portal veröffentlicht ist.

Unterstützte Kanäle

Die folgende Tabelle zeigt die Kanäle, die derzeit SSO unterstützen. Sie können Unterstützung für weitere Kanäle im Microsoft Copilot Studio-Ideenforum vorschlagen.

Kanal	Unterstützt
Azure Bot Service-Kanäle	Nicht unterstützt
Benutzerdefinierte Website	Unterstützt
Demowebsite	Nicht unterstützt
Facebook	Nicht unterstützt
Microsoft Teams1	Unterstützt
Mobile App	Nicht unterstützt
Omnichannel for Customer Service2	Unterstützt

¹ Wenn Sie auch den Teams-Kanal aktiviert haben, müssen Sie die Konfigurationsanweisungen in der Dokumentation SSO für den Teams-Kanal konfigurieren befolgen. Wenn Sie die SSO-Einstellungen für Teams nicht gemäß den Anweisungen auf dieser Seite konfigurieren, schlägt die Authentifizierung Ihrer Benutzenden immer fehl, wenn sie den Teams-Kanal verwenden.

² Nur der Live-Chat-Kanal wird unterstützt. Weitere Informationen finden Sie unter Übergabe an Dynamics 365 Customer Service konfigurieren.

Web-App

App-Registrierungen für Ihre benutzerdefinierte Website erstellen

Um SSO zu aktivieren, müssen Sie zwei separate App-Registrierungen erstellen:

• Eine Authentifizierungs-App-Registrierung, die die Microsoft Entra ID-Benutzerauthentifizierung für Ihren Copiloten ermöglicht
• Eine Canvas-App-Registrierung, die SSO für Ihre benutzerdefinierte Webseite aktiviert

Aus Sicherheitsgründen sollten Sie dieselbe App-Registrierung nicht sowohl für Ihren Copiloten als auch für Ihre benutzerdefinierte Website zu verwenden.

1. Folgen Sie den Anweisungen in Benutzerauthentifizierung mit Microsoft Entra ID, um eine Authentifizierungs-App-Registrierung zu erstellen.
2. Befolgen Sie die gleichen Anweisungen noch einmal, um eine zweite App-Registrierung zu erstellen, die als Ihre Canvas-App-Registrierung dient.
3. Zurück zu diesem Artikel.

Ihre Canvas-App-Registrierung konfigurieren

1. Nachdem Sie Ihre Canvas-App-Registrierung erstellt haben, wechseln Sie zu Authentifizierung, und wählen Sie dann Eine Plattform hinzufügen aus.

2. Wählen Sie unter PlattformkonfigurationenEine Plattform hinzufügen und dann Web aus.

3. Geben Sie unter Umleitungs-URIs die URL für Ihre Webseite ein, z. B. http://contoso.com/index.html.

   

4. Aktivieren Sie im Abschnitt Implizite Genehmigung und Hybridflows sowohl Zugriffstoken (verwendet für implizite Flows) als auch ID-Token (für implizite und Hybrid-Flows).

5. Wählen Sie Konfigurieren aus.

Suchen Sie die Tokenendpunkt-URL Ihres Copiloten

1. Wechseln Sie in Copilot Studio zu Einstellungen, und wählen Sie dann Kanäle aus.

2. Wählen Sie mobile App.

3. Wählen Sie unter Token-Endpunkt die Option Kopieren aus.

   

SSO auf Ihrer Webseite konfigurieren

Vewrenden Sie den im Copilot Studio-GitHub-Repository bereitgestellten Code, um eine Webseite für die Umleitungs-URL zu erstellen. Kopieren Sie den Code aus dem GitHub-Repository, und ändern Sie ihn gemäß den nachstehenden Anweisungen.

1. Wechseln Sie zur Seite Übersicht im Azure-Portal, und kopieren Sie die Anwendungs-ID (Client) und die Verzeichnis-ID (Mandant) aus Ihrer Canvas-App-Registrierung.

   

2. So konfigurieren Sie die Microsoft Authentication Library (MSAL):

   • Ordnen Sie clientId Ihrer Anwendungs-(Client-)ID zu.
   • Ordnen Sie authority zu https://login.microsoftonline.com/ zu und fügen Sie am Ende Ihre Verzeichnis-(Mandanten)-ID hinzu.

   Zum Beispiel:

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

3. Legen Sie die theURL-Variable auf die URL des Token-Endpunkts fest, die Sie zuvor kopiert haben. Zum Beispiel:

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

4. Bearbeiten Sie den Wert userId, um ein benutzerdefiniertes Präfix einzuschließen. Zum Beispiel:

   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. Speichern Sie Ihre Änderungen.

Testen Sie Ihren Copiloten mithilfe Ihrer Webseite

1. Öffnen Sie Ihre Webseite in Ihrem Browser.

2. Wählen Sie Anmeldung aus.

   

   Notiz

   Wenn Ihr Browser Popups blockiert oder Sie ein Inkognito- oder privates Browserfenster verwenden, werden Sie aufgefordert, sich anzumelden. Andernfalls wird die Anmeldung mit einem Validierungscode abgeschlossen.

   Es wird eine neue Browserregisterkarte geöffnet.

3. Wechseln Sie zur neuen Registerkarte, und kopieren Sie den Validierungscode.

4. Gehen Sie zurück zur Registerkarte mit Ihrem Copiloten und fügen Sie den Validierungscode in die Copilotenunterhaltung ein.

Ähnliche Artikel

• Azure-App-Registrierung

Klassisch

Technische Übersicht

Die folgende Abbildung zeigt, wie ein Benutzer angemeldet ist, ohne dass eine Anmeldeaufforderung (SSO) in Copilot Studio angezeigt wird:

1. Der Copilot-Benutzende gibt eine Phrase ein, die ein Anmeldethema auslöst. Das Anmeldethema dient dazu, den Benutzer anzumelden und das authentifizierte Token (AuthToken Variable) des Benutzers zu verwenden.

2. Copilot Studio sendet eine Anmeldeaufforderung, damit sich der Benutzer bei seinem konfigurierten Identitätsanbieter anmelden kann.

3. Der benutzerdefinierte Canvas des Copiloten fängt die Anmeldeaufforderung ab und fordert ein On-Behalf-of-(OBO-)Token von Microsoft Entra ID an. Der Canvas sendet das Token an den Copiloten.

4. Nach Erhalt des OBO-Tokens tauscht der Copilot das OBO-Token gegen ein Zugriffstoken aus und füllt die AuthToken-Variable mit dem Wert vom Zugriffstoken aus. Zu diesem Zeitpunkt wird auch eine IsLoggedIn-Variable festgelegt.

Erstellen Sie eine App-Registrierung in Microsoft Entra ID für Ihren benutzerdefinierten Canvas

Um SSO zu aktivieren, benötigen Sie zwei separate App-Registrierungen:

• Eine für Ihren Copiloten, um die Benutzerauthentifizierung mit Microsoft Entra ID zu aktivieren.
• Eine für Ihren benutzerdefinierten Canvas, um SSO zu aktivieren.

Wichtig

Sie können dieselbe App-Registrierung nicht sowohl für die Benutzerauthentifizierung Ihres Copiloten als auch für Ihren benutzerdefinierten Canvas verwenden.

Erstellen einer App-Registrierung für den Canvas des Copiloten

1. Melden Sie sich am Azure-Portal an.

2. Gehen Sie zu App-Registrierungen, entweder durch Auswahl des Symbols oder durch Suchen in der oberen Suchleiste.

   

3. Wählen Sie Neue Registrierung aus.

   

4. Geben Sie einen Namen für die Registrierung ein. Es kann hilfreich sein, den Namen des Copiloten zu verwenden, dessen Canvas Sie registrieren, und „Canvas“ einzuschließen, um ihn von der App-Registrierung zur Authentifizierung zu unterscheiden.

   Wenn Ihr Copilot beispielsweise „Contoso sales help“ heißt, können Sie die App-Registrierung als „ContosoSalesCanvas“ oder Ähnliches bezeichnen.

5. Wählen Sie den Kontotyp unter Unterstützte Kontotypen. Wir empfehlen, Konten in einem beliebigen Organisationsverzeichnis (beliebiges Microsoft Entra ID-Verzeichnis - mandantenfähig) und persönliche Microsoft-Konten (z. B. Skype, Xbox) zu wählen.

6. Lassen Sie den Abschnitt Umleitungs-URI leer für den Moment, da Sie diese Informationen in den nächsten Schritten eingeben werden. Wählen Sie Registrieren aus.

   

7. Nachdem die Registrierung abgeschlossen ist, wird die Seite Überblick geöffnet. Gehen Sie zu Manifest. Bestätigen Sie, dass accessTokenAcceptedVersion auf 2 festgelegt ist. Ist das nicht der Fall, ändern Sie es auf 2 und wählen Sie dann Speichern.

Hinzufügen der Umleitungs-URL

1. Gehen Sie bei geöffneter Registrierung zu Authentifizierung und wählen Sie dann Eine Plattform hinzufügen.

   

2. Wählen Sie auf dem Blatt Plattformen konfigurieren die Option Web aus.

   

3. Fügen Sie unter URIs weiterleiten die vollständige URL der Seite hinzu, auf der Ihr Chat-Canvas gehostet wird. Aktivieren Sie unter dem Abschnitt Implizite Genehmigung die Kontrollkästchen für ID-Token und Zugriffstoken.

4. Wählen Sie Konfigurieren aus, um Ihre Änderungen zu bestätigen.

   

5. Gehen Sie zu API-Berechtigungen. Wählen Sie Einwilligung des Administrators für <Mandantennamen> gewähren und dann Ja aus.

   Wichtig

   Um zu vermeiden, dass Benutzer jeder Anwendung zustimmen müssen, muss ein globaler Administrator, ein Anwendungsadministrator oder ein Cloudanwendungsadministrator mandantenweite Zustimmung zu Ihren App-Registrierungen erteilen.

   

Einen benutzerdefinierten Bereich für Ihren Copiloten festlegen

Definieren Sie einen benutzerdefinierten Bereich, indem Sie eine API für die Canvas-App-Registrierung in der Authentifizierungs-App-Registrierung verfügbar machen. Mit Bereichen können Sie Benutzer- und Administratorrollen sowie Zugriffsrechte festlegen.

Dieser Schritt erstellt eine Vertrauensbeziehung zwischen der Authentifizierungs-App-Registrierung für die Authentifizierung und der App-Registrierung für Ihren benutzerdefinierten Canvas.

1. Öffnen Sie die von Ihnen erstellte App-Registrierung, wenn Sie die Authentifizierung konfiguriert haben.

2. Gehen Sie zu API-Berechtigungen und stellen Sie sicher, dass die richtigen Berechtigungen für Ihren Copiloten hinzugefügt wurden. Wählen Sie Einwilligung des Administrators für <Mandantennamen> gewähren und dann Ja aus.

   Wichtig

   Um zu vermeiden, dass Benutzer jeder Anwendung zustimmen müssen, muss ein globaler Administrator, ein Anwendungsadministrator oder ein Cloudanwendungsadministrator mandantenweite Zustimmung zu Ihren App-Registrierungen erteilen.

3. Gehen Sie zu Eine API verfügbar machen und wählen Sie Einen Bereich hinzufügen aus.

   

4. Geben Sie einen Namen für den Umfang ein, zusammen mit den Anzeigeinformationen, die den Benutzern angezeigt werden sollen, wenn sie auf den SSO-Bildschirm kommen. Wählen Sie Umfang hinzufügen aus.

   

5. Wählen Sie Eine Client-Anwendung hinzufügen aus.

6. Geben Sie die Anwendungs-ID (Client-ID) von der Seite Überblick für die Canvas-App-Registrierung im Feld Client-ID ein. Aktivieren Sie das Kontrollkästchen für den aufgelisteten Bereich, den Sie erstellt haben.

7. Wählen Sie Anwendung hinzufügen aus.

Konfigurieren der Authentifizierung in Copilot Studio, um SSO zu aktivieren

Die Token-Austausch-URL auf der Copilot Studio-Authentifizierungskonfigurationsseite wird verwendet, um das OBO-Token über das Bot Framework gegen das angeforderte Zugriffstoken auszutauschen.

Copilot Studio ruft Microsoft Entra ID auf, um den eigentlichen Austausch durchzuführen.

1. Melden Sie sich bei Copilot Studio an.

2. Bestätigen Sie, dass Sie den Copiloten ausgewählt haben, für den Sie die Authentifizierung aktivieren möchten, indem Sie das Copilot-Symbol im oberen Menü und dann den richtigen Copiloten auswählen.

3. Wählen Sie im Navigationsmenü unter Einstellungen die Option Sicherheit. Wählen Sie dann die Karte Authentifizierung aus.

   

4. Geben Sie die URI für den gesamten Bereich über das Blade Eine API bereitstellen für die Registrierung der Authentifizierungs-App des Copiloten im Feld Token-Austausch-URL ein. Die URI hat das Format api://1234-4567/scope.name.

   

   

5. Wählen Sie Speichern aus und veröffentlichen Sie dann den Copilot-Inhalt.

Konfigurieren Ihres benutzerdefinierten Canvas-HTML-Codes, um SSO zu aktivieren

Aktualisieren Sie die benutzerdefinierte Canvas-Seite, auf der sich der Copilot befindet, um die Anmeldekartenanforderung abzufangen und das OBO-Token auszutauschen.

1. Konfigurieren Sie die Microsoft Authentication Library (MSAL), indem Sie den folgenden Code in ein <script>-Tag im <head>-Abschnitt einfügen.

2. Aktualisieren Sie clientId mit dem Anwendungs-ID (Client-ID) für die Canvas-App-Registrierung. Ersetzen Sie <Directory ID> mit der Verzeichnis-ID (Mandanten-ID). Sie erhalten diese IDs von der Seite Überblick für die Canvas-App-Registrierung.

   

   <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. Fügen Sie folgendes <script> in den <body>-Abschnitt ein. Dieses Skript ruft eine Methode zum Abrufen der resourceUrl auf und zum Austauschen des aktuellen Tokens gegen ein Token, das von der OAuth-Eingabeaufforderung angefordert wird.

   <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. Fügen Sie folgendes <script> in den <body>-Abschnitt ein. Innerhalb der main Methode fügt dieser Code eine Bedingung zu Ihrem store mit der eindeutigen Kennung Ihres Copiloten hinzu. Es erzeugt auch eine eindeutige ID als Ihre userId-Variable.

5. Aktualisieren Sie <COPILOT ID> mit der ID Ihres Copiloten. Sie können die ID Ihres Copiloten sehen, indem Sie auf die Registerkarte Kanäle für den Copiloten, den Sie verwenden, gehen und Mobile App im Copilot Studio-Portal auswählen.

   

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

Vollständiger Beispielcode

Um weitere Informationen zu erhalten, finden Sie den vollständigen Beispielcode mit den bereits in unserem GitHub-Repository enthaltenen MSAL- und Store-Bedingungsskripten.