Freigeben über

Hinzufügen von Authentifizierung zu einem Bot

  • Artikel

GILT FÜR: SDK v4

Das Azure KI Bot Service v4 SDK vereinfacht die Entwicklung von Bots, die auf Onlineressourcen mit erforderlicher Benutzerauthentifizierung zugreifen können. Ihr Bot muss keine Authentifizierungstoken verwalten, da Azure es für Sie mit OAuth 2.0 verwendet, um ein Token basierend auf den Anmeldeinformationen jedes Benutzers zu generieren. Ihr Bot verwendet das von Azure generierte Token für den Ressourcenzugriff. Dadurch muss der Benutzer seine ID und sein Kennwort für den Zugriff auf eine geschützte Ressource nicht im Bot, sondern nur bei einem vertrauenswürdigen Identitätsanbieter angeben.

Eine Übersicht über diese Art der Authentifizierung durch das Bot Framework finden Sie unter Benutzerauthentifizierung.

Dieser Artikel enthält zwei Beispiele. Das eine zeigt das Beziehen eines Authentifizierungstokens. Das andere ist komplexer und zeigt, wie im Namen des Benutzers auf Microsoft Graph zugegriffen wird. In beiden Fällen können Sie Azure AD v1 oder v2 als Identitätsanbieter verwenden, um ein OAuth-Token für den Bot zu beziehen. In diesem Artikel wird Folgendes behandelt:

  • Erstellen einer Azure Bot-Ressource
  • Erstellen Sie den Microsoft-Entra-ID-Identitätsanbieter
  • Registrieren des Microsoft-Entra-ID-Identitätsanbieters beim Bot
  • Vorbereiten des Botcodes

Am Ende dieses Artikels verfügen Sie über einen Bot, der auf einige einfache Aufgaben reagieren kann. Im Microsoft Graph-Beispiel können Sie eine E-Mail senden, anzeigen, wer Sie sind, und die aktuellsten E-Mail-Nachrichten überprüfen. Sie müssen den Bot zwar nicht veröffentlichen, um die OAuth-Features zu testen, der Bot benötigt jedoch eine gültige Azure-App-ID und ein entsprechendes Kennwort.

Hinweis

Die JavaScript-, C#- und Python-SDKs für Bot Framework werden weiterhin unterstützt, das Java-SDK wird jedoch eingestellt und der langfristige Support endet im November 2023.

Bestehende Bots, die mit dem Java SDK erstellt wurden, werden weiterhin funktionieren.

Für das erstellen eines neuen Bots sollten Sie Microsoft Copilot Studio verwenden und lesen, wie Sie die richtige Copilot-Lösung auswählen.

Weitere Informationen finden Sie unter Die Zukunft des Bot-Buildings.

Überlegungen zu Web Chat und Direct Line

Wichtig

Sie müssen Direct Line mit aktivierter erweiterter Authentifizierung verwenden, um Sicherheitsrisiken beim Herstellen einer Verbindung mit einem Bot mithilfe des Webchat-Steuerelements zu minimieren. Weitere Informationen finden Sie unter erweiterte Direct-Line-Authentifizierung.

Voraussetzungen

  • Sie müssen mit den Bot-Grundlagen, der Zustandsverwaltung, der Dialogbibliothek, der Implementierung von sequenziellen Konversationsflüssen und der Wiederverwendung von Dialogen vertraut sein.

  • Erfahrung mit Azure- und OAuth 2.0-Entwicklung

  • Mindestens Visual Studio 2017 für .NET

  • Node.js für JavaScript.

  • Python 3.8+ für Python.

  • Eines der folgenden Beispiele:

    Beispiel BotBuilder-Version Demonstriert
    Authentifizierung in C# oder JavaScript oder Java oder Python v4 OAuthCard-Unterstützung
    Authentifizierung für Microsoft Graph in C# oder JavaScript oder Java oder Python v4 Microsoft Graph-API-Unterstützung mit OAuth 2.0
    Authentifizierung für Microsoft Teams in C# oder JavaScript oder Java oder Python v4 Microsoft Graph-API-Unterstützung mit OAuth 2.0

    Für die Beispiele in diesem Artikel benötigen Sie:

    • Eine Microsoft-Entra-ID-Anwendung, mit der eine Bot-Ressource in Azure registriert werden kann. Diese Anwendung ermöglicht es dem Bot, auf eine externe geschützte Ressource zuzugreifen (etwa auf Microsoft Graph). Außerdem kann der Benutzer dank der Anwendung über verschiedene Kanäle (beispielsweise Webchat) mit dem Bot kommunizieren.
    • Eine separate Microsoft-Entra-ID-Anwendung, die als Identitätsanbieter funktioniert. Diese Anwendung stellt die Anmeldeinformationen bereit, die zum Herstellen einer OAuth-Verbindung zwischen dem Bot und der geschützten Ressource erforderlich sind. In diesem Artikel wird Active Directory als Identitätsanbieter verwendet. Es werden aber auch zahlreiche andere Anbieter unterstützt.

Wichtig

Wenn Sie einen Bot in Azure registrieren, wird ihm eine Microsoft-Entra-ID-Anwendung zugewiesen. Diese Anwendung schützt jedoch den Zugriff auf den Bot über den Kanal. Für externe geschützte Ressourcen, auf die der Bot im Namen des Benutzers zugreifen soll, wird jeweils eine zusätzliche Microsoft-Entra-ID-Anwendung benötigt.

Erstellen der Ressource

Erstellen Sie die Azure Bot-Ressource, mit der Sie Ihren Bot beim Azure KI Bot Service registrieren können.

Tipp

Neue Web App-Bot- und Bot-Kanalregistrierungs-Ressourcen können nicht erstellt werden. Alle vorhandenen Ressourcen, die konfiguriert und bereitgestellt werden, funktionieren jedoch weiterhin. Bots, die aus einer VSIX- oder Yeoman-Vorlage aus der SDK-Version 4.14.1.2 oder höher erstellt wurden, enthalten ARM-Vorlagen, die eine Azure Bot-Ressource generieren.

  1. Öffnen Sie das Azure-Portal.

  2. Wählen Sie im rechten Bereich Ressource erstellen.

  3. Geben Sie bot in das Suchfeld ein, und drücken Sie die Eingabetaste.

  4. Wählen Sie die Azure Bot-Karte.

    Azure Bot-Ressource auswählen

  5. Klicken Sie auf Erstellen.

  6. Geben Sie Werte in die Pflichtfelder ein und überprüfen und aktualisieren Sie die Einstellungen.

    1. Geben Sie Informationen unter Projektdetails an. Wählen Sie aus, ob Ihr Bot über einen globalen oder lokalen Datenspeicher verfügt. Derzeit steht die lokale Datenaufbewahrungsfunktion für Ressourcen in der Region "Westeuropa" und "Centralindia" zur Verfügung. Weitere Informationen finden Sie unter Regionalisierung bei Azure KI Bot Service.

      Die Projektdetailseinstellungen für eine Azure Bot-Ressource

    2. Geben Sie Informationen unter der Microsoft App-ID an. Wählen Sie aus, wie Ihre Bot-Identität in Azure verwaltet wird und ob Sie eine neue Identität erstellen oder eine vorhandene verwenden möchten.

      Die Microsoft-App-ID-Einstellungen für eine Azure Bot-Ressource

  7. Klicken Sie auf Überprüfen + erstellen.

  8. Wenn die Validierung erfolgreich war, wählen Sie Erstellen.

  9. Wählen Sie nach Abschluss der Bereitstellung die Option Zu Ressource wechseln aus. Der Bot und die zugehörigen aufgelisteten Ressourcen sollten in der ausgewählten Ressourcengruppe aufgeführt sein.

  10. Wenn Sie noch nicht über das Bot Framework SDK verfügen, wählen Sie Von GitHub herunterladen aus, um zu erfahren, wie Sie die Pakete für Ihre bevorzugte Sprache nutzen können.

    Erstellen eines Bots im SDK

Jetzt können Sie Ihren Bot mit dem Bot Framework SDK erstellen.

Tipp

Wenn Azure eine neue Einzel- oder mehrinstanzfähige Azure Bot-Ressource mit einer neuen App-ID erstellt, wird auch ein Passwort generiert.

Bot-Identitätsinformationen

Führen Sie die folgenden Schritte aus, um Identitätsinformationen zur Konfigurationsdatei Ihres Bots hinzuzufügen. Die Datei unterscheidet sich je nach Programmiersprache, die Sie zum Erstellen des Bots verwenden.

Wichtig

Die Java-Version des Bot Framework SDK unterstützt nur mehrinstanzenfähige Bots. Die C#-, JavaScript- und Python-Versionen unterstützen alle drei Anwendungstypen zum Verwalten der Identität des Bots.

Sprache Dateiname Hinweise
C# appsettings.json Unterstützt alle drei Anwendungstypen zum Verwalten der Identität Ihres Bots.
JavaScript .env Unterstützt alle drei Anwendungstypen zum Verwalten der Identität Ihres Bots.
Java application.properties Unterstützt nur mehrinstanzfähige Bots.
Python config.py Unterstützt alle drei Anwendungstypen zum Verwalten der Identität Ihres Bots.

Welche Identitätsinformationen Sie hinzufügen müssen, hängt vom Anwendungstyp des Bots ab. Stellen Sie in der Konfigurationsdatei folgende Werte bereit.

Verfügbar für C#-, JavaScript- und Python-Bots.

Eigenschaft Wert
MicrosoftAppType UserAssignedMSI
MicrosoftAppId Die Client-ID einer benutzerseitig zugewiesenen verwalteten Identität.
MicrosoftAppPassword Nicht zutreffend. Lassen Sie diesen Wert für einen Bot mit benutzerseitig zugewiesener verwalteter Identität leer.
MicrosoftAppTenantId Die Instanz-ID der benutzerseitig zugewiesenen verwalteten Identität.

So aktualisieren Sie Ihren App-Dienst

Wenn Sie über eine bestehende App Service-Ressource (Web-App) für Ihren Bot verfügen und Ihr Bot eine benutzerseitig zugewiesene verwaltete Identitäts-Anwendung ist, müssen Sie möglicherweise den App-Dienst Ihres Bots aktualisieren:

  1. Wechseln Sie zum Blatt App Service für die Web-App Ihres Bots.
  2. Wählen Sie unter Einstellungen Identität aus:
  3. Wählen Sie auf dem Blatt Identität die Registerkarte vom Benutzer zugewiesen und wählen Sie Hinzufügen (+).
  4. Auf dem Blatt Benutzerseitig zugewiesene verwaltete Identität hinzufügen:

    1. Wählen Sie Ihr Abonnement aus.

    2. Wählen Sie für benutzerseitig zugewiesene verwaltete Identität die verwaltete Identität für Ihren Bot aus. Wenn die verwaltete Identität automatisch für Sie generiert wurde, hat sie denselben Namen wie Ihr Bot.

    3. Wählen Sie Hinzufügen aus, um diese Identität für Ihren Bot zu verwenden.

      Das Blatt

So rufen Sie Ihre App- oder Mandanten-ID ab

So rufen Sie die App- oder Mandanten-ID Ihres Bots ab

  1. Öffnen Sie das Bot-Ressourcen-Blatt für Ihren Bot in Azure.
  2. Navigieren Sie zum Blatt Konfigurations. Von diesem Blatt aus können Sie die Microsoft App-ID oder die App-Mandanten-ID des Bots kopieren.

Um ein neues Kennwort zu generieren

Einzel- und Mehrinstanz-Bots verfügen über einen App-Geheimschlüssel oder ein Passwort, das Sie für einige Vorgänge benötigen. Azure KI Bot Service blendet Ihren Botschlüssel aus. Der Besitzer der App Service-Ressource des Bots kann jedoch ein neues Passwort generieren:

  1. Öffnen Sie das Bot-Ressourcen-Blatt für Ihren Bot in Azure.
  2. Navigieren Sie zum Blatt Konfigurations.
  3. Wählen Sie Verwalten neben der Microsoft App-ID aus, um zum Blatt Zertifikate + Geheimnisse für den App-Dienst zu wechseln.
  4. Folgen Sie den Anweisungen auf dem Blatt, um einen neuen geheimen Client-Geheimnis zu erstellen und verwahren Sie den Wert an einem sicheren Ort.

Microsoft Entra ID ist ein Identitätsdienst

Die Microsoft Entra ID ist ein Cloudidentitätsdienst, der es Ihnen ermöglicht, Anwendungen zu erstellen, mit denen sich Benutzer sicher über Industriestandardprotokolle wie OAuth 2.0 anmelden können.

Sie können einen der beiden folgenden Identitätsdienste verwenden:

  1. Microsoft Entra ID-Entwicklerplattform (v1.0). auch bekannt als Endpunkt Azure AD v1. Ermöglicht das Erstellen von Apps mit sicherer Anmeldung von Benutzern, die über ein Geschäfts-, Schul- oder Unikonto von Microsoft verfügen. Weitere Informationen finden Sie in der Übersicht Microsoft Entra ID für Entwickler (v1.0).
  2. Microsoft Identity Platform (v2.0) – Auch bekannt als Endpunkt Microsoft Entra ID. Hierbei handelt es sich um eine Weiterentwicklung der Azure AD-Plattform (v1.0). Ermöglicht das Erstellen von Anwendungen, di sich bei allen Microsoft-Identitätsanbietern anmelden und Token abrufen, um Microsoft-APIs (beispielweise Microsoft Graph) oder andere, von Entwicklern erstellte APIs aufzurufen. Weitere Informationen finden Sie in der Übersicht über Microsoft Identity Platform (v2.0).

Informationen zu den Unterschieden zwischen den Endpunkten der Versionen 1 und 2 finden Sie unter Gründe für eine Aktualisierung auf die Microsoft Identity Platform (v2.0). Vollständige Informationen finden Sie unter Microsoft Identity Platform (früher Microsoft Entra ID für Entwickler).

Erstellen Sie den Microsoft-Entra-ID-Identitätsanbieter

In diesem Abschnitt wird gezeigt, wie Sie einen Microsoft-Entra-ID-Identitätsanbieter erstellen, der OAuth 2.0 zum Authentifizieren des Bots verwendet. Sie können Azure-AD-v1- oder Microsoft-Entra-ID-Endpunkte verwenden.

Tipp

Sie müssen die Microsoft-Entra-ID-Anwendung bei einem Mandanten erstellen und registrieren, in dem Sie der Delegierung der von einer Anwendung angeforderten Berechtigungen zustimmen können.

  1. Öffnen Sie den Bereich Microsoft Entra ID im Azure-Portal. Sollten Sie sich nicht im korrekten Mandanten befinden, klicken Sie auf Verzeichnis wechseln, um zum korrekten Mandanten zu wechseln. (Weitere Informationen zum Erstellen eines Mandanten finden Sie unter Schnellstart: Erstellen eines neuen Mandanten in Azure Active Directory.)

  2. Öffnen Sie den Bereich App-Registrierungen.

  3. Wählen Sie im Bereich App-Registrierungen die Option Neue Registrierung aus.

  4. Füllen Sie die erforderlichen Felder aus, und erstellen Sie die App-Registrierung.

    1. Benennen Sie Ihre Anwendung.

    2. Wählen Sie die unterstützten Kontotypen für Ihre Anwendung aus. (Mit diesem Beispiel funktionieren alle diese Optionen.)

    3. Wählen Sie für den Umleitungs-URI Web aus und legen Sie die URL auf eine der unterstützten OAuth-Umleitungs-URLs fest.

    4. Wählen Sie Registrieren aus.

      • Sobald sie erstellt wurde, zeigt Azure die Seite Übersicht für die App an.
      • Notieren Sie sich den Wert der Anwendungs-ID (Client). Sie verwenden diesen Wert später als Client-ID, wenn Sie die Verbindungszeichenfolge erstellen und den Microsoft-Entra-ID-Anbieter bei der Bot-Registrierung registrieren.
      • Notieren Sie den Wert der Verzeichnis-ID (Mandant). Sie verwenden diesen Wert, um diese Anbieteranwendung bei Ihrem Bot zu registrieren.

  5. Wählen Sie im Navigationsbereich Zertifikate und geheime Schlüssel aus, um einen geheimen Schlüssel für Ihre Anwendung zu erstellen.

    1. Wählen Sie unter Geheime Clientschlüssel die Option Neuer geheimer Clientschlüssel.
    2. Fügen Sie eine Beschreibung hinzu, um dieses Geheimnis von anderen zu unterscheiden, die Sie für diese App erstellen müssen, z. B. bot login.
    3. Wählen Sie für Läuft ab eine Zeitspanne aus, nach der der geheime Schlüssel abläuft.
    4. Wählen Sie Hinzufügen.
    5. Notieren Sie sich vor dem Verlassen von Zertifikaten und geheimen Schlüsseln das Geheimnis. Dieser Wert wird später als geheimer Clientschlüssel verwendet, wenn Sie Ihre Microsoft-Entra-ID-Anwendung mit Ihrem Bot registrieren.

  6. Klicken Sie im Navigationsbereich auf API-Berechtigungen, um den Bereich API-Berechtigungen zu öffnen. Dies ist eine bewährte Methode, um die API-Berechtigungen für die App explizit festzulegen.

    1. Klicken Sie auf Berechtigung hinzufügen, um den Bereich API-Berechtigungen anfordern anzuzeigen.

    2. Wählen Sie für dieses Beispiel Microsoft-APIs und Microsoft Graph aus.

    3. Wählen Sie Delegierte Berechtigungen aus, und stellen Sie sicher, dass die benötigten Berechtigungen ausgewählt sind. Dieses Beispiel erfordert diese Berechtigungen.

      Hinweis

      Für Berechtigungen, die mit ADMINISTRATOREINWILLIGUNG ERFORDERLICH gekennzeichnet sind, müssen sich sowohl ein Benutzer als auch ein Mandantenadministrator anmelden, also sollten Sie diese für Ihren Bot vermeiden.

      • openid
      • profile
      • Mail.Read
      • Mail.Send
      • User.Read
      • User.ReadBasic.All

    4. Wählen Sie Berechtigungen hinzufügen aus. (Wenn ein Benutzer zum ersten Mal über den Bot auf diese App zugreift, muss er die Einwilligung erteilen.)

Sie haben nun eine Microsoft-Entra-ID-Anwendung konfiguriert.

Hinweis

Wenn Sie die Verbindungszeichenfolge erstellen und den Identitätsanbieter bei der Botregistrierung registrieren, weisen Sie die Anwendungs-(Client)-ID und den geheimen Clientschlüssel zu. Siehe nächsten Abschnitt.

Registrieren des Microsoft-Entra-ID-Identitätsanbieters beim Bot

Der nächste Schritt besteht darin, Ihren Identitätsanbieter bei Ihrem Bot zu registrieren.

  1. Öffnen Sie die Ressourcenseite für Ihren Bot im Azure-Portal.

  2. Wählen Sie Einstellungen aus.

  3. Klicken Sie ganz unten Auf der Seite unter OAuth-Verbindungseinstellungen auf Einstellung hinzufügen.

  4. Füllen Sie das Formular wie folgt aus:

    1. Name: Geben Sie einen Namen für Ihre Verbindung ein. Diesen verwenden Sie im Code Ihres Bots.

    2. Dienstanbieter. Wählen Sie Microsoft Entra ID aus, um Microsoft Entra ID-spezifische Felder anzuzeigen.

    3. Client-ID. Geben Sie die Anwendungs-(Client-ID) ein, die Sie für Ihren Microsoft-Entra-ID-Identitätsanbieter aufgezeichnet haben.

    4. Geheimer Clientschlüssel. Geben Sie das Geheimnis ein, das Sie für Ihren Microsoft-Entra-ID-Identitätsanbieter aufgezeichnet haben.

      Tipp

      Wenn Sie Zertifikate verwenden möchten, können Sie den Anbieter AAD v2 mit Zertifikaten auswählen. Sie müssen Bot Service Token Store (appid: 5b404cf4-a79d-4cfe-b866-24bf8e1a4921) die Berechtigung zum Abrufen des Zertifikats erteilen.

    5. URL für den Tokenaustausch. Lassen Sie sie leer, da sie nur für SSO in Microsoft Entra ID verwendet wird.

    6. Mandanten-ID. Geben Sie die Verzeichnis-(Mandant)-ID ein, die Sie zuvor für Ihre Microsoft-Entra-ID-App oder gemeinsam notiert haben, je nachdem, welche unterstützten Kontotypen bei der Erstellung der Azure DD-App ausgewählt wurden. Folgen Sie diesen Kriterien, um zu entscheiden, welcher Wert zugewiesen werden soll:

      • Wenn Sie beim Erstellen der Microsoft-Entra-ID-App Nur Konten in diesem Organisationsverzeichnis (nur Microsoft – einzelner Mandant) ausgewählt haben, geben Sie die Mandanten-ID ein, die Sie zuvor für die Microsoft-Entra-ID-App notiert haben.
      • Wenn Sie aber „Konten in einem beliebigen Organisationsverzeichnis (beliebiges Microsoft-Entra-ID-Verzeichnis – mehrinstanzenfähig)“ und „Konten in allen Organisationsverzeichnissen und persönliche Microsoft-Konten (z. B. Skype, Xbox, Outlook.com)“ oder Konten in einem beliebigen Organisationsverzeichnis (Microsoft-Entra-ID-Verzeichnis – mehrinstanzfähig) ausgewählt haben, müssen Sie common anstelle einer Mandanten-ID eingeben. Andernfalls überprüft die Microsoft-Entra-ID-App über den Mandanten, dessen ID ausgewählt wurde, und schließt persönliche Microsoft-Konten aus.

      Dieser Mandant wird den Benutzern zugeordnet, die authentifiziert werden können. Weitere Informationen finden Sie unter Mandanten in Microsoft Entra ID.

    7. Geben Sie unter Bereiche die Namen der Berechtigungen ein, die Sie bei der Anwendungsregistrierung ausgewählt haben. Zu Testzwecken können Sie einfach eingeben: openid profile.

      Hinweis

      Bei Microsoft Entra ID wird im Feld Bereiche eine Liste von durch Leerzeichen getrennten Werten mit Beachtung der Groß-/Kleinschreibung verwendet.

  5. Wählen Sie Speichern.

Hinweis

Mit diesen Werten kann Ihre Anwendung über die Microsoft Graph-API auf Office 365-Daten zugreifen. Auch sollte keine URL für den Tokenaustausch angegeben werden, da sie nur für einmaliges Anmelden in Microsoft Entra ID verwendet wird.

Ihre Verbindung testen

  1. Klicken Sie auf den Verbindungseintrag, um die erstellte Verbindung zu öffnen.
  2. Klicken Sie oben im Bereich Service Provider Connection Setting (Dienstanbieter-Verbindungseinstellung) auf Verbindung testen.
  3. Beim ersten Mal sollte dies eine neue Registerkarte im Browser öffnen, auf der die Berechtigungen aufgeführt werden, die die App von Ihnen anfordert.
  4. Wählen Sie Akzeptieren aus.
  5. Daraufhin werden Sie zu einer Seite mit dem Hinweis weitergeleitet, dass die Verbindung mit <Name Ihrer Verbindung> erfolgreich getestet wurde.

Sie können diesen Verbindungsnamen nun im Code Ihres Bots verwenden, um Benutzertoken abzurufen.

Vorbereiten des Botcodes

Sie benötigen die App-ID und das Kennwort für Ihren Bot, um diesen Prozess abschließen zu können.

  1. Klonen Sie aus dem GitHub-Repository das Beispiel, mit dem Sie arbeiten möchten: Bot-Authentifizierung oder Bot-Authentifizierung für Microsoft Graph.

  2. Aktualisieren Sie appsettings.json:

    • Legen Sie ConnectionName auf den Namen der OAuth-Verbindungseinstellung fest, die Sie Ihrem Bot hinzugefügt haben.

    • Legen Sie MicrosoftAppId und MicrosoftAppPassword auf die App-ID bzw. das App-Geheimnis Ihres Bots fest.

      Abhängig von den Zeichen in Ihrem Botgeheimnis müssen Sie das Kennwort unter Umständen mit XML-Escapezeichen versehen. Beispielsweise müssen alle kaufmännische Und-Zeichen (&) als &amp; codiert werden.

    {
  "MicrosoftAppType": "",
  "MicrosoftAppId": "",
  "MicrosoftAppPassword": "",
  "MicrosoftAppTenantId": "",
  "ConnectionName": ""
}

    Um OAuth in Bot mit Datenresidenz in Public Cloud zu verwenden, müssen Sie die folgenden Konfigurationen in Ihren App-Einstellungen hinzufügen

    "OAuthUrl": "<Regional-OAuth-Uri>",
"ToChannelFromBotOAuthScope": "https://api.botframework.com",
"ToChannelFromBotLoginUrlTemplate": "https://api.botframework.com",
"PublicAzureChannel": "https://api.botframework.com",
"ToBotFromChannelOpenIdMetadataUrl": "https://login.botframework.com/v1/.well-known/openidconfiguration",
"ToBotFromEmulatorOpenIdMetadataUrl": "https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration",
"ToBotFromChannelTokenIssuer": "https://api.botframework.com",
"ToChannelFromBotLoginUrl": "https://login.microsoftonline.com/botframework.com",

    Dabei ist <Regional-OAuth-URL> eine der folgenden URIs:

    URI Beschreibung
    https://europe.api.botframework.com Für Public-Cloud-Bots mit Datenresidenz in Europa.
    https://unitedstates.api.botframework.com Für Public-Cloud-Bots mit Datenresidenz in den USA.
    https://india.api.botframework.com Für Public-Cloud-Bots mit Data Residency in Indien.

  3. Aktualisieren von Startup.cs:

    Um OAuth in nicht öffentlichen Azure-Clouds wie der Government-Cloud zu verwenden, müssen Sie den folgenden Code in der Datei Startup.cs hinzufügen.

    string uri = "<uri-to-use>";
MicrosoftAppCredentials.TrustServiceUrl(uri);
OAuthClientConfig.OAuthEndpoint = uri;

    Dabei ist <uri-to-use> eine der folgenden URIs:

    URI Beschreibung
    https://api.botframework.azure.us Für Government-Cloud-Bots ohne Datenresidenz in den USA.
    https://api.botframework.com Für Public-Cloud-Bots ohne Datenresidenz. Dies ist der Standard-URI und erfordert keine Änderung an Startup.cs.

Informationen zum Abrufen der Microsoft-App-ID und der Passwortwerte für Microsoft-Apps finden Sie unter Abrufen des Registrierungspassworts.

Hinweis

Als Nächstes können Sie diesen Botcode in Ihrem Azure-Abonnement veröffentlichen, indem Sie mit der rechten Maustaste auf das Projekt klicken und anschließend Veröffentlichen wählen. Dies ist für diesen Artikel aber nicht erforderlich. Sie müssten eine Veröffentlichungskonfiguration einrichten, die den Anwendungs- und Hostingplan verwendet, den Sie beim Konfigurieren des Bots im Azure-Portal verwendet haben.

Testen des Bots mit dem Emulator

Installieren Sie Bot Framework Emulator, sofern noch nicht geschehen. Siehe auch Debuggen mit dem Emulator.

Damit die Anmeldung des Botbeispiels erfolgreich ist, müssen Sie den Emulator wie unter Konfigurieren des Emulators für die Authentifizierung gezeigt konfigurieren.

Testen

Nach dem Konfigurieren des Authentifizierungsmechanismus können Sie die eigentlichen Botbeispieltests durchführen.

Hinweis

Sie werden aufgrund der Art und Weise der Implementierung des Botbeispiels möglicherweise aufgefordert, einen magischen Code einzugeben. Dieser magische Code ist Teil von RFC#7636 und wird zum Hinzufügen eines zusätzlichen Sicherheitselements verwendet. Durch das Entfernen des magischen Codes besteht ein höheres Sicherheitsrisiko. Dies kann mithilfe von Direct Line mit aktivierter erweiterter Authentifizierung abgemildert werden. Weitere Informationen finden Sie unter erweiterte Bot-Framework-Authentifizierung.

  1. Führen Sie das Botbeispiel lokal auf Ihrem Computer aus.
  2. Starten Sie den Emulator.
  3. Sie müssen die App-ID und das Passwort Ihres Bots angeben, wenn Sie die Verbindung mit dem Bot herstellen.
    • Die App-ID und das Kennwort können Sie aus der Azure-App-Registrierung abrufen. Dabei handelt es sich um die gleichen Werte, die Sie der Bot-App in der Datei appsettings.json oder .env zugewiesen haben. Im Emulator weisen Sie diese Werte in der Konfigurationsdatei oder beim erstmaligen Herstellen einer Verbindung mit dem Bot zu.
    • Wenn Sie das Kennwort in Ihrem Botcode mit XML-Escapezeichen versehen mussten, müssen Sie dies auch hier tun.
  4. Geben Sie help ein, um eine Liste der verfügbaren Befehle für den Bot anzuzeigen und die Authentifizierungsfeatures zu testen.
  5. Sobald Sie sich angemeldet haben, müssen Sie Ihre Anmeldeinformationen nur neu eingeben, wenn Sie sich abgemeldet haben.
  6. Geben Sie logout ein, um sich abzumelden und die Authentifizierung abzubrechen.

Hinweis

Für die Bot-Authentifizierung ist die Verwendung des Bot-Connector-Diensts erforderlich. Der Dienst greift auf Informationen aus Ihrer Azure-Bot-Ressource zu.

Beispiel für die Authentifizierung

Im Beispiel Botauthentifizierung ist der Dialog so aufgebaut, dass das Benutzertoken abgerufen wird, nachdem sich der Benutzer angemeldet hat.

Beispielunterhaltung mit dem Authentifizierungsbeispiel-Bot.

Beispiel für die Authentifizierung für Microsoft Graph

Im Beispiel Botauthentifizierung für Microsoft Graph ist der Dialog so aufgebaut, das nach dem Anmelden des Benutzers nur ein eingeschränkter Satz an Befehlen akzeptiert wird.

Beispielunterhaltung mit dem Beispiel-Bot für die Microsoft Graph-Authentifizierung.

Weitere Informationen

Wenn ein Benutzer den Bot zu einem Vorgang auffordert, für den der Benutzer angemeldet sein muss, kann der Bot ein OAuthPrompt-Element verwenden, um das Abrufen eines Tokens für eine bestimmte Verbindung zu initiieren. Mit OAuthPrompt wird ein Fluss für den Tokenabruf mit folgenden Elementen erstellt:

  1. Es wird überprüft, ob Azure KI Bot Service bereits über ein Token für den aktuellen Benutzer und die Verbindung verfügt. Wenn ja, wird das Token zurückgegeben.
  2. Falls für Azure KI Bot Service noch kein zwischengespeichertes Token vorhanden ist, wird ein OAuthCard-Element erstellt. Hierbei handelt es sich um eine Anmeldeschaltfläche, auf die der Benutzer klicken kann.
  3. Nachdem der Benutzer auf die OAuthCard-Anmeldeschaltfläche geklickt hat, sendet Azure KI Bot Service das Token des Benutzers entweder direkt an den Bot oder zeigt einen sechsstelligen Authentifizierungscode für den Benutzer an, der im Chatfenster eingegeben werden muss.
  4. Wenn für den Benutzer ein Authentifizierungscode angezeigt wird, tauscht der Bot diesen Authentifizierungscode gegen das Token des Benutzers aus.

In den folgenden Abschnitten wird beschrieben, wie im Beispiel einige allgemeine Authentifizierungsaufgaben implementiert werden.

Nutzen einer OAuth-Eingabeaufforderung zum Anmelden des Benutzers und Abrufen eines Tokens

Architekturdiagramm für das C#-Beispiel.

Dialogs\MainDialog.cs

Fügen Sie dem MainDialog-Element im Konstruktor eine OAuth-Eingabeaufforderung hinzu. Hier wurde der Wert für den Verbindungsnamen aus der Datei appsettings.json abgerufen.

AddDialog(new OAuthPrompt(
    nameof(OAuthPrompt),
    new OAuthPromptSettings
    {
        ConnectionName = ConnectionName,
        Text = "Please Sign In",
        Title = "Sign In",
        Timeout = 300000, // User has 5 minutes to login (1000 * 60 * 5)
    }));

Verwenden Sie innerhalb eines Dialogschritts BeginDialogAsync, um die OAuth-Eingabeaufforderung zu starten, mit der der Benutzer zum Anmelden aufgefordert wird.

  • Wenn der Benutzer bereits angemeldet ist, wird ein Tokenantwortereignis generiert, ohne dass der Benutzer eine Aufforderung erhält.
  • Andernfalls wird der Benutzer zum Anmelden aufgefordert. Azure KI Bot Service sendet das Tokenantwortereignis, nachdem der Benutzer versucht hat, sich anzumelden.
return await stepContext.BeginDialogAsync(nameof(OAuthPrompt), null, cancellationToken);

Überprüfen Sie im folgenden Dialogschritt, ob im Ergebnis des vorherigen Schritts ein Token enthalten ist. Wenn es nicht NULL lautet, war die Anmeldung des Benutzers erfolgreich.

// Get the token from the previous step. Note that we could also have gotten the
// token directly from the prompt itself. There is an example of this in the next method.
var tokenResponse = (TokenResponse)stepContext.Result;

Warten auf TokenResponseEvent

Wenn Sie eine OAuth-Eingabeaufforderung starten, wird auf ein Tokenantwortereignis gewartet, aus dem das Token des Benutzers abgerufen wird.

Bots\AuthBot.cs

AuthBot wird von ActivityHandler abgeleitet und führt eine explizite Verarbeitung von Tokenantwortereignis-Aktivitäten durch. Hier setzen wir den aktiven Dialog fort, sodass die OAuth-Eingabeaufforderung das Ereignis verarbeiten und das Token abrufen kann.

protected override async Task OnTokenResponseEventAsync(ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
    Logger.LogInformation("Running dialog with Token Response Event Activity.");

    // Run the Dialog with the new Token Response Event Activity.
    await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
}

Abmelden des Benutzers

Die bewährte Methode besteht darin, Benutzern das explizite Abmelden zu ermöglichen, anstatt nur den Timeout der Verbindung zu verwenden.

Dialogs\LogoutDialog.cs

private async Task<DialogTurnResult> InterruptAsync(DialogContext innerDc, CancellationToken cancellationToken = default(CancellationToken))
{
    if (innerDc.Context.Activity.Type == ActivityTypes.Message)
    {
        var text = innerDc.Context.Activity.Text.ToLowerInvariant();

        if (text == "logout")
        {
            // The UserTokenClient encapsulates the authentication processes.
            var userTokenClient = innerDc.Context.TurnState.Get<UserTokenClient>();
            await userTokenClient.SignOutUserAsync(innerDc.Context.Activity.From.Id, ConnectionName, innerDc.Context.Activity.ChannelId, cancellationToken).ConfigureAwait(false);

            await innerDc.Context.SendActivityAsync(MessageFactory.Text("You have been signed out."), cancellationToken);
            return await innerDc.CancelAllDialogsAsync(cancellationToken);
        }
    }

    return null;
}

Hinzufügen einer Teams-Authentifizierung

OAuth wird in Teams anders behandelt als in anderen Kanälen. Das Beispiel für den Teams-Authentifizierungs-Bot (in C#, JavaScript, Java oder Python) veranschaulicht, wie die Authentifizierung für Teams ordnungsgemäß implementiert wird.

Weitere Informationen