Adicionar código para ativar o SSO na sua aplicação de bot

Antes de adicionar código para ativar o início de sessão único (SSO), certifique-se de que configura a aplicação e o recurso de bot no centro de administração do Microsoft Entra.

Configurar a aplicação de bot no Microsoft Entra ID

Tem de configurar o código da sua aplicação para obter um token de acesso a partir de Microsoft Entra ID. O token de acesso é emitido em nome da aplicação de bot.

Observação

Se criou a sua aplicação teams com o Microsoft Teams Toolkit, pode ativar o SSO para a sua aplicação com as instruções no módulo Ferramentas e SDKs. Para obter mais informações, consulte Adicionar início de sessão único à aplicação Teams. O Teams Toolkit suporta o SSO para aplicações JavaScript, TypeScript e C# no Visual Studio Code.

Esta seção cobre:

1. Atualizar variáveis de ambiente de desenvolvimento
2. Adicionar código para processar um token de acesso
3. Adicionar código para receber o token
4. Processar o início de sessão do utilizador da aplicação

Atualizar variáveis de ambiente de desenvolvimento

Configurou o segredo do cliente e a definição de ligação OAuth para a aplicação no Microsoft Entra ID. Tem de configurar o código com estes valores.

Para atualizar as variáveis de ambiente de desenvolvimento:

1. Abra o projeto da aplicação de bot.

2. Abra o ficheiro de ambiente do projeto.

3. Atualize as seguintes variáveis:

   • Para MicrosoftAppId, atualize o ID do bot a partir de Microsoft Entra ID.
   • Para MicrosoftAppPassword, atualize o segredo do cliente.
   • Para ConnectionName, atualize o nome da ligação OAuth que configurou no Microsoft Entra ID.
   • Para MicrosoftAppTenantId, atualize o ID do inquilino.

   Observação

   Pode personalizar o URL de redirecionamento do OAuth para o seu bot e fornecedor de identidade com base nos seus requisitos de residência dos dados, independentemente de o bot estar na cloud pública, no Microsoft Azure Governamental cloud ou no Microsoft Azure operado pela 21Vianet. Para obter os URLs de OAuth e a lista de residência dos dados, veja OAuth URL support in Azure AI Serviço de Bot (Suporte de URLs de OAuth no Serviço de Bot de IA do Azure).

4. Salve o arquivo.

Configurou agora as variáveis de ambiente necessárias para a aplicação bot e o SSO. Em seguida, adicione o código para processar tokens de bot.

Detetei um problema

Adicionar código para processar um token de acesso

O pedido para obter o token é um pedido de mensagem POST com o esquema de mensagem existente. Ele está incluído nos anexos de um OAuthCard. O esquema da classe OAuthCard é definido no Microsoft Bot Schema 4.0. O Teams atualiza o token se a TokenExchangeResource propriedade estiver 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 da sua aplicação:

1. Adicionar fragmento de código para TeamsSSOTokenExchangeMiddleware.

   C#

   Adicione o seguinte fragmento de código a (ou à AdapterWithErrorHandler.cs classe equivalente no código da sua aplicação):

   base.Use(new TeamsSSOTokenExchangeMiddleware(storage, configuration["ConnectionName"]));
   

   JavaScript

   Adicione o seguinte fragmento de código a (ou à index.js classe equivalente no código da sua aplicação):

   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. Tem de eliminar todas as respostas duplicadas ou redundantes com o token. Para obter mais informações sobre o início de sessão/tokenExchange, veja TeamsSSOTokenExchangeMiddleware Class (Classe TeamsSSOTokenExchangeMiddleware).

2. Utilize o seguinte fragmento de código para pedir um token.

   C#

   Depois de adicionar o AdapterWithErrorHandler.cs, tem de ser apresentado o seguinte código:

       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 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 is displayed in the Bot Framework Emulator.
                   await turnContext.TraceActivityAsync(
                       "OnTurnError Trace",
                       exception.Message,
                       "https://www.botframework.com/schemas/error",
                       "TurnError");
               };
           }
       }
   

   JavaScript

   Depois de adicionar o fragmento de código para TeamsSSOTokenExchangeMiddleware, tem de ser apresentado o seguinte código:

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

Detetei um problema

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

O utilizador tem de consentir as permissões pedidas pela aplicação bot para obter o token de acesso. A caixa de diálogo de consentimento é apresentada com base no âmbito da aplicação.

Chats entre duas pessoas

Quando o utilizador da aplicação está a utilizar a aplicação pela primeira vez e é necessário o consentimento do utilizador, é apresentada a seguinte caixa de diálogo:

Quando o utilizador seleciona Continuar, ocorre um dos seguintes eventos:

• Se a IU do bot tiver um botão de início de sessão, o fluxo de início de sessão para bots é ativado. Pode determinar as permissões que requerem o consentimento do utilizador da aplicação. Utilize esta abordagem se a sua aplicação necessitar de permissões do Graph diferentes de openid.

• Se o bot não tiver um botão de início de sessão no card OAuth, é necessário o consentimento do utilizador da aplicação para um conjunto mínimo de permissões. Este token é útil para autenticação básica e para obter o endereço de e-mail do utilizador da aplicação.

A caixa de diálogo de consentimento apresentada destina-se a âmbitos open-id definidos no Microsoft Entra ID. O usuário do aplicativo deve dar consentimento apenas uma vez. Após o consentimento, o utilizador da aplicação pode aceder e utilizar a aplicação bot para obter as permissões e âmbitos concedidos.

Conversas de grupo

Eis os dois cenários de autenticação no âmbito do grupo:

• Microsoft Entra ID consentimento é necessário
• Microsoft Entra ID consentimento não é necessário

Microsoft Entra ID consentimento é necessário

Quando um bot é adicionado a uma conversa de grupo pela primeira vez e é necessário consentimento para um determinado utilizador, é apresentada uma caixa de diálogo de consentimento apenas ao utilizador que @mentions o bot tem. O utilizador tem de dar consentimento único às permissões pedidas pela aplicação de bot para obter o token de acesso.

Desktop

O utilizador @mentions , o bot. É apresentado um Cartão Ajustável para pedir o consentimento do utilizador.

• Se o utilizador selecionar Adicionar, é apresentada uma caixa de diálogo de permissões.

  

  O utilizador tem de selecionar Aceitar para dar consentimento.

• Se o utilizador recusar ou o pedido exceder o limite de tempo, o utilizador terá @mention de conceder novamente permissão para a aquisição de tokens. O grupo consegue ver uma mensagem de bot a indicar que a autenticação não foi bem-sucedida.

  

Dispositivo móvel

O utilizador @mentions , o bot. É apresentado um Cartão Ajustável para pedir o consentimento do utilizador.

• Se o utilizador selecionar Adicionar, é apresentada uma caixa de diálogo de permissões.

  

  O utilizador tem de selecionar Aceitar para dar consentimento.

• Se o utilizador recusar ou o pedido exceder o limite de tempo, o utilizador terá @mention de conceder novamente permissão para a aquisição de tokens. O grupo consegue ver uma mensagem de bot a indicar que a autenticação não foi bem--valia.

  

Microsoft Entra ID consentimento não é necessário

Se as permissões de utilizador forem concedidas por predefinição ou para aplicações fidedignas, o utilizador que @mentions o bot pode interagir diretamente com o bot sem ter de dar consentimento.

Observação

Após o consentimento do utilizador da aplicação, não é necessário dar novamente consentimento para quaisquer outras permissões. Se as permissões definidas no âmbito Microsoft Entra forem modificadas, o utilizador da aplicação poderá ter de consentir novamente. No entanto, se o pedido de consentimento não permitir que o utilizador da aplicação aceda, a aplicação bot volta a iniciar sessão card.

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 inquilino, não é necessário pedir consentimento aos utilizadores da aplicação. Isto significa que os utilizadores da aplicação não veem as caixas de diálogo de consentimento e podem aceder à aplicação de forma totalmente integrada.
• Se a sua aplicação Microsoft Entra estiver registada no mesmo inquilino a partir do qual está a pedir uma autenticação no Teams, não é possível pedir consentimento ao utilizador da aplicação e é-lhe concedido um token de acesso imediatamente. Os utilizadores da aplicação só consentem estas permissões se a aplicação Microsoft Entra estiver registada num inquilino diferente.

Se encontrar erros, veja Resolver problemas de autenticação de SSO no Teams.

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, o início de sessão/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.

Utilize o seguinte fragmento de código para invocar a resposta:

C#

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

JavaScript

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 fragmentos de código utilizam a Caixa de Diálogo de Cascata. Para obter mais informações, veja Acerca das caixas de diálogo sobre componentes e cascata.

Detetei um problema

Validar o token de acesso

As APIs Web no servidor têm de descodificar o token de acesso e verificar se foram enviadas do cliente.

Observação

Se utilizar o Bot Framework, este processa a validação do token de acesso. Se não utilizar o Bot Framework, siga as diretrizes indicadas nesta secção.

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

Existem muitas bibliotecas disponíveis que podem processar a validação JWT. A validação básica inclui:

• Verificar se o token está bem formado.

• Verificar se o token foi emitido pela autoridade pretendida.

• Verificar se o token está direcionado para a API Web. Ao validar o token, lembre-se das seguintes diretrizes:

• Os tokens de SSO válidos são emitidos por Microsoft Entra ID. A iss afirmação no token tem de começar com este valor.

• O parâmetro do token está definido como o ID da aplicação gerado durante Microsoft Entra registo da aud1 aplicação.

• O parâmetro do scp token está definido como access_as_user.

Token de acesso de exemplo

O fragmento de código seguinte é um payload normal descodificado 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"
}

Processar o início de sessão do utilizador da aplicação

Utilize o seguinte fragmento de código para processar o token de acesso, caso o utilizador da aplicação saia:

C#

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

JavaScript

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

Detetei um problema

Exemplo de código

Nome de exemplo	Descrição	C#	Node.js
Início rápido do SSO de conversação do bot	Configure rapidamente o bot do Teams com SSO para autenticação de utilizador totalmente integrada para conversas um-a-um e de grupo.	View	View

Observação

OnTeamsMessagingExtensionQueryAsync e OnTeamsAppBasedLinkQueryAsync do TeamsMessagingExtensionsSearchAuthConfigBot.cs ficheiro são os únicos processadores de SSO suportados. Outros processadores de SSO não são suportados.

Esta seção cobre:

1. Atualizar variáveis de ambiente de desenvolvimento
2. Adicionar código para pedir um token
3. Adicionar código para receber o token
4. Adicionar token ao Arquivo de Tokens do Bot Framework
5. Processar o início de sessão do utilizador da aplicação

Atualizar variáveis de ambiente de desenvolvimento

Configurou o segredo do cliente e a definição de ligação OAuth para a aplicação no Microsoft Entra ID. Tem de configurar o código da aplicação com estas variáveis.

Para atualizar as variáveis de ambiente de desenvolvimento:

1. Abra o projeto da aplicação.

2. Abra o ./env ficheiro do projeto.

3. Atualize as seguintes variáveis:

   • Para MicrosoftAppId, atualize o ID de registo do Bot a partir de Microsoft Entra ID.
   • Para MicrosoftAppPassword, atualize o segredo do cliente de registo do Bot.
   • Para ConnectionName, atualize o nome da ligação OAuth que configurou no Microsoft Entra ID.
   • Para MicrosoftAppTenantId, atualize o ID do inquilino.

4. Salve o arquivo.

Configurou agora as variáveis de ambiente necessárias para a aplicação bot e o SSO. Em seguida, adicione o código para processar tokens.

Detetei um problema

Adicionar código para pedir um token

O pedido para obter o token é um pedido de mensagem POST com o esquema de mensagem existente. Ele está incluído nos anexos de um OAuthCard. O esquema da classe OAuthCard é definido no Microsoft Bot Schema 4.0. O Teams atualiza o token se a TokenExchangeResource propriedade estiver 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 da sua aplicação:

1. Adicionar fragmento de código para TeamsSSOTokenExchangeMiddleware.

   C#

   Adicione o seguinte fragmento de código a (ou à AdapterWithErrorHandler.cs classe equivalente no código da sua aplicação):

   base.Use(new TeamsSSOTokenExchangeMiddleware(storage, configuration["ConnectionName"]));
   

   JavaScript

   Adicione o seguinte fragmento de código a (ou à index.js classe equivalente no código da sua aplicação):

      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. Tem de eliminar todas as respostas duplicadas ou redundantes com o token. Para obter mais informações sobre o início de sessão/tokenExchange, veja TeamsSSOTokenExchangeMiddleware Class (Classe TeamsSSOTokenExchangeMiddleware).

2. Utilize o seguinte fragmento de código para pedir um token.

   C#

   Depois de adicionar o AdapterWithErrorHandler.cs, tem de ser apresentado o seguinte código:

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

   JavaScript

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

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

Detetei um problema

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

Se o utilizador da aplicação estiver a utilizar a sua aplicação pela primeira vez, terá de consentir a autenticação SSO.

Quando o utilizador da aplicação seleciona o nome de utilizador, a permissão é concedida e pode utilizar a aplicação.

A caixa de diálogo de consentimento apresentada destina-se a âmbitos open-id definidos no Microsoft Entra ID. O usuário do aplicativo deve dar consentimento apenas uma vez. Após o consentimento, o utilizador da aplicação pode aceder e utilizar a sua aplicação de extensão de mensagem para as permissões e âmbitos concedidos.

Importante

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

• Se o administrador tiver dado consentimento em nome do inquilino, não é necessário pedir consentimento aos utilizadores da aplicação. Isto significa que os utilizadores da aplicação não veem as caixas de diálogo de consentimento e podem aceder à aplicação de forma totalmente integrada.

Se encontrar erros, veja Resolver problemas de autenticação de SSO no Teams.

Detetei 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, o início de sessão/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.

Utilize o seguinte exemplo de fragmento de código para invocar a resposta:

C#

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

JavaScript

 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 fragmentos de código utilizam o bot de Caixa de Diálogo cascata. Para obter mais informações sobre a Caixa de Diálogo de Cascata, consulte Acerca do componente e das caixas de diálogo de cascata.

Recebe o token no OnTeamsMessagingExtensionQueryAsync processador no turnContext.Activity.Value payload ou no , consoante o cenário para o OnTeamsAppBasedLinkQueryAsyncqual está a ativar o SSO.

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

Detetei um problema

Validar o token de acesso

As APIs Web no servidor têm de descodificar o token de acesso e verificar se foram enviadas do cliente.

Observação

Se utilizar o Bot Framework, este processa a validação do token de acesso. Se não utilizar o Bot Framework, siga as diretrizes nesta secção.

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

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

• Verificar se o token está bem formado.
• Verificar se o token foi emitido pela autoridade pretendida.
• Verificar se o token está direcionado para a API Web.

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

• Os tokens de SSO válidos são emitidos por Microsoft Entra ID. A iss afirmação no token tem de começar com este valor.
• O parâmetro do token está definido como o ID da aplicação gerado durante Microsoft Entra registo da aud1 aplicação.
• O parâmetro do scp token está definido como access_as_user.

Token de acesso de exemplo

O fragmento de código seguinte é um payload normal descodificado 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 Arquivo de Tokens do Bot Framework

Se estiver a utilizar a ligação OAuth, tem de atualizar ou adicionar o token no arquivo de Tokens do Bot Framework. Adicione o seguinte exemplo de fragmento de código a TeamsMessagingExtensionsSearchAuthConfigBot.cs (ou ao ficheiro equivalente no código da aplicação) para atualizar ou adicionar o token no arquivo:

Observação

Pode encontrar o exemplo TeamsMessagingExtensionsSearchAuthConfigBot.cs no SSO de Tecla de Tabulação, Bot e Extensão de Mensagens (ME).

C#

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

JavaScript

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

Detetei um problema

Processar o início de sessão do utilizador da aplicação

Utilize o seguinte fragmento de código para processar o token de acesso, caso o utilizador da aplicação termine a sessão:

C#

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

JavaScript

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

Detetei um problema

Exemplo de código

Esta secção fornece o exemplo do SDK v3 de autenticação do bot.

Nome de exemplo	Descrição	.NET	Node.js	Python	Manifesto
Autenticação de bot	Esta aplicação de exemplo demonstra como um Bot pode utilizar a autenticação do Teams.	View	View	View	Exibir
SSO da Tecla de Tabulação, bot e Extensão de mensagem (ME)	Esta aplicação de exemplo demonstra a integração do SSO do Teams para a Extensão de Tabulação, Bot e Mensagens, com C# e Microsoft Entra ID para autenticação segura.	View	View	NA	View
Separador, bot e extensão mensagem	Este exemplo mostra Microsoft Entra ID e Facebook autenticação entre bots, separadores e extensões de mensagens no Microsoft Teams.	View	View	NA	Exibir

Próxima etapa

Atualizar manifesto para SSO e aplicativo de visualização