Hinzufügen von Code zum Aktivieren von SSO in Ihrer Bot-App

Bevor Sie Code zum Aktivieren des einmaligen Anmeldens (Single Sign-On, SSO) hinzufügen, stellen Sie sicher, dass Sie Ihre App- und Bot-Ressource im Microsoft Entra Admin Center konfigurieren.

Sie müssen den Code Ihrer App konfigurieren, um ein Zugriffstoken von Microsoft Entra ID abzurufen. Das Zugriffstoken wird im Namen der Bot-App ausgestellt.

Hinweis

Wenn Sie Ihre Teams-App mit dem Microsoft Teams-Toolkit erstellt haben, können Sie SSO für Ihre App mithilfe der Anweisungen im Modul "Tools und SDKs" aktivieren. Weitere Informationen finden Sie unter Hinzufügen von einmaligem Anmelden zur Teams-App. Teams Toolkit unterstützt SSO für JavaScript-, TypeScript- und C#-Apps in Visual Studio Code.

In diesem Abschnitt werden folgende Themen behandelt:

  1. Entwicklungsumgebungsvariablen aktualisieren
  2. App mit OAuth initialisieren
  3. Behandeln der Anmeldung und des Tokenempfangs
  4. Behandeln von Anmeldefehlern
  5. Behandeln der Abmeldung von App-Benutzern

Entwicklungsumgebungsvariablen aktualisieren

Sie haben den geheimen Clientschlüssel und die OAuth-Verbindungseinstellung für die App in Microsoft Entra ID konfiguriert. Sie müssen den Code mit diesen Werten konfigurieren.

So aktualisieren Sie die Entwicklungsumgebungsvariablen:

  1. Öffnen Sie das Bot-App-Projekt.

  2. Öffnen Sie die Umgebungsdatei (.env) für Ihr Projekt.

  3. Aktualisieren Sie die folgenden Variablen:

    • Aktualisieren CLIENT_IDSie für die Bot-ID aus der Microsoft Entra ID.
    • Aktualisieren CLIENT_SECRETSie für den geheimen Clientschlüssel.
    • Aktualisieren CONNECTION_NAMESie für den Namen der OAuth-Verbindung, die Sie in Microsoft Entra ID konfiguriert haben.
    • Aktualisieren TENANT_IDSie für die Mandanten-ID.

    Hinweis

    Sie können die OAuth-Umleitungs-URL für Ihren Bot und Identitätsanbieter basierend auf Ihren Datenresidenzanforderungen anpassen, unabhängig davon, ob sich Ihr Bot in der öffentlichen Cloud, der Microsoft Azure Government Cloud oder der Microsoft Azure befindet, die von 21Vianet betrieben wird. Informationen zu OAuth-URLs und einer Datenresidenzliste finden Sie unter OAuth-URL-Unterstützung in Azure KI Bot Service.

  4. Speichern Sie die Datei.

Sie haben jetzt die erforderlichen Umgebungsvariablen für Ihre Bot-App und SSO konfiguriert. Initialisieren Sie als Nächstes die App mit OAuth.

App mit OAuth initialisieren

Das Teams SDK vereinfacht die App-Initialisierung mit einer einzelnen App Klasse, die den Serverlebenszyklus, die Authentifizierung und den Tokenaustausch intern verarbeitet.

using Microsoft.Teams.Apps;
using Microsoft.Teams.Apps.OAuth;

var builder = WebApplication.CreateBuilder(args);

var connectionName = builder.Configuration["CONNECTION_NAME"]
    ?? throw new InvalidOperationException("Missing required configuration value: CONNECTION_NAME");

builder.Services.AddTeamsBotApplication(options =>
{
  options.AddOAuthFlow(connectionName);
});

var app = builder.Build();
var teams = app.UseTeamsBotApplication();

OAuthFlow auth = teams.GetOAuthFlow(connectionName);

Hinweis

Die App Klasse verarbeitet intern die gesamte Adapterkonfiguration, Middleware, Fehlerbehandlung und Servereinrichtung.

Behandeln der Anmeldung und des Tokenempfangs

Das Teams SDK verwendet einfache ereignisgesteuerte Handler für die Authentifizierung. Wird verwendetIsSignedIn, um den Status der Authentifizierung zu überprüfen, SignIn() den SSO-Flow auszulösen und das signin Ereignis zu abonnieren, um eine erfolgreiche Authentifizierung durchzuführen.

teams.OnMessage(async (context, cancellationToken) =>
{
  string? token = await auth.SignInAsync(context, cancellationToken);
  if (token is null)
    {
        return;
    }

  await context.SendAsync($"You are signed in. Token length: {token.Length}", cancellationToken);
});

auth.OnSignInComplete(async (context, tokenResponse, cancellationToken) =>
{
  await context.SendAsync("Successfully signed in! You can now use the bot.", cancellationToken);
});

Hinweis

Das SDK verarbeitet den Tokenaustausch und die Validierung intern. Sie müssen , , oder MainDialog Klassen nicht mehr manuell verwalten.OAuthPromptWaterfallDialog

Behandeln von Anmeldefehlern

Wenn Sie SSO verwenden und der Tokenaustausch fehlschlägt, sendet Teams eine signin/failure Aufrufaktivität an Ihre App. Das SDK enthält einen integrierten Standardhandler, der eine Warnung mit umsetzbaren Anleitungen zur Problembehandlung protokolliert. Sie können optional Ihren eigenen Handler registrieren, um das Verhalten anzupassen:

auth.OnSignInFailure(async (context, failure, cancellationToken) =>
{
    Console.WriteLine($"Sign-in failed: {failure?.Code} - {failure?.Message}");
    await context.SendAsync("Sign-in failed. Please try again.", cancellationToken);
});

Behandeln der Abmeldung von App-Benutzern

Rufen Sie die signout Methode auf, um das Authentifizierungstoken des Benutzers aus dem Zwischenspeicher des Benutzertokendiensts zu entfernen und ihn effektiv abzumelden. Das Teams SDK ersetzt das bisherige Muster der Verwendung DialogContextvon , UserTokenClientund CancelAllDialogsAsync durch einen einfachen Methodenaufruf.

teams.OnMessage("/signout", async (context, cancellationToken) =>
{
  await auth.SignOutAsync(context, cancellationToken);
  await context.SendAsync("You have been signed out.", cancellationToken);
});

Der Benutzer muss den Berechtigungen zustimmen, die von der Bot-App angefordert werden, um das Zugriffstoken abzurufen. Das Zustimmungsdialogfeld wird basierend auf dem Umfang der App angezeigt.

1:1-Chats

Wenn der App-Benutzer die Anwendung zum ersten Mal verwendet und die Zustimmung des Benutzers erforderlich ist, wird das folgende Dialogfeld angezeigt:

Die Infografik zeigt die Interaktion eines Bots mit einem Benutzer im persönlichen Bereich

Wenn der Benutzer "Weiter" wählt, tritt eines der folgenden Ereignisse auf:

  • Wenn die Bot-Benutzeroberfläche über eine Anmeldeschaltfläche verfügt, wird der Anmeldeablauf für Bots aktiviert. Sie können die Berechtigungen festlegen, für die die Zustimmung des App-Benutzers erforderlich ist. Verwenden Sie diesen Ansatz, wenn Ihre App andere Graph-Berechtigungen als openiderfordert.

  • Wenn der Bot keine Anmeldeschaltfläche auf der OAuth-Karte hat, ist für einen minimalen Satz von Berechtigungen die Zustimmung des App-Benutzers erforderlich. Dieses Token ist für die Standardauthentifizierung und zum Abrufen der E-Mail-Adresse des App-Benutzers nützlich.

Das angezeigte Zustimmungsdialogfeld gilt für Open-ID-Bereiche, die in Microsoft Entra ID definiert sind. Der App-Benutzer muss seine Zustimmung nur einmal erteilen. Nach Ihrer Zustimmung kann der App-Benutzer für die erteilten Berechtigungen und Bereiche auf Ihre Bot-App zugreifen und diese verwenden.

Gruppenchats

Im Folgenden werden die beiden Szenarien für die Authentifizierung im Gruppenbereich beschrieben:

Wenn ein Bot zum ersten Mal zu einem Gruppenchat hinzugefügt wird und für einen bestimmten Benutzer eine Zustimmung erforderlich ist, wird nur dem Benutzer ein Zustimmungsdialogfeld angezeigt, der @mentions den Bot verwendet hat. Der Benutzer muss den von der Bot-App angeforderten Berechtigungen einmalig zustimmen, um das Zugriffstoken zu erhalten.

Der Benutzer @mentions der Bot. Eine adaptive Karte wird angezeigt, um die Zustimmung des Benutzers anzufordern.

Die Abbildung zeigt ein Zustimmungsdialogfeld für Desktop

  • Wenn der Benutzer Hinzufügen auswählt, wird ein Berechtigungsdialogfeld angezeigt.

    Das Bild zeigt ein Popupfenster

    Der Benutzer muss Annehmen auswählen, um seine Zustimmung zu erteilen.

  • Wenn der Benutzer ablehnt oder die Anforderung eine Zeitüberschreitung aufweist, muss @mention der Benutzer den Bot erneut verwenden, um die Berechtigung für den Tokenabruf zu erteilen. Die Gruppe kann eine Bot-Meldung sehen, dass die Authentifizierung nicht erfolgreich war.

    Das Bild zeigt die Botinteraktion, wenn die Zustimmung des Benutzers verweigert wird oder die Anforderung abläuft.

Wenn die Benutzerberechtigungen standardmäßig oder für vertrauenswürdige Apps gewährt werden, kann der Benutzer, dem der Bot zugewiesen ist, @mentions direkt mit dem Bot interagieren, ohne dass eine Zustimmung erforderlich ist.

Hinweis

Nachdem der App-Benutzer zugestimmt hat, muss er für weitere Berechtigungen nicht erneut zustimmen. Wenn die im Bereich Microsoft Entra definierten Berechtigungen geändert werden, muss der App-Benutzer möglicherweise erneut zustimmen. Wenn der App-Benutzer jedoch in der Zustimmungsaufforderung nicht auf die App zugreifen kann, greift die Bot-App auf die Anmelde-Karte zurück.

Wichtig

Szenarien, in denen Zustimmungsdialoge nicht erforderlich sind:

  • Wenn der Administrator die Zustimmung im Namen des Mandanten erteilt, müssen App-Benutzer überhaupt nicht zur Zustimmung aufgefordert werden. Dies bedeutet, dass den App-Benutzern die Zustimmungsdialoge nicht angezeigt werden und sie nahtlos auf die App zugreifen können.
  • Wenn Ihre Microsoft Entra-App bei demselben Mandanten registriert ist, von dem Sie eine Authentifizierung in Teams anfordern, kann der App-Benutzer nicht um Zustimmung gebeten werden, und er erhält sofort ein Zugriffstoken. App-Benutzer stimmen diesen Berechtigungen nur zu, wenn die Microsoft Entra-App in einem anderen Mandanten registriert ist.

Wenn Fehler auftreten, lesen Sie Problembehandlung für die SSO-Authentifizierung in Teams.

Codebeispiel

Beispielname Beschreibung .NET Node.js
Schnellstart für Bot-Unterhaltungen für SSO Richten Sie den Teams-Bot mit SSO für eine nahtlose Benutzerauthentifizierung für Einzel- und Gruppenchats schnell ein. View View

Nächster Schritt