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.

Konfigurieren der Bot-App in Microsoft Entra ID

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.

C# SDK v2.1

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

C# SDK <2.1 (Legacy)

using Microsoft.Teams.Apps.Extensions;
using Microsoft.Teams.Plugins.AspNetCore.Extensions;

var builder = WebApplication.CreateBuilder(args);

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

var appBuilder = App.Builder()
    .AddOAuth(connectionName);

builder.AddTeams(appBuilder);
var app = builder.Build();
var teams = app.UseTeams();

TypeScript

import { App } from '@microsoft/teams.apps';

const connectionName = process.env.CONNECTION_NAME ?? 'graph';

const app = new App({
  oauth: {
    defaultConnectionName: connectionName,
  },
});

Python

import os
from microsoft_teams.apps import App

app = App(default_connection_name=os.getenv("CONNECTION_NAME", "graph"))

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.

C# SDK v2.1

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);
});

C# SDK <2.1 (Legacy)

teams.OnMessage(async (context, cancellationToken) =>
{
    if (!context.IsSignedIn)
    {
        await context.SignIn(cancellationToken);
        return;
    }

    var token = context.UserToken;
    await context.Send($"You are signed in. Token length: {token?.Length}", cancellationToken);
});

teams.OnSignIn(async (_, teamsEvent, cancellationToken) =>
{
    var context = teamsEvent.Context;
    await context.Send("Successfully signed in! You can now use the bot.", cancellationToken);
});

TypeScript

app.on('message', async ({ isSignedIn, signin, userToken, send }) => {
  if (!isSignedIn) {
    await signin();
    return;
  }

  await send(`You are signed in. Token length: ${userToken?.length}`);
});

app.event('signin', async ({ send, token }) => {
  await send(`Successfully signed in! Token length: ${token.token.length}`);
});

Python

from teams.api import MessageActivity, SignInEvent
from teams.apps import ActivityContext

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    if not ctx.is_signed_in:
        await ctx.sign_in()
        return

    token = ctx.user_token
    await ctx.send(f"You are signed in. Token length: {len(token)}")

@app.event("sign_in")
async def handle_sign_in(event: SignInEvent):
    await event.activity_ctx.send("Successfully signed in! You can now use the bot.")

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:

C# SDK v2.1

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);
});

C# SDK <2.1 (Legacy)

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

TypeScript

app.on('signin.failure', async ({ activity, send }) => {
  const { code, message } = activity.value;
  console.log(`Sign-in failed: ${code} - ${message}`);
  await send('Sign-in failed. Please try again.');
});

Python

@app.on_signin_failure()
async def handle_signin_failure(ctx):
    failure = ctx.activity.value
    print(f"Sign-in failed: {failure.code} - {failure.message}")
    await ctx.send("Sign-in failed. Please try again.")

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.

C# SDK v2.1

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

C# SDK <2.1 (Legacy)

teams.OnMessage("/signout", async (context, cancellationToken) =>
{
    if (!context.IsSignedIn)
    {
        await context.Send("You are not signed in.", cancellationToken);
        return;
    }

    await context.SignOut(cancellationToken);
    await context.Send("You have been signed out.", cancellationToken);
});

TypeScript

app.message('/signout', async ({ signout, send, isSignedIn }) => {
  if (!isSignedIn) return;
  await signout();
  await send('You have been signed out.');
});

Python

@app.on_message
async def handle_signout(ctx: ActivityContext[MessageActivity]):
    if "/signout" in ctx.activity.text.lower():
        if not ctx.is_signed_in:
            await ctx.send("You are not signed in.")
            return

        await ctx.sign_out()
        await ctx.send("You have been signed out.")

Zustimmungsdialogfeld zum Abrufen des Zugriffstokens

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:

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:

• Die Zustimmung zu Microsoft Entra ID ist erforderlich
• Die Zustimmung zu Microsoft Entra ID ist nicht erforderlich

Die Zustimmung zu Microsoft Entra ID ist erforderlich

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.

Desktop

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

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

  

  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.

  

Mobil

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

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

  

  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-Nachricht sehen, dass die Authentifizierung nicht erfolgreich war.

  

Die Zustimmung zu Microsoft Entra ID ist nicht erforderlich

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

Aktualisieren von App-Manifest für SSO und App-Vorschau