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.

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:

  1. Atualizar variáveis de ambiente de desenvolvimento
  2. Inicializar o aplicativo com OAuth
  3. Lidar com a entrada e o recebimento de token
  4. Lidar com falhas de entrada
  5. 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:

  1. Abra o projeto do aplicativo bot.

  2. Abra o arquivo de ambiente (.env) do seu projeto.

  3. 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.

  4. 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;
using Microsoft.Teams.Apps.OAuth;

var builder = WebApplication.CreateBuilder(args);

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

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

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

OAuthFlow auth = teams.GetOAuthFlow(connectionName);

Observação

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

Lidar com a entrada e o recebimento de token

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) =>
{
  string? token = await auth.SignInAsync(context, cancellationToken);
  if (token is null)
    {
        return;
    }

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

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

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.

Lidar com falhas de entrada

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:

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

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) =>
{
  await auth.SignOutAsync(context, cancellationToken);
  await context.SendAsync("You have been signed out.", cancellationToken);
});

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:

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.

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.

    A imagem mostra o pop-up de permissões solicitadas na área de trabalho

    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.

    A imagem mostra a interação do bot quando o consentimento do usuário é negado ou a solicitação atinge o tempo limite

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.

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

Próxima etapa