Adicionar código para habilitar o SSO em seu aplicativo bot

Antes de adicionar código para habilitar o logon único (SSO), certifique-se de configurar seu aplicativo e recurso de bot no centro de administração do Microsoft Entra.

Configurar o aplicativo bot no Microsoft Entra ID

Você precisa configurar o código do seu aplicativo para obter um token de acesso do Microsoft Entra ID. O token de acesso é emitido em nome do aplicativo bot.

Observação

Se você criou seu aplicativo do Teams usando o Microsoft Teams Toolkit, poderá habilitar o SSO para seu aplicativo usando as instruções no módulo Ferramentas e SDKs. Para obter mais informações, confira Adicionar logon único ao aplicativo Teams. O Kit de Ferramentas do Teams dá suporte ao SSO para aplicativos JavaScript, TypeScript e C# no Visual Studio Code.

Esta seção cobre:

Atualizar variáveis de ambiente de desenvolvimento
Inicializar o aplicativo com OAuth
Lidar com a entrada e o recebimento de token
Lidar com falhas de entrada
Lidar com a saída do usuário do aplicativo

Atualizar variáveis de ambiente de desenvolvimento

Você definiu o segredo do cliente e a configuração de conexão OAuth para o aplicativo no Microsoft Entra ID. Você deve configurar o código com esses valores.

Para atualizar as variáveis de ambiente de desenvolvimento:

Abra o projeto do aplicativo bot.
Abra o arquivo de ambiente (.env) do seu projeto.
Atualize as seguintes variáveis:
- Para CLIENT_ID, atualize a ID do bot do Microsoft Entra ID.
- Para CLIENT_SECRET, atualize o segredo do cliente.
- Para CONNECTION_NAME, atualize o nome da conexão OAuth configurada no Microsoft Entra ID.
- Para TENANT_ID, atualize a ID do locatário.
Observação

Você pode personalizar a URL de redirecionamento OAuth para seu bot e provedor de identidade com base em seus requisitos de residência de dados, independentemente de seu bot estar na nuvem pública, na nuvem do Microsoft Azure Governamental ou no Microsoft Azure operado pela 21Vianet. Para URLs OAuth e lista de residência de dados, consulte Suporte a URL OAuth no Serviço de Bot de IA do Azure.
Salve o arquivo.

Agora você configurou as variáveis de ambiente necessárias para seu aplicativo de bot e SSO. Em seguida, inicialize o aplicativo com OAuth.

Inicializar o aplicativo com OAuth

O SDK do Teams simplifica a inicialização do aplicativo com uma única App classe que lida com o ciclo de vida do servidor, a autenticação e a troca de token internamente.

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

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

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

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

import os
from microsoft_teams.apps import App

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

Observação

A classe lida internamente com toda a App configuração do adaptador, middleware, tratamento de erros e configuração do servidor.

O usuário precisa consentir com as permissões solicitadas pelo aplicativo bot para obter o token de acesso. A caixa de diálogo de consentimento aparece com base no escopo do aplicativo.

Chats entre duas pessoas

Quando o usuário do aplicativo estiver usando o aplicativo pela primeira vez e o consentimento do usuário for necessário, a seguinte caixa de diálogo será exibida:

O infográfico mostra a interação de um bot com um usuário em escopo pessoal

Quando o usuário seleciona Continuar, um dos seguintes eventos ocorre:

Se a interface do usuário do bot tiver um botão de entrada, o fluxo de entrada para bots será ativado. Você pode determinar as permissões que exigem o consentimento do usuário do aplicativo. Use essa abordagem se o aplicativo exigir permissões do Graph diferentes de openid.
Se o bot não tiver um botão de entrada no card OAuth, o consentimento do usuário do aplicativo será necessário para um conjunto mínimo de permissões. Esse token é útil para autenticação básica e para obter o endereço de email do usuário do aplicativo.

A caixa de diálogo de consentimento que aparece é para escopos de ID aberta definidos no Microsoft Entra ID. O usuário do aplicativo deve dar consentimento apenas uma vez. Depois de consentir, o usuário do aplicativo pode acessar e usar seu aplicativo bot para as permissões e escopos concedidos.

Chats em grupo

Aqui estão os dois cenários de autenticação no escopo do grupo:

O consentimento do Microsoft Entra ID é necessário
O consentimento do Microsoft Entra ID não é necessário

Quando um bot é adicionado a um chat de grupo pela primeira vez e o consentimento é necessário para um usuário específico, uma caixa de diálogo de consentimento é exibida somente para o usuário que @mentions adicionou o bot. O usuário deve dar consentimento único às permissões solicitadas pelo aplicativo bot para obter o token de acesso.

Desktop
Dispositivo móvel

O usuário @mentions , o bot. Um Cartão Adaptável é exibido para solicitar o consentimento do usuário.

A imagem mostra uma caixa de diálogo de consentimento para área de trabalho

Se o usuário selecionar Adicionar, uma caixa de diálogo de permissões será exibida.

O usuário deve selecionar Aceitar para dar consentimento.
Se o usuário recusar ou a solicitação expirar, o usuário deverá @mention usar o bot novamente para conceder permissão para aquisição de token. O grupo pode ver uma mensagem de bot informando que a autenticação não foi bem-sucedida.

Se as permissões de usuário forem concedidas por padrão ou para aplicativos confiáveis, o usuário com o @mentions bot pode interagir diretamente com o bot sem precisar dar consentimento.

Observação

Depois que o usuário do aplicativo consentir, ele não precisará consentir novamente com nenhuma outra permissão. Se as permissões definidas no escopo do Microsoft Entra forem modificadas, talvez o usuário do aplicativo precise consentir novamente. Se, no entanto, a solicitação de consentimento não permitir o acesso do usuário do aplicativo, o aplicativo bot retornará ao card de entrada.

Importante

Cenários em que as caixas de diálogo de consentimento não são necessárias:

Se o administrador conceder consentimento em nome do locatário, os usuários do aplicativo não precisarão ser solicitados a dar consentimento. Isso significa que os usuários do aplicativo não veem as caixas de diálogo de consentimento e podem acessar o aplicativo sem problemas.
Se o seu aplicativo do Microsoft Entra estiver registrado no mesmo locatário do qual você está solicitando uma autenticação no Teams, o usuário do aplicativo não poderá ser solicitado a consentir e receberá um token de acesso imediatamente. Os usuários do aplicativo consentem com essas permissões somente se o aplicativo do Microsoft Entra estiver registrado em um locatário diferente.

Se você encontrar algum erro, consulte Solucionar problemas de autenticação SSO no Teams.

O SDK do Teams usa manipuladores simples orientados a eventos para autenticação. Use IsSignedIn para marcar o status da autenticação, SignIn() disparar o fluxo de SSO e assinar o evento para lidar com a signin autenticação bem-sucedida.

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

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

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.")

Observação

O SDK lida com a troca e validação de token internamente. Você não precisa mais gerenciar OAuthPromptmanualmente , WaterfallDialog, ou MainDialog classes.

Ao usar o SSO, se a troca de token falhar, o Teams enviará uma signin/failure atividade de invocação ao seu aplicativo. O SDK inclui um manipulador padrão integrado que registra um aviso com orientações de solução de problemas acionáveis. Opcionalmente, você pode registrar seu próprio manipulador para personalizar o comportamento:

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

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

@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.")

Lidar com a saída do usuário do aplicativo

Chame o signout método para remover o token de autenticação do usuário do cache do serviço de Token de Usuário, desconectando-o efetivamente. O SDK do Teams substitui o padrão anterior de uso DialogContextde , UserTokenClient, e CancelAllDialogsAsync por uma chamada de método simples.

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

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

@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.")

Exemplo de código

Nome de exemplo	Descrição	.NET	Node.js
Início rápido do SSO de conversa de bot	Configure rapidamente o bot do Teams com SSO para autenticação contínua do usuário para chats individuais e em grupo.	View	View

Observação

OnTeamsMessagingExtensionQueryAsync e OnTeamsAppBasedLinkQueryAsync do TeamsMessagingExtensionsSearchAuthConfigBot.cs arquivo são os únicos manipuladores de SSO com suporte. Não há suporte para outros manipuladores de SSO.

Esta seção cobre:

Atualizar variáveis de ambiente de desenvolvimento
Adicionar código para solicitar um token
Adicionar código para receber o token
Adicionar token ao Repositório de Tokens do Bot Framework
Lidar com logoff do usuário do aplicativo

Atualizar variáveis de ambiente de desenvolvimento

Você definiu o segredo do cliente e a configuração de conexão OAuth para o aplicativo no Microsoft Entra ID. Você deve configurar o código do aplicativo com essas variáveis.

Para atualizar as variáveis de ambiente de desenvolvimento:

Abra o projeto do aplicativo.
Abra o arquivo do ./env seu projeto.
Atualize as seguintes variáveis:
- Para MicrosoftAppId, atualize a ID de registro do Bot do Microsoft Entra ID.
- Para MicrosoftAppPassword, atualize o segredo do cliente de registro do bot.
- Para ConnectionName, atualize o nome da conexão OAuth configurada no Microsoft Entra ID.
- Para MicrosoftAppTenantId, atualize a ID do locatário.
Salve o arquivo.

Agora você configurou as variáveis de ambiente necessárias para seu aplicativo de bot e SSO. Em seguida, adicione o código para lidar com tokens.

Tive um problema

Adicionar código para solicitar um token

A solicitação para obter o token é uma solicitação de mensagem POST usando o esquema de mensagens existente. Ele está incluído nos anexos de um OAuthCard. O esquema da classe OAuthCard é definido no Microsoft Bot Schema 4.0. O Teams atualizará o token se a TokenExchangeResource propriedade for preenchida no card. Para o canal do Teams, somente a propriedade Id, que identifica exclusivamente uma solicitação de token, é respeitada.

Observação

O Microsoft Bot Framework OAuthPrompt ou o MultiProviderAuthDialog tem suporte para autenticação de SSO.

Para atualizar o código do seu aplicativo:

Adicionar trecho de código para TeamsSSOTokenExchangeMiddleware.
- C#
- JavaScript
Adicione o seguinte trecho de código a AdapterWithErrorHandler.cs (ou a classe equivalente no código do seu aplicativo):
```
base.Use(new TeamsSSOTokenExchangeMiddleware(storage, configuration["ConnectionName"]));
```
Adicione o seguinte trecho de código a index.js (ou a classe equivalente no código do seu aplicativo):
```
   const {TeamsSSOTokenExchangeMiddleware} = require('botbuilder');
   const tokenExchangeMiddleware = new TeamsSSOTokenExchangeMiddleware(memoryStorage, env.connectionName);
   adapter.use(tokenExchangeMiddleware);
```
Observação

Você poderá receber várias respostas para uma determinada solicitação se o usuário tiver vários pontos de extremidade ativos. Você deve eliminar todas as respostas duplicadas ou redundantes com o token. Para obter mais informações sobre signin/tokenExchange, consulte Classe TeamsSSOTokenExchangeMiddleware.

Use o trecho de código a seguir para solicitar um token.

C#
JavaScript

Depois de adicionar o AdapterWithErrorHandler.cs, o seguinte código deve aparecer:

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

Depois de adicionar o código a index.js, o seguinte código deve aparecer:

    // 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 express = require("express");

    // 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 express application.
    const expressApp = express();
    expressApp.use(express.json());

    const server = expressApp.listen(process.env.port || process.env.PORT || 3978, () => {
        console.log(`\n${ expressApp.name } listening to`, server.address());
        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.
    expressApp.post('/api/messages', async (req, res) => {
        // Route received a request to adapter for processing.
        await adapter.process(req, res, (context) => bot.run(context));
    });

Tive um problema

Se o usuário do aplicativo estiver usando seu aplicativo pela primeira vez, ele deverá consentir com a autenticação SSO.

Quando o usuário do aplicativo seleciona o nome de usuário, a permissão é concedida e ele pode usar o aplicativo.

Autenticação SSO concluída para o aplicativo de extensão de mensagem

Importante

Cenários onde as caixas de diálogo de consentimento não são necessárias:

Se o administrador tiver concedido consentimento em nome do locatário, os usuários do aplicativo não precisarão ser solicitados a dar consentimento. Isso significa que os usuários do aplicativo não veem as caixas de diálogo de consentimento e podem acessar o aplicativo sem problemas.

Se você encontrar algum erro, consulte Solucionar problemas de autenticação SSO no Teams.

Tive um problema

Adicionar código para receber o token

A resposta com o token é enviada por meio de uma atividade de invocação com o mesmo esquema que outras atividades de invocação que os bots recebem hoje. A única diferença é o nome da invocação, sign in/tokenExchange e o campo de valor . O campo valor contém a ID, uma cadeia de caracteres da solicitação inicial para obter o token e o campo token, um valor de cadeia de caracteres incluindo o token.

Use o seguinte exemplo de trecho de código para invocar a resposta:

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

Observação

Os trechos de código usam o bot de Caixa de Diálogo em Cascata. Para obter mais informações sobre a caixa de diálogo em cascata, consulte Sobre caixas de diálogo em cascata e de componentes.

Você recebe o token no OnTeamsMessagingExtensionQueryAsync manipulador no turnContext.Activity.Value conteúdo ou no , dependendo do cenário para o qual você está habilitando o OnTeamsAppBasedLinkQueryAsyncSSO.

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

Tive um problema

Validar o token de acesso

As APIs Web em seu servidor devem decodificar o token de acesso e verificar se ele é enviado do cliente.

Observação

Se você usar o Bot Framework, ele manipulará a validação do token de acesso. Se você não usar o Bot Framework, siga as diretrizes nesta seção.

Para obter mais informações sobre como validar o token de acesso, consulte Validar tokens.

Há diversas bibliotecas disponíveis que podem lidar com a validação de JWT. A validação básica inclui:

Verificando se o token está bem formado.
Verificando se o token foi emitido pela autoridade pretendida.
Verificar se o token está direcionado à API Web.

Ao validar o token, lembre-se das seguintes diretrizes:

Os tokens SSO válidos são emitidos pelo Microsoft Entra ID. A iss declaração no token deve começar com esse valor.
O parâmetro do aud1 token é definido como a ID do aplicativo gerada durante o registro do aplicativo Microsoft Entra.
O parâmetro do scp token é definido como access_as_user.

Token de acesso de exemplo

O trecho de código a seguir é uma carga decodificada típica de um token de acesso:

{
    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"
}

Adicionar token ao Repositório de Tokens do Bot Framework

Se estiver usando a conexão OAuth, você deverá atualizar ou adicionar o token no repositório de Tokens do Bot Framework. Adicione o seguinte exemplo de trecho de código ( TeamsMessagingExtensionsSearchAuthConfigBot.cs ou o arquivo equivalente no código do seu aplicativo) para atualizar ou adicionar o token no repositório:

Observação

Você pode encontrar o exemplo TeamsMessagingExtensionsSearchAuthConfigBot.cs em SSO de Guia, Bot e Extensão de Mensagem (ME).

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

Tive um problema

Lidar com logoff do usuário do aplicativo

Use o trecho de código a seguir para lidar com o token de acesso caso o usuário do aplicativo faça logoff:

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

Tive um problema

Exemplo de código

Esta seção fornece um exemplo de SDK de autenticação de bot v3.

Nome de exemplo	Descrição	.NET	Node.js	Python	Manifesto
Autenticação de bot	Este aplicativo de exemplo demonstra como um bot pode usar a autenticação do Teams.	View	View	View	NA
SSO de guia, bot e Extensão de mensagem (ME)	Este aplicativo de exemplo demonstra a integração do SSO do Teams para Guia, Bot e Extensão de Mensagens, usando C# e o Microsoft Entra ID para autenticação segura.	View	View	NA	View
Guia, bot e extensão de mensagem	Este exemplo mostra a autenticação do Microsoft Entra ID e do Facebook em bots, guias e extensões de mensagens no Microsoft Teams.	View	View	NA	View

Próxima etapa

Atualizar manifesto para SSO e aplicativo de visualização

Comentários

Esta página foi útil?

Last updated on 2026-08-24

Adicionar código para habilitar o SSO em seu aplicativo bot

Atualizar variáveis de ambiente de desenvolvimento

Inicializar o aplicativo com OAuth

Caixa de diálogo de consentimento para obter o token de acesso

Chats entre duas pessoas

Chats em grupo

O consentimento do Microsoft Entra ID é necessário

O consentimento do Microsoft Entra ID não é necessário

Lidar com a entrada e o recebimento de token

Lidar com falhas de entrada

Lidar com a saída do usuário do aplicativo

Exemplo de código

Atualizar variáveis de ambiente de desenvolvimento

Adicionar código para solicitar um token

Caixa de diálogo de consentimento para obter o token de acesso

Adicionar código para receber o token

Validar o token de acesso

Token de acesso de exemplo

Adicionar token ao Repositório de Tokens do Bot Framework

Lidar com logoff do usuário do aplicativo

Exemplo de código

Próxima etapa

Comentários

Recursos adicionais