Hinzufügen von Code zum Aktivieren des einmaligen Anmeldens in Ihrer Bot-App

Artikel
11/17/2023

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

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 Auftrag 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 aktivieren, indem Sie die Anweisungen im Modul Tools und SDKs verwenden. Weitere Informationen finden Sie unter Hinzufügen des einmaligen Anmeldens zur Teams-App. Teams Toolkit unterstützt SSO für JavaScript- und TypeScript-Apps in Visual Studio Code und in Teams Toolkit 17.4 Preview 3 für C#-Apps.

In diesem Abschnitt werden folgende Themen behandelt:

Aktualisieren von Entwicklungsumgebungsvariablen
Hinzufügen von Code zum Verarbeiten eines Zugriffstokens
Hinzufügen von Code zum Empfangen des Tokens
Behandeln der Abmeldung von App-Benutzern

Aktualisieren von Entwicklungsumgebungsvariablen

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:

Öffnen Sie das Bot-App-Projekt.
Öffnen Sie die Umgebungsdatei für Ihr Projekt.
Aktualisieren Sie die folgenden Variablen:
- Aktualisieren Sie für MicrosoftAppIddie Bot-ID von Microsoft Entra ID.
- Aktualisieren MicrosoftAppPasswordSie für den geheimen Clientschlüssel.
- Aktualisieren Sie für ConnectionNameden Namen der OAuth-Verbindung, die Sie in Microsoft Entra ID konfiguriert haben.
- Aktualisieren MicrosoftAppTenantIdSie für die Mandanten-ID.
Speichern Sie die Datei.

Sie haben nun die erforderlichen Umgebungsvariablen für Ihre Bot-App und SSO konfiguriert. Fügen Sie als Nächstes den Code für die Verarbeitung von Bottoken hinzu.

Hinzufügen von Code zum Verarbeiten eines Zugriffstokens

Die Anforderung zum Abrufen des Tokens ist eine POST-Nachrichtenanforderung, die das vorhandene Nachrichtenschema verwendet. Es ist in den Anhängen einer OAuthCard enthalten. Das Schema für die OAuthCard-Klasse ist in Microsoft Bot Schema 4.0 definiert. Teams aktualisiert das Token, wenn die TokenExchangeResource -Eigenschaft auf der Karte aufgefüllt ist. Für den Teams-Kanal wird nur die Eigenschaft Id berücksichtigt, die eine Tokenanforderung eindeutig identifiziert.

Hinweis

Das Microsoft Bot Framework OAuthPrompt oder MultiProviderAuthDialog wird für die SSO-Authentifizierung unterstützt.

So aktualisieren Sie den Code Ihrer App:

Fügen Sie Codeausschnitt für TeamsSSOTokenExchangeMiddlewarehinzu.
- C#
- JavaScript
Fügen Sie den folgenden Codeausschnitt zu AdapterWithErrorHandler.cs (oder der entsprechenden Klasse im Code Ihrer App) hinzu:
```
base.Use(new TeamsSSOTokenExchangeMiddleware(storage, configuration["ConnectionName"]));
```
Fügen Sie den folgenden Codeausschnitt zu index.js (oder der entsprechenden Klasse im Code Ihrer App) hinzu:
```
const {TeamsSSOTokenExchangeMiddleware} = require('botbuilder');
const tokenExchangeMiddleware = new TeamsSSOTokenExchangeMiddleware(memoryStorage, env.connectionName);
adapter.use(tokenExchangeMiddleware);
```
Hinweis

Sie erhalten möglicherweise mehrere Antworten für eine bestimmte Anfrage, wenn der Benutzer mehrere aktive Endpunkte hat. Sie müssen alle doppelten oder redundanten Antworten mit dem Token entfernen. Weitere Informationen zu signin/tokenExchange finden Sie unter TeamsSSOTokenExchangeMiddleware-Klasse.

Verwenden Sie den folgenden Codeausschnitt, um ein Token anzufordern.

C#
JavaScript

Nachdem Sie hinzugefügt haben AdapterWithErrorHandler.cs, muss der folgende Code angezeigt werden:

    public class AdapterWithErrorHandler : CloudAdapter
    {
        public AdapterWithErrorHandler(
            IConfiguration configuration,
            IHttpClientFactory httpClientFactory,
            ILogger<IBotFrameworkHttpAdapter> logger,
            IStorage storage,
            ConversationState conversationState)
            : base(configuration, httpClientFactory, logger)
        {
            base.Use(new TeamsSSOTokenExchangeMiddleware(storage, configuration["ConnectionName"]));

            OnTurnError = async (turnContext, exception) =>
            {
                // Log any leaked exception from the application.
                // NOTE: In production environment, you must consider logging this to
                // Azure Application Insights. Visit https://learn.microsoft.com/azure/bot-service/bot-builder-telemetry?view=azure-bot-service-4.0&tabs=csharp to see how
                // to add telemetry capture to your bot.
                logger.LogError(exception, $"[OnTurnError] unhandled error : {exception.Message}");

                // Send a message to the user.
                await turnContext.SendActivityAsync("The bot encountered an error or bug.");
                await turnContext.SendActivityAsync("To continue to run this bot, please fix the bot source code.");

                if (conversationState != null)
                {
                    try
                    {
                        // Delete the conversationState for the current conversation to prevent the
                        // bot from getting stuck in a error-loop caused by being in a bad state.
                        // conversationState must be thought of as similar to "cookie-state" in a Web pages.
                        await conversationState.DeleteAsync(turnContext);
                    }
                    catch (Exception e)
                    {
                        logger.LogError(e, $"Exception caught on attempting to Delete ConversationState : {e.Message}");
                    }
                }

                // Send a trace activity, which is displayed in the Bot Framework Emulator.
                await turnContext.TraceActivityAsync(
                    "OnTurnError Trace",
                    exception.Message,
                    "https://www.botframework.com/schemas/error",
                    "TurnError");
            };
        }
    }

Nachdem Sie den Codeausschnitt für TeamsSSOTokenExchangeMiddlewarehinzugefügt haben, muss der folgende Code angezeigt werden:

    // index.js is used to setup and configure your bot.

    // Import required packages
    const path = require('path');

    // Read botFilePath and botFileSecret from .env file.
    const ENV_FILE = path.join(__dirname, '.env');
    require('dotenv').config({ path: ENV_FILE });

    const restify = require('restify');

    // Import required bot services.
    // See https://learn.microsoft.com/azure/bot-service/bot-builder-basics?view=azure-bot-service-4.0 to learn more about the different parts of a bot.
    const {
        CloudAdapter,
        ConversationState,
        MemoryStorage,
        UserState,
        ConfigurationBotFrameworkAuthentication,
        TeamsSSOTokenExchangeMiddleware
    } = require('botbuilder');

    const { TeamsBot } = require('./bots/teamsBot');
    const { MainDialog } = require('./dialogs/mainDialog');
    const { env } = require('process');

    const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(process.env);

    var conname = env.connectionName;

    console.log(`\n${ conname } is the con name`);

    // Create adapter.
    // See https://learn.microsoft.com/javascript/api/botbuilder-core/botadapter?view=botbuilder-ts-latest to learn more about how bot adapter.
    const adapter = new CloudAdapter(botFrameworkAuthentication);
    const memoryStorage = new MemoryStorage();
    const tokenExchangeMiddleware = new TeamsSSOTokenExchangeMiddleware(memoryStorage, env.connectionName);

    adapter.use(tokenExchangeMiddleware);
    adapter.onTurnError = async (context, error) => {
        // This check writes out errors to console log .vs. app insights.
        // NOTE: In production environment, you must consider logging this to Azure
        //       application insights. See https://learn.microsoft.com/azure/bot-service/bot-builder-telemetry?view=azure-bot-service-4.0&tabs=csharp for telemetry
        //       configuration instructions.
        console.error(`\n [onTurnError] unhandled error: ${ error }`);

        // Send a trace activity, which is displayed in Bot Framework Emulator.
        await context.sendTraceActivity(
            'OnTurnError Trace',
            `${ error }`,
            'https://www.botframework.com/schemas/error',
            'TurnError'
        );

        // Send a message to the user.
        await context.sendActivity('The bot encountered an error or bug.');
        await context.sendActivity('To continue to run this bot, please fix the bot source code.');
        // Clear out state.
        await conversationState.delete(context);
    };

    // Define the state store for your bot.
    // See https://aka.ms/about-bot-state to learn more about using MemoryStorage.
    // A bot requires a state storage system to persist the dialog and user state between messages.
    //const memoryStorage = new MemoryStorage();

    // Create conversation and user state with in-memory storage provider.
    const conversationState = new ConversationState(memoryStorage);
    const userState = new UserState(memoryStorage);

    // Create the main dialog.
    const dialog = new MainDialog();
    // Create the bot that will handle incoming messages.
    const bot = new TeamsBot(conversationState, userState, dialog);

    // Create HTTP server.
    const server = restify.createServer();
    server.use(restify.plugins.bodyParser());

    server.listen(process.env.port || process.env.PORT || 3978, function() {
        console.log(`\n${ server.name } listening to ${ server.url }`);
        console.log('\nGet Bot Framework Emulator: https://aka.ms/botframework-emulator');
        console.log('\nTo talk to your bot, open the emulator select "Open Bot"');
    });

    // Listen for incoming requests.
    server.post('/api/messages', async (req, res) => {
        // Route received a request to adapter for processing.
        await adapter.process(req, res, (context) => bot.run(context));
    });

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

Zustimmungsdialogfeld für Bot-SSO

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

Wenn die Bot-Benutzeroberfläche über eine Anmeldeschaltfläche verfügt, wird der Anmeldeflow für Bots aktiviert. Sie können die Berechtigungen bestimmen, für die die Zustimmung des App-Benutzers erforderlich ist. Verwenden Sie diesen Ansatz, wenn Ihre App andere Graph-Berechtigungen als openidbenötigt.
Wenn der Bot nicht über eine Anmeldeschaltfläche auf der OAuth-Karte verfügt, ist die Zustimmung des App-Benutzers für einen minimalen Berechtigungssatz erforderlich. Dieses Token ist nützlich für die Standardauthentifizierung und zum Abrufen der E-Mail-Adresse des App-Benutzers.

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 der Zustimmung kann der App-Benutzer auf Ihre Bot-App zugreifen und diese für die erteilten Berechtigungen und Bereiche verwenden.

Hinweis

Nachdem der App-Benutzer seine Zustimmung erteilt hat, muss er keine weiteren Berechtigungen mehr erteilen. Wenn die im Microsoft Entra-Bereich definierten Berechtigungen geändert werden, muss der App-Benutzer möglicherweise erneut zustimmen. Wenn die Zustimmungsaufforderung dem App-Benutzer jedoch keinen Zugriff gewährt, greift die Bot-App auf die Anmeldekarte zurück.

Wichtig

Szenarien, in denen keine Zustimmungsdialogfelder erforderlich sind:

Wenn der Mandantenadministrator die Zustimmung im Namen des Mandanten erteilt hat, müssen App-Benutzer überhaupt nicht zur Zustimmung aufgefordert werden. Dies bedeutet, dass die App-Benutzer die Zustimmungsdialoge nicht sehen und nahtlos auf die App zugreifen können.
Wenn Ihre Microsoft Entra-App im selben Mandanten registriert ist, von dem Aus Sie eine Authentifizierung in Teams anfordern, kann der App-Benutzer nicht zur Zustimmung aufgefordert werden und 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 bei der SSO-Authentifizierung in Teams.

Hinzufügen von Code zum Empfangen des Tokens

Die Antwort mit dem Token wird über eine Aufrufaktivität mit demselben Schema gesendet wie andere Aufrufaktivitäten, die die Bots heute erhalten. Der einzige Unterschied ist der Aufrufname, die Anmeldung/tokenExchange und das Wertfeld . Das Feld Wert enthält die ID, eine Zeichenfolge der ursprünglichen Anforderung zum Abrufen des Tokens, und das Feld Token, einen Zeichenfolgenwert, der das Token enthält.

Verwenden Sie den folgenden Codeausschnitt, um die Antwort aufzurufen:

C#
JavaScript

public MainDialog(IConfiguration configuration, ILogger<MainDialog> logger)
            : base(nameof(MainDialog), configuration["ConnectionName"])
        {
            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)
                    EndOnInvalidMessage = true
                }));

            AddDialog(new ConfirmPrompt(nameof(ConfirmPrompt)));

            AddDialog(new WaterfallDialog(nameof(WaterfallDialog), new WaterfallStep[]
            {
                PromptStepAsync,
                LoginStepAsync,
            }));

            // The initial child Dialog to run.
            InitialDialogId = nameof(WaterfallDialog);
        }


private async Task<DialogTurnResult> PromptStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
        {
            return await stepContext.BeginDialogAsync(nameof(OAuthPrompt), null, cancellationToken);
        }

private async Task<DialogTurnResult> LoginStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
        {

            var tokenResponse = (TokenResponse)stepContext.Result;
            if (tokenResponse?.Token != null)
            {
                var token = tokenResponse.Token;

                // On successful login, the token contains sign in token.
            }
            else 
            {
                await stepContext.Context.SendActivityAsync(MessageFactory.Text("Login was not successful please try again."), cancellationToken);
            }            

            return await stepContext.EndDialogAsync(cancellationToken: cancellationToken);
        }

class MainDialog {

        this.addDialog(new OAuthPrompt(OAUTH_PROMPT, {
                    connectionName: process.env.connectionName,
                    text: 'Please Sign In',
                    title: 'Sign In',
                    timeout: 300000
                }));

        this.addDialog(new ConfirmPrompt(CONFIRM_PROMPT));

        this.addDialog(new WaterfallDialog(MAIN_WATERFALL_DIALOG, [
                    this.promptStep.bind(this),
                    this.loginStep.bind(this),
                ]));

        this.initialDialogId = MAIN_WATERFALL_DIALOG;

    }

async promptStep(stepContext) {
        try {
            return await stepContext.beginDialog(OAUTH_PROMPT);
        } catch (err) {
            console.error(err);
        }
    }

async loginStep(stepContext) {
        // 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.
        const tokenResponse = stepContext.result;
        if (!tokenResponse || !tokenResponse.token) {
            await stepContext.context.sendActivity('Login was not successful please try again.');
        } else {
            const token = tokenResponse.token;
            // On successful login, the token contains sign in token.
        }
        return await stepContext.endDialog();
    }

Hinweis

Die Codeausschnitte verwenden den Wasserfalldialog. Weitere Informationen finden Sie unter Informationen zu Komponenten- und Wasserfalldialogen.

Überprüfen des Zugriffstokens

Web-APIs auf Ihrem Server müssen das Zugriffstoken decodieren und überprüfen, ob es vom Client gesendet wird.

Hinweis

Wenn Sie Bot Framework verwenden, übernimmt es die Überprüfung des Zugriffstokens. Wenn Sie Bot Framework nicht verwenden, befolgen Sie die Richtlinien in diesem Abschnitt.

Weitere Informationen zum Überprüfen des Zugriffstokens finden Sie unter Überprüfen von Token.

Es gibt eine Reihe von Bibliotheken, welche die JWT-Überprüfung verarbeiten können. Die grundlegende Überprüfung umfasst:

Überprüfen, ob das Token wohlgeformt ist.
Überprüfen, ob das Token von der beabsichtigten Autorität ausgestellt wurde.
Überprüfen, ob das Token für die Web-API verwendet wird.

Beachten Sie bei der Überprüfung des Tokens die folgenden Richtlinien:

Gültige SSO-Token werden von Microsoft Entra ID ausgestellt. Der iss Anspruch im Token muss mit diesem Wert beginnen.
Der Parameter des aud1 Tokens wird auf die App-ID festgelegt, die während der Registrierung der Microsoft Entra-App generiert wurde.
Der Parameter des scp Tokens ist auf access_as_userfestgelegt.

Beispielzugriffstoken

Der folgende Codeausschnitt ist eine typische decodierte Nutzlast eines Zugriffstokens:

{
    aud: "2c3caa80-93f9-425e-8b85-0745f50c0d24",
    iss: "https://login.microsoftonline.com/fec4f964-8bc9-4fac-b972-1c1da35adbcd/v2.0",
    iat: 1521143967,
    nbf: 1521143967,
    exp: 1521147867,
    aio: "ATQAy/8GAAAA0agfnU4DTJUlEqGLisMtBk5q6z+6DB+sgiRjB/Ni73q83y0B86yBHU/WFJnlMQJ8",
    azp: "e4590ed6-62b3-5102-beff-bad2292ab01c",
    azpacr: "0",
    e_exp: 262800,
    name: "Mila Nikolova",
    oid: "6467882c-fdfd-4354-a1ed-4e13f064be25",
    preferred_username: "milan@contoso.com",
    scp: "access_as_user",
    sub: "XkjgWjdmaZ-_xDmhgN1BMP2vL2YOfeVxfPT_o8GRWaw",
    tid: "fec4f964-8bc9-4fac-b972-1c1da35adbcd",
    uti: "MICAQyhrH02ov54bCtIDAA",
    ver: "2.0"
}

Behandeln der Abmeldung von App-Benutzern

Verwenden Sie den folgenden Codeausschnitt, um das Zugriffstoken für den Fall zu verarbeiten, dass sich der App-Benutzer abmeldet:

C#
JavaScript

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

                // Allow logout anywhere in the command.
                if (text.IndexOf("logout") >= 0)
                {
                    // 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;
        }

    async interrupt(innerDc) {
        if (innerDc.context.activity.type === ActivityTypes.Message) {
            const text = innerDc.context.activity.text.toLowerCase();
            if (text === 'logout') {
                const userTokenClient = innerDc.context.turnState.get(innerDc.context.adapter.UserTokenClientKey);

                const { activity } = innerDc.context;
                await userTokenClient.signOutUser(activity.from.id, this.connectionName, activity.channelId);

                await innerDc.context.sendActivity('You have been signed out.');
                return await innerDc.cancelAllDialogs();
            }
        }
    }

Codebeispiel

Beispielname	Beschreibung	C#	Node.js
Bot Conversation SSO – Schnellstart	Dieser Beispielcode zeigt die ersten Schritte mit SSO in einem Bot für Microsoft Teams.	View	View

Hinweis

OnTeamsMessagingExtensionQueryAsync und OnTeamsAppBasedLinkQueryAsync aus der TeamsMessagingExtensionsSearchAuthConfigBot.cs Datei sind die einzigen SSO-Handler, die unterstützt werden. Andere SSO-Handler werden nicht unterstützt.

In diesem Abschnitt werden folgende Themen behandelt:

Aktualisieren von Entwicklungsumgebungsvariablen
Hinzufügen von Code zum Anfordern eines Tokens
Hinzufügen von Code zum Empfangen des Tokens
Hinzufügen eines Tokens zum Bot Framework-Tokenspeicher
Behandeln der Abmeldung von App-Benutzern

Aktualisieren von Entwicklungsumgebungsvariablen

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

So aktualisieren Sie die Entwicklungsumgebungsvariablen:

Öffnen Sie das App-Projekt.
Öffnen Sie die ./env Datei für Ihr Projekt.
Aktualisieren Sie die folgenden Variablen:
- Aktualisieren Sie für MicrosoftAppIddie Botregistrierungs-ID von Microsoft Entra ID.
- Aktualisieren Sie für MicrosoftAppPasswordden geheimen Clientschlüssel für die Botregistrierung.
- Aktualisieren Sie für ConnectionNameden Namen der OAuth-Verbindung, die Sie in Microsoft Entra ID konfiguriert haben.
- Aktualisieren MicrosoftAppTenantIdSie für die Mandanten-ID.
Speichern Sie die Datei.

Sie haben nun die erforderlichen Umgebungsvariablen für Ihre Bot-App und SSO konfiguriert. Fügen Sie als Nächstes den Code für die Verarbeitung von Token hinzu.

Hinzufügen von Code zum Anfordern eines Tokens

Hinweis

Das Microsoft Bot Framework OAuthPrompt oder MultiProviderAuthDialog wird für die SSO-Authentifizierung unterstützt.

So aktualisieren Sie den Code Ihrer App:

Fügen Sie Codeausschnitt für TeamsSSOTokenExchangeMiddlewarehinzu.
- C#
- JavaScript
Fügen Sie den folgenden Codeausschnitt zu AdapterWithErrorHandler.cs (oder der entsprechenden Klasse im Code Ihrer App) hinzu:
```
base.Use(new TeamsSSOTokenExchangeMiddleware(storage, configuration["ConnectionName"]));
```
Fügen Sie den folgenden Codeausschnitt zu index.js (oder der entsprechenden Klasse im Code Ihrer App) hinzu:
```
   const {TeamsSSOTokenExchangeMiddleware} = require('botbuilder');
   const tokenExchangeMiddleware = new TeamsSSOTokenExchangeMiddleware(memoryStorage, env.connectionName);
   adapter.use(tokenExchangeMiddleware);
```
Hinweis

Sie erhalten möglicherweise mehrere Antworten für eine bestimmte Anfrage, wenn der Benutzer mehrere aktive Endpunkte hat. Sie müssen alle doppelten oder redundanten Antworten mit dem Token entfernen. Weitere Informationen zu signin/tokenExchange finden Sie unter TeamsSSOTokenExchangeMiddleware-Klasse.

Verwenden Sie den folgenden Codeausschnitt, um ein Token anzufordern.

C#
JavaScript

Nachdem Sie hinzugefügt haben AdapterWithErrorHandler.cs, muss der folgende Code angezeigt werden:

    public class AdapterWithErrorHandler : CloudAdapter
    {
        public AdapterWithErrorHandler(
            IConfiguration configuration,
            IHttpClientFactory httpClientFactory,
            ILogger<IBotFrameworkHttpAdapter> logger,
            IStorage storage,
            ConversationState conversationState)
            : base(configuration, httpClientFactory, logger)
        {
            base.Use(new TeamsSSOTokenExchangeMiddleware(storage, configuration["ConnectionName"]));

            OnTurnError = async (turnContext, exception) =>
            {
                // Log any leaked exception from the application.
                // NOTE: In production environment, you must consider logging this to
                // Azure Application Insights. Visit https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-telemetry?view=azure-bot-service-4.0&tabs=csharp to see how
                // to add telemetry capture to your bot.
                logger.LogError(exception, $"[OnTurnError] unhandled error : {exception.Message}");

                // Send a message to the user.
                await turnContext.SendActivityAsync("The bot encountered an error or bug.");
                await turnContext.SendActivityAsync("To continue to run this bot, please fix the bot source code.");

                if (conversationState != null)
                {
                    try
                    {
                        // Delete the conversationState for the current conversation to prevent the
                        // bot from getting stuck in an error-loop caused by being in a bad state.
                        // ConversationState must be thought of as similar to "cookie-state" in a Web pages.
                        await conversationState.DeleteAsync(turnContext);
                    }
                    catch (Exception e)
                    {
                        logger.LogError(e, $"Exception caught on attempting to Delete ConversationState : {e.Message}");
                    }
                }

                // Send a trace activity, which will be displayed in the Bot Framework Emulator.
                await turnContext.TraceActivityAsync(
                    "OnTurnError Trace",
                    exception.Message,
                    "https://www.botframework.com/schemas/error",
                    "TurnError");
            };
        }
    }

Nachdem Sie den Code zu hinzugefügt haben index.js, muss der folgende Code angezeigt werden:

    // index.js is used to setup and configure your bot.

    // Import required packages.
    const path = require('path');

    // Read botFilePath and botFileSecret from .env file.
    const ENV_FILE = path.join(__dirname, '.env');
    require('dotenv').config({ path: ENV_FILE });

    const restify = require('restify');

    // Import required bot services.
    // See https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-basics?view=azure-bot-service-4.0 to learn more about the different parts of a bot.
    const {
        CloudAdapter,
        ConversationState,
        MemoryStorage,
        UserState,
        ConfigurationBotFrameworkAuthentication,
        TeamsSSOTokenExchangeMiddleware
    } = require('botbuilder');

    const { TeamsBot } = require('./bots/teamsBot');
    const { MainDialog } = require('./dialogs/mainDialog');
    const { env } = require('process');

    const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(process.env);

    var conname = env.connectionName;

    console.log(`\n${ conname } is the con name`);

    // Create adapter.
    // See https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-basics?view=azure-bot-service-4.0 to learn more about how bots work.
    const adapter = new CloudAdapter(botFrameworkAuthentication);
    const memoryStorage = new MemoryStorage();
    const tokenExchangeMiddleware = new TeamsSSOTokenExchangeMiddleware(memoryStorage, env.connectionName);

    adapter.use(tokenExchangeMiddleware);
    adapter.onTurnError = async (context, error) => {
        // This check writes out errors to console log .vs. app insights.
        // NOTE: In production environment, you must consider logging this to Azure application insights. See https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-telemetry?view=azure-bot-service-4.0&tabs=csharp for telemetry configuration instructions.
        console.error(`\n [onTurnError] unhandled error: ${ error }`);

        // Send a trace activity, which will be displayed in Bot Framework Emulator.
        await context.sendTraceActivity(
            'OnTurnError Trace',
            `${ error }`,
            'https://www.botframework.com/schemas/error',
            'TurnError'
        );

        // Send a message to the user.
        await context.sendActivity('The bot encountered an error or bug.');
        await context.sendActivity('To continue to run this bot, please fix the bot source code.');
        // Clear out state.
        await conversationState.delete(context);
    };

    // Define the state store for your bot.
    // See https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-howto-v4-state?view=azure-bot-service-4.0&branch=live&tabs=csharp to learn more about using MemoryStorage.
    // A bot requires a state storage system to persist the dialog and user state between messages.
 //const memoryStorage = new MemoryStorage();

    // Create conversation and user state with in-memory storage provider.
    const conversationState = new ConversationState(memoryStorage);
    const userState = new UserState(memoryStorage);

    // Create the main dialog.
    const dialog = new MainDialog();
    // Create the bot that will handle incoming messages.
    const bot = new TeamsBot(conversationState, userState, dialog);

    // Create HTTP server.
    const server = restify.createServer();
    server.use(restify.plugins.bodyParser());

    server.listen(process.env.port || process.env.PORT || 3978, function() {
        console.log(`\n${ server.name } listening to ${ server.url }`);
        console.log('\nGet Bot Framework Emulator: https://aka.ms/botframework-emulator');
        console.log('\nTo talk to your bot, open the emulator select "Open Bot"');
    });

    // Listen for incoming requests.
    server.post('/api/messages', async (req, res) => {
        // Route received a request to adapter for processing.
        await adapter.process(req, res, (context) => bot.run(context));
    });

Wenn der App-Benutzer Ihre App zum ersten Mal verwendet, muss er der SSO-Authentifizierung zustimmen.

Wenn der App-Benutzer den Benutzernamen auswählt, wird die Berechtigung erteilt, und er kann die App verwenden.

SSO-Authentifizierung für die Nachrichtenerweiterungs-App abgeschlossen

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 der Zustimmung kann der App-Benutzer auf Ihre Nachrichtenerweiterungs-App zugreifen und diese für die erteilten Berechtigungen und Bereiche verwenden.

Wichtig

Szenarien, in denen keine Zustimmungsdialogfelder erforderlich sind:

Wenn der Mandantenadministrator die Zustimmung im Namen des Mandanten erteilt hat, müssen App-Benutzer überhaupt nicht zur Zustimmung aufgefordert werden. Dies bedeutet, dass die App-Benutzer die Zustimmungsdialoge nicht sehen und nahtlos auf die App zugreifen können.

Wenn Fehler auftreten, lesen Sie Problembehandlung bei der SSO-Authentifizierung in Teams.

Hinzufügen von Code zum Empfangen des Tokens

Verwenden Sie das folgende Codeausschnittbeispiel, um die Antwort aufzurufen:

C#
JavaScript

public MainDialog(IConfiguration configuration, ILogger<MainDialog> logger)
            : base(nameof(MainDialog), configuration["ConnectionName"])
        {
            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)
                    EndOnInvalidMessage = true
                }));

            AddDialog(new ConfirmPrompt(nameof(ConfirmPrompt)));

            AddDialog(new WaterfallDialog(nameof(WaterfallDialog), new WaterfallStep[]
            {
                PromptStepAsync,
                LoginStepAsync,
            }));

            // The initial child Dialog to run.
            InitialDialogId = nameof(WaterfallDialog);
        }


private async Task<DialogTurnResult> PromptStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
        {
            return await stepContext.BeginDialogAsync(nameof(OAuthPrompt), null, cancellationToken);
        }

private async Task<DialogTurnResult> LoginStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
        {
            
            var tokenResponse = (TokenResponse)stepContext.Result;
            if (tokenResponse?.Token != null)
            {
                var token = tokenResponse.Token;

                // On successful login, the token contains sign in token.
            }
            else 
            {
                await stepContext.Context.SendActivityAsync(MessageFactory.Text("Login was not successful please try again."), cancellationToken);
            }            

            return await stepContext.EndDialogAsync(cancellationToken: cancellationToken);
        }

 class MainDialog {
   
         this.addDialog(new OAuthPrompt(OAUTH_PROMPT, {
                     connectionName: process.env.connectionName,
                     text: 'Please Sign In',
                     title: 'Sign In',
                     timeout: 300000
                 }));
 
         this.addDialog(new ConfirmPrompt(CONFIRM_PROMPT));
 
         this.addDialog(new WaterfallDialog(MAIN_WATERFALL_DIALOG, [
                     this.promptStep.bind(this),
                     this.loginStep.bind(this),
                 ]));
 
         this.initialDialogId = MAIN_WATERFALL_DIALOG;
 
     }
 
 async promptStep(stepContext) {
         try {
             return await stepContext.beginDialog(OAUTH_PROMPT);
         } catch (err) {
             console.error(err);
         }
     }
 
 async loginStep(stepContext) {
         // 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.
         const tokenResponse = stepContext.result;
         if (!tokenResponse || !tokenResponse.token) {
             await stepContext.context.sendActivity('Login was not successful please try again.');
         } else {
             const token = tokenResponse.token;
             // On successful login, the token contains sign in token.
         }
         return await stepContext.endDialog();
     }

Hinweis

Die Codeausschnitte verwenden den Wasserfalldialog-Bot. Weitere Informationen zum Wasserfalldialog finden Sie unter Informationen zu Komponenten- und Wasserfalldialogen.

Sie erhalten das Token im OnTeamsMessagingExtensionQueryAsync Handler in der turnContext.Activity.Value Nutzlast oder im OnTeamsAppBasedLinkQueryAsync, je nachdem, für welches Szenario Sie einmaliges Anmelden aktivieren.

JObject valueObject=JObject.FromObject(turnContext.Activity.Value);
if(valueObject["authentication"] !=null)
 {
    JObject authenticationObject=JObject.FromObject(valueObject["authentication"]);
    if(authenticationObject["token"] !=null)
 }

Überprüfen des Zugriffstokens

Web-APIs auf Ihrem Server müssen das Zugriffstoken decodieren und überprüfen, ob es vom Client gesendet wird.

Hinweis

Wenn Sie Bot Framework verwenden, übernimmt es die Überprüfung des Zugriffstokens. Wenn Sie Bot Framework nicht verwenden, befolgen Sie die Richtlinien in diesem Abschnitt.

Weitere Informationen zum Überprüfen des Zugriffstokens finden Sie unter Überprüfen von Token.

Es gibt eine Reihe von Bibliotheken, welche die JWT-Überprüfung verarbeiten können. Die grundlegende Überprüfung umfasst:

Überprüfen, ob das Token wohlgeformt ist.
Überprüfen, ob das Token von der beabsichtigten Autorität ausgestellt wurde.
Überprüfen, ob das Token für die Web-API verwendet wird.

Beachten Sie bei der Überprüfung des Tokens die folgenden Richtlinien:

Gültige SSO-Token werden von Microsoft Entra ID ausgestellt. Der iss Anspruch im Token muss mit diesem Wert beginnen.
Der Parameter des aud1 Tokens wird auf die App-ID festgelegt, die während der Registrierung der Microsoft Entra-App generiert wurde.
Der Parameter des scp Tokens ist auf access_as_userfestgelegt.

Beispielzugriffstoken

Der folgende Codeausschnitt ist eine typische decodierte Nutzlast eines Zugriffstokens:

{
    aud: "2c3caa80-93f9-425e-8b85-0745f50c0d24",
    iss: "https://login.microsoftonline.com/fec4f964-8bc9-4fac-b972-1c1da35adbcd/v2.0",
    iat: 1521143967,
    nbf: 1521143967,
    exp: 1521147867,
    aio: "ATQAy/8GAAAA0agfnU4DTJUlEqGLisMtBk5q6z+6DB+sgiRjB/Ni73q83y0B86yBHU/WFJnlMQJ8",
    azp: "e4590ed6-62b3-5102-beff-bad2292ab01c",
    azpacr: "0",
    e_exp: 262800,
    name: "Mila Nikolova",
    oid: "6467882c-fdfd-4354-a1ed-4e13f064be25",
    preferred_username: "milan@contoso.com",
    scp: "access_as_user",
    sub: "XkjgWjdmaZ-_xDmhgN1BMP2vL2YOfeVxfPT_o8GRWaw",
    tid: "fec4f964-8bc9-4fac-b972-1c1da35adbcd",
    uti: "MICAQyhrH02ov54bCtIDAA",
    ver: "2.0"
}

Hinzufügen eines Tokens zum Bot Framework-Tokenspeicher

Wenn Sie die OAuth-Verbindung verwenden, müssen Sie das Token im Bot Framework-Tokenspeicher aktualisieren oder hinzufügen. Fügen Sie das folgende Codeausschnittbeispiel zu (oder der entsprechenden Datei im Code Ihrer App) hinzu, um TeamsMessagingExtensionsSearchAuthConfigBot.cs das Token im Store zu aktualisieren oder hinzuzufügen:

Hinweis

Sie finden das Beispiel TeamsMessagingExtensionsSearchAuthConfigBot.cs unter Tab, Bot, and Message Extension (ME) SSO.

C#
JavaScript

protected override async Task<InvokeResponse> OnInvokeActivityAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
     {
         JObject valueObject = JObject.FromObject(turnContext.Activity.Value);
         if (valueObject["authentication"] != null)
         {
             JObject authenticationObject = JObject.FromObject(valueObject["authentication"]);
             if (authenticationObject["token"] != null)
             {
                 //If the token is NOT exchangeable, then return 412 to require user consent.
                 if (await TokenIsExchangeable(turnContext, cancellationToken))
                 {
                     return await base.OnInvokeActivityAsync(turnContext, cancellationToken).ConfigureAwait(false);
                 }
                 else
                 {
                     var response = new InvokeResponse();
                     response.Status = 412;
                     return response;
                 }
             }
         }
         return await base.OnInvokeActivityAsync(turnContext, cancellationToken).ConfigureAwait(false);
     }
     private async Task<bool> TokenIsExchangeable(ITurnContext turnContext, CancellationToken cancellationToken)
     {
         TokenResponse tokenExchangeResponse = null;
         try
         {
             JObject valueObject = JObject.FromObject(turnContext.Activity.Value);
             var tokenExchangeRequest =
             ((JObject)valueObject["authentication"])?.ToObject<TokenExchangeInvokeRequest>();
             var userTokenClient = turnContext.TurnState.Get<UserTokenClient>();
             tokenExchangeResponse = await userTokenClient.ExchangeTokenAsync(
                             turnContext.Activity.From.Id,
                              _connectionName,
                              turnContext.Activity.ChannelId,
                              new TokenExchangeRequest
              {
                  Token = tokenExchangeRequest.Token,
              },
               cancellationToken).ConfigureAwait(false);
         }
 #pragma warning disable CA1031 //Do not catch general exception types (ignoring, see comment below)
         catch
 #pragma warning restore CA1031 //Do not catch general exception types
         {
             //ignore exceptions.
             //if token exchange failed for any reason, tokenExchangeResponse above remains null, and a failure invoke response is sent to the caller.
             //This ensures the caller knows that the invoke has failed.
         }
         if (tokenExchangeResponse == null || string.IsNullOrEmpty(tokenExchangeResponse.Token))
         {
             return false;
         }
         return true;
     }


async onInvokeActivity(context) {
    console.log('onInvoke, ' + context.activity.name);
    const valueObj = context.activity.value;
    if (valueObj.authentication) {
        const authObj = valueObj.authentication;
        if (authObj.token) {
            // If the token is NOT exchangeable, then do NOT deduplicate requests.
            if (await this.tokenIsExchangeable(context)) {
                return await super.onInvokeActivity(context);
            } else {
                const response = {
                    status: 412
                };
                return response;
            }
        }
    }
    return await super.onInvokeActivity(context);
}

async tokenIsExchangeable(context) {
    let tokenExchangeResponse = null;
    try {
        const valueObj = context.activity.value;
        const tokenExchangeRequest = valueObj.authentication;
        tokenExchangeResponse = await context.adapter.exchangeToken(context,
        process.env.connectionName,
        context.activity.from.id,
            { token: tokenExchangeRequest.token });
    } catch (err) {
        console.log('tokenExchange error: ' + err);
        // Ignore Exceptions
        // If token exchange failed for any reason, tokenExchangeResponse above stays null , and hence we send back a failure invoke response to the caller.
    }
    if (!tokenExchangeResponse || !tokenExchangeResponse.token) {
        return false;
    }
    return true;
}

Behandeln der Abmeldung von App-Benutzern

Verwenden Sie den folgenden Codeausschnitt, um das Zugriffstoken für den Fall zu verarbeiten, dass sich der App-Benutzer abmeldet:

C#
JavaScript

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

                // Allow logout anywhere in the command.
                if (text.IndexOf("logout") >= 0)
                {
                    // 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;
        }

    async interrupt(innerDc) {
        if (innerDc.context.activity.type === ActivityTypes.Message) {
            const text = innerDc.context.activity.text.toLowerCase();
            if (text === 'logout') {
                const userTokenClient = innerDc.context.turnState.get(innerDc.context.adapter.UserTokenClientKey);

                const { activity } = innerDc.context;
                await userTokenClient.signOutUser(activity.from.id, this.connectionName, activity.channelId);

                await innerDc.context.sendActivity('You have been signed out.');
                return await innerDc.cancelAllDialogs();
            }
        }
    }

Codebeispiel

Dieser Abschnitt enthält ein Beispiel für das Sdk für die Botauthentifizierung v3.

Beispielname	Beschreibung	.NET	Node.js	Python	Manifest
Botauthentifizierung	In diesem Beispiel wird gezeigt, wie Sie mit der Authentifizierung in einem Bot für Teams beginnen.	View	View	View	View
Tab-, Bot- und Nachrichtenerweiterung (ME) SSO	Dieses Beispiel zeigt SSO für Registerkarten-, Bot- und Nachrichtenerweiterung – Suche, Aktion, Link unfurl.	View	View	–	View
Registerkarten-, Bot- und Nachrichtenerweiterung	In diesem Beispiel wird gezeigt, wie Sie die Authentifizierung in Bot, Registerkarte und Nachrichtenerweiterung mit SSO überprüfen.	View	View	–	View

Nächster Schritt

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

Freigeben über

Hinzufügen von Code zum Aktivieren des einmaligen Anmeldens in Ihrer Bot-App

Aktualisieren von Entwicklungsumgebungsvariablen

Hinzufügen von Code zum Verarbeiten eines Zugriffstokens

Hinzufügen von Code zum Empfangen des Tokens

Überprüfen des Zugriffstokens

Beispielzugriffstoken

Behandeln der Abmeldung von App-Benutzern

Codebeispiel

Aktualisieren von Entwicklungsumgebungsvariablen

Hinzufügen von Code zum Anfordern eines Tokens

Hinzufügen von Code zum Empfangen des Tokens

Überprüfen des Zugriffstokens

Beispielzugriffstoken

Hinzufügen eines Tokens zum Bot Framework-Tokenspeicher

Behandeln der Abmeldung von App-Benutzern

Codebeispiel

Nächster Schritt

Zusätzliche Ressourcen

Freigeben über

Hinzufügen von Code zum Aktivieren des einmaligen Anmeldens in Ihrer Bot-App

Aktualisieren von Entwicklungsumgebungsvariablen

Hinzufügen von Code zum Verarbeiten eines Zugriffstokens

Zustimmungsdialogfeld zum Abrufen des Zugriffstokens

Hinzufügen von Code zum Empfangen des Tokens

Überprüfen des Zugriffstokens

Beispielzugriffstoken

Behandeln der Abmeldung von App-Benutzern

Codebeispiel

Aktualisieren von Entwicklungsumgebungsvariablen

Hinzufügen von Code zum Anfordern eines Tokens

Zustimmungsdialogfeld zum Abrufen des Zugriffstokens

Hinzufügen von Code zum Empfangen des Tokens

Überprüfen des Zugriffstokens

Beispielzugriffstoken

Hinzufügen eines Tokens zum Bot Framework-Tokenspeicher

Behandeln der Abmeldung von App-Benutzern

Codebeispiel

Nächster Schritt

Zusätzliche Ressourcen