Adicionar o logon único ao aplicativo do Teams

Artigo
08/11/2023

O Microsoft Teams fornece uma função SSO (logon único) para um aplicativo obter o token de usuário do Teams conectado para acessar o Microsoft Graph e outras APIs. O Teams Toolkit facilita a interação abstraindo alguns dos fluxos e integrações Microsoft Azure Active Directory (Azure AD) por trás de APIs simples. Isso permite que você adicione recursos de SSO facilmente ao seu aplicativo teams.

Adicionar o SSO ao aplicativo Teams para Microsoft Visual Studio Code

Para aplicativos que interagem com o usuário em um chat, Equipe ou canal, o SSO se manifesta como um Cartão Adaptável, com o qual o usuário pode interagir para invocar o fluxo de consentimento Azure AD.

Habilitar o suporte ao SSO

O Teams Toolkit ajuda você a adicionar o SSO aos seguintes recursos do Teams no Visual Studio Code:

Tab
Bot
Bot de notificação: restificar servidor
Bot de comando
Bot de fluxo de trabalho
Extensão de mensagem

Adicionar SSO usando Visual Studio Code

Você pode executar as seguintes etapas para adicionar o SSO usando o Teams Toolkit no Visual Studio Code:

Abra o Visual Studio Code.
Selecione Kit de Ferramentas do Teams na barra de atividades Visual Studio Code.
Selecione Exibir Guias de Instruções na seção DESENVOLVIMENTO .
Na lista suspensa, selecione Desenvolver Experiência de Sign-On Único no Teams. Você será redirecionado para o respectivo guia De instruções.

Desenvolvimento Guia de instruções

Desenvolver experiência de logon único no Teams Como desenvolver a experiência de logon único

Desenvolvimento	Guia de instruções
Desenvolver experiência de logon único no Teams	Como desenvolver a experiência de logon único

Observação

Quando o SSO está habilitado, o Teams Toolkit, por padrão, provisiona um aplicativo de Azure AD de locatário único, o que significa que apenas contas de usuário e convidado no mesmo diretório que sua conta M365 podem entrar no aplicativo do Teams. Para obter mais informações sobre como dar suporte a vários locatários para atualizar seu projeto do TeamsFx, consulte Suporte de vários locatários para Azure AD aplicativo.

Confira também

Importante

Introduzimos a extensão do Teams Toolkit v5 em Visual Studio Code. Essa versão chega a você com muitos novos recursos de desenvolvimento de aplicativos. Recomendamos que você use o Teams Toolkit v5 para criar seu aplicativo teams.

Em breve, a extensão do Teams Toolkit v4 será preterida.

O Microsoft Teams fornece uma função SSO (logon único) para um aplicativo obter o token de usuário do Teams conectado para acessar o Microsoft Graph e outras APIs. O Teams Toolkit facilita a interação abstraindo alguns dos fluxos e integrações de Microsoft Azure Active Directory (Azure AD) por trás de algumas APIs simples. Isso permite que você adicione recursos de SSO facilmente ao seu aplicativo teams.

Adicionar o SSO ao aplicativo Teams para Microsoft Visual Studio Code

Habilitar o suporte ao SSO

O Teams Toolkit ajuda você a adicionar o SSO aos seguintes recursos do Teams no Visual Studio Code:

Tab
Bot
Bot de notificação: restificar servidor
Bot de comando
Bot de fluxo de trabalho
Extensão de mensagem

Adicionar SSO usando Visual Studio Code

Você pode executar as seguintes etapas para adicionar o SSO usando o Teams Toolkit no Visual Studio Code:

Abra o Visual Studio Code.
Selecione Kit de Ferramentas do Teams na barra de atividades Visual Studio Code.
Selecione Adicionar recursos em DESENVOLVIMENTO.
- Você pode selecionar Exibir>Paleta de Comandos... para exibir a janela Adicionar recursos .
Selecione Logon Único.

Adicionar SSO usando a CLI do TeamsFx

Você pode executar teamsfx add sso o comando no diretório raiz do projeto.

Observação

O recurso habilita o SSO para todos os recursos aplicáveis existentes. Siga as mesmas etapas para habilitar o SSO se você adicionar recursos posteriormente ao projeto.

Personalizar seu projeto usando o Teams Toolkit

A tabela a seguir lista as alterações que o Teams Toolkit faz ao seu projeto:

Tipo	Arquivo	Objetivo
Criar	`aad.template.json` Sob `template\appPackage`	Azure AD manifesto do aplicativo representa seu aplicativo Azure AD. `template\appPackage`ajuda a registrar um aplicativo Azure AD durante o estágio de depuração ou provisionamento local.
Modificar	`manifest.template.json` Sob `template\appPackage`	Um `webApplicationInfo` objeto é adicionado ao seu manifesto de aplicativo (anteriormente chamado de manifesto de aplicativo do Teams). O Teams requer esse campo para habilitar o SSO. A alteração está em vigor quando você dispara a depuração ou provisionamento local.
Criar	`auth\tab`	Código de referência, páginas de redirecionamento de auth e `README.md` arquivos são gerados neste caminho para um projeto de guia.
Criar	`auth\bot`	Código de referência, páginas de redirecionamento de auth e `README.md` arquivos são gerados neste caminho para um projeto de bot.

Observação

Ao adicionar o SSO, o Teams Toolkit não altera nada na nuvem até que você acione a depuração local. Atualize seu código para garantir que o SSO esteja funcionando no projeto.

Atualizar seu aplicativo para usar o SSO

Para habilitar o SSO em seu aplicativo, siga estas etapas:

Observação

Essas alterações são baseadas nos modelos que você scaffold.

Projeto Tab

Copiar auth-start.html e auth-end.htm na auth\public pasta para tabs\public\. O Teams Toolkit registra esses dois pontos de extremidade em Azure AD para o fluxo de redirecionamento do Azure AD.
Copiar sso pasta em auth\tab .tabs\src\sso\
- InitTeamsFx: o arquivo implementa uma função que inicializa o SDK do TeamsFx e abre GetUserProfile o componente após a inicialização do SDK.
- GetUserProfile: o arquivo implementa uma função que chama a Microsoft API do Graph para obter informações do usuário.
Execute npm install @microsoft/teamsfx-react em tabs\.
Adicione as seguintes linhas para tabs\src\components\sample\Welcome.tsx importar InitTeamsFx:
```
import { InitTeamsFx } from "../../sso/InitTeamsFx";
```
Substitua a seguinte linha:

<AddSSO /> com <InitTeamsFx /> para substituir o AddSso componente por InitTeamsFx componente.

Projeto bot

Configurar os redirecionamentos Azure AD

Mova a auth\bot\public pasta para bot\src. Esta pasta contém páginas HTML que o aplicativo bot hospeda. Quando o fluxo SSO é iniciado com Azure AD, ele redireciona você para as páginas HTML.

Modifique o para bot\src\index adicionar as rotas apropriadas restify às páginas HTML.

const path = require("path");

server.get(
  "/auth-*.html",
  restify.plugins.serveStatic({
    directory: path.join(__dirname, "public"),
  })
);

Atualize seu aplicativo

O manipulador ProfileSsoCommandHandler de comandoSO usa um token Azure AD para chamar o Microsoft Graph. Esse token é obtido usando o token de usuário conectado no Teams. O fluxo é reunido em uma caixa de diálogo que exibe uma caixa de diálogo de consentimento, se necessário.

Mover profileSsoCommandHandler o arquivo em auth\bot\sso pasta para bot\src. ProfileSsoCommandHandler Class é um manipulador de comandoSO para obter informações do usuário com token SSO, seguir esse método e criar seu próprio manipulador de comandoSO.
Abra package.json o arquivo e verifique se o TeamsFx SDK versão >= 1.2.0.
Execute o npm install isomorphic-fetch --save comando na bot pasta.
Para script ts, execute o npm install copyfiles --save-dev comando na pasta e substitua as bot seguintes linhas em package.json:
```
"build": "tsc --build && shx cp -r ./src/adaptiveCards ./lib/src",
```
com
```
"build": "tsc --build && shx cp -r ./src/adaptiveCards ./lib/src && copyfiles src/public/*.html lib/",
```
Isso copia as páginas HTML usadas para redirecionamento de auth ao criar o projeto do bot.

Para fazer o fluxo de consentimento do SSO funcionar, substitua o seguinte código no bot\src\index arquivo:

server.post("/api/messages", async (req, res) => {
  await commandBot.requestHandler(req, res);
});

com

server.post("/api/messages", async (req, res) => {
  await commandBot.requestHandler(req, res).catch((err) => {
    // Error message including "412" means it is waiting for user's consent, which is a normal process of SSO, shouldn't throw this error.
    if (!err.message.includes("412")) {
      throw err;
    }
  });
});

Substitua as seguintes opções por ConversationBot instância bot\src\internal\initialize para adicionar o manipulador de comandos SSO e SSO:

export const commandBot = new ConversationBot({
    ...
    command: {
        enabled: true,
        commands: [new HelloWorldCommandHandler()],
    },
});

com

import { ProfileSsoCommandHandler } from "../profileSsoCommandHandler";

export const commandBot = new ConversationBot({
    ...
    // To learn more about ssoConfig, please refer teamsfx sdk document: https://docs.microsoft.com/microsoftteams/platform/toolkit/teamsfx-sdk
    ssoConfig: {
        aad :{
            scopes:["User.Read"],
        },
    },
    command: {
        enabled: true,
        commands: [new HelloWorldCommandHandler() ],
        ssoCommands: [new ProfileSsoCommandHandler()],
    },
});

Registre seu comando no manifesto do aplicativo Teams. Abra templates\appPackage\manifest.template.jsone adicione as seguintes linhas commands no commandLists bot:
```
{
  "title": "profile",
  "description": "Show user profile using Single Sign On feature"
}
```

Adicionar um novo comando SSO ao bot (Opcional)

Depois de adicionar o SSO com êxito em seu projeto, você pode adicionar um novo comando SSO:

Crie um novo arquivo como photoSsoCommandHandler.ts ou photoSsoCommandHandler.js in bot\src\ e adicione seu próprio manipulador de comandos SSO para chamar API do Graph:

// for TypeScript:
import { Activity, TurnContext, ActivityTypes } from "botbuilder";
import "isomorphic-fetch";
import {
    CommandMessage,
    TriggerPatterns,
    TeamsFx,
    createMicrosoftGraphClient,
    TeamsFxBotSsoCommandHandler,
    TeamsBotSsoPromptTokenResponse,
} from "@microsoft/teamsfx";

export class PhotoSsoCommandHandler implements TeamsFxBotSsoCommandHandler {
    triggerPatterns: TriggerPatterns = "photo";

    async handleCommandReceived(
        context: TurnContext,
        message: CommandMessage,
        tokenResponse: TeamsBotSsoPromptTokenResponse,
    ): Promise<string | Partial<Activity> | void> {
        await context.sendActivity("Retrieving user information from Microsoft Graph ...");

        const teamsfx = new TeamsFx().setSsoToken(tokenResponse.ssoToken);

        const graphClient = createMicrosoftGraphClient(teamsfx, ["User.Read"]);

        let photoUrl = "";
        try {
            const photo = await graphClient.api("/me/photo/$value").get();
            const arrayBuffer = await photo.arrayBuffer();
            const buffer=Buffer.from(arrayBuffer, 'binary');
            photoUrl = "data:image/png;base64," + buffer.toString("base64");
        } catch {
            // Could not fetch photo from user's profile, return empty string as placeholder.
        }
        if (photoUrl) {
            const photoMessage: Partial<Activity> = {
                type: ActivityTypes.Message,
                text: 'This is your photo:',
                attachments: [
                    {
                        name: 'photo.png',
                        contentType: 'image/png',
                        contentUrl: photoUrl
                    }
                ]
            };
            return photoMessage;
        } else {
            return "Could not retrieve your photo from Microsoft Graph. Please make sure you have uploaded your photo.";
        }
    }
}

// for JavaScript:
const { ActivityTypes } = require("botbuilder");
require("isomorphic-fetch");
const {
  createMicrosoftGraphClient,
  TeamsFx,
} = require("@microsoft/teamsfx");

class PhotoSsoCommandHandler {
  triggerPatterns = "photo";

  async handleCommandReceived(context, message, tokenResponse) {
    await context.sendActivity(
      "Retrieving user information from Microsoft Graph ..."
    );

    const teamsfx = new TeamsFx().setSsoToken(tokenResponse.ssoToken);

    const graphClient = createMicrosoftGraphClient(teamsfx, ["User.Read"]);

    let photoUrl = "";
    try {
      const photo = await graphClient.api("/me/photo/$value").get();
      const arrayBuffer = await photo.arrayBuffer();
      const buffer = Buffer.from(arrayBuffer, "binary");
      photoUrl = "data:image/png;base64," + buffer.toString("base64");
    } catch {
      // Could not fetch photo from user's profile, return empty string as placeholder.
    }
    if (photoUrl) {
      const photoMessage = {
        type: ActivityTypes.Message,
        text: "This is your photo:",
        attachments: [
          {
            name: "photo.png",
            contentType: "image/png",
            contentUrl: photoUrl,
          },
        ],
      };
      return photoMessage;
    } else {
      return "Could not retrieve your photo from Microsoft Graph. Please make sure you have uploaded your photo.";
    }
  }
}

module.exports = {
  PhotoSsoCommandHandler,
};

Adicionar PhotoSsoCommandHandler instância à ssoCommands matriz em bot\src\internal\initialize.ts:

// for TypeScript:
import { PhotoSsoCommandHandler } from "../photoSsoCommandHandler";

export const commandBot = new ConversationBot({
    ...
    command: {
        ...
        ssoCommands: [new ProfileSsoCommandHandler(), new PhotoSsoCommandHandler()],
    },
});

// for JavaScript:
...
const { PhotoSsoCommandHandler } = require("../photoSsoCommandHandler");

const commandBot = new ConversationBot({
    ...
    command: {
        ...
        ssoCommands: [new ProfileSsoCommandHandler(), new PhotoSsoCommandHandler()]
    },
});
...

Registre seu comando no manifesto do aplicativo. Abra templates\appPackage\manifest.template.jsone adicione as seguintes linhas commands no commandLists bot:
```
{
    "title": "photo",
    "description": "Show user photo using Single Sign On feature"
}
```

Projeto de extensão de mensagem

A lógica de negócios de exemplo fornece um manipulador TeamsBot que estende TeamsActivityHandler e substitui handleTeamsMessagingExtensionQuery.

Você pode atualizar a lógica de handleMessageExtensionQueryWithToken consulta no token com, que é obtido usando o token de usuário conectado no Teams.

Para fazer isso funcionar em seu aplicativo:

Mova a auth\bot\public pasta para bot. Esta pasta contém páginas HTML que o aplicativo bot hospeda. Quando os fluxos de SSO são iniciados com Azure AD, Azure AD redireciona você para essas páginas.

Modifique o seu bot\index para adicionar as rotas apropriadas restify a essas páginas.

const path = require("path");

server.get(
    "/auth-*.html",
    restify.plugins.serveStatic({
        directory: path.join(__dirname, "public"),
    })
);

handleTeamsMessagingExtensionQuery Substituir a interface em bot\teamsBot. Você pode seguir o código de exemplo no handleMessageExtensionQueryWithToken para fazer sua própria lógica de consulta.
Abra bot\package.json, verifique se a @microsoft/teamsfx versão >= 1.2.0
Instale isomorphic-fetch pacotes npm em seu projeto de bot.
Para ts, instale copyfiles pacotes npm no projeto do bot, adicione ou atualize o script da buildbot\package.json seguinte maneira:
```
"build": "tsc --build && copyfiles ./public/*.html lib/",
```
Conforme você faz isso, as páginas HTML usadas para redirecionamento de auth são copiadas quando você cria esse projeto de bot.

Atualize templates\appPackage\aad.template.json seus escopos, que são usados em handleMessageExtensionQueryWithToken.

"requiredResourceAccess": [
    {
        "resourceAppId": "Microsoft Graph",
        "resourceAccess": [
            {
                "id": "User.Read",
                "type": "Scope"
            }
        ]
    }
]

Depurar seu aplicativo

Pressione F5 para depurar seu aplicativo. O Teams Toolkit usa o arquivo de manifesto do aplicativo Azure AD para registrar um aplicativo Azure AD para SSO. Para funcionalidades de depuração local do Teams Toolkit, confira como depurar seu aplicativo localmente.

Personalizar Azure AD registro de aplicativo

O manifesto do aplicativo Azure AD permite personalizar vários aspectos do registro do aplicativo. Você pode atualizar o manifesto do aplicativo conforme necessário. Se você precisar incluir mais permissões de API para acessar as APIs desejadas, consulte permissões de API para acessar as APIs desejadas. Para exibir seu aplicativo Azure AD no portal do Azure, consulte exibir Azure AD aplicativo no portal do Azure.

Conceitos de autenticação SSO

Os seguintes conceitos ajudam você com a autenticação SSO:

Trabalho do SSO no Teams

A autenticação SSO no Azure AD atualiza silenciosamente o token de autenticação para minimizar o número de vezes que os usuários precisam inserir suas credenciais de entrada. Se os usuários concordarem em usar seu aplicativo, eles não precisarão fornecer consentimento novamente em outro dispositivo, pois eles são conectados automaticamente.

As guias e bots do Teams têm fluxo semelhante para suporte ao SSO. Para saber mais, veja:

SSO simplificado com o TeamsFx

O TeamsFx ajuda a reduzir as tarefas do desenvolvedor usando o SSO e acessando recursos de nuvem até instruções de linha única sem configuração.

Com o SDK do TeamsFx, você pode escrever o código de autenticação do usuário de forma simplificada usando as seguintes credenciais:

Identidade do usuário no ambiente do navegador: TeamsUserCredential representa a identidade do usuário atual do Teams.
Identidade do usuário no ambiente Node.js: OnBehalfOfUserCredential usa fluxo em nome e token SSO.
Identidade do aplicativo no ambiente Node.js: AppCredential representa a identidade do aplicativo.

Para obter mais informações sobre o SDK do TeamsFx, confira:

Referência de SDK ou API do TeamsFx
Galeria de Exemplos do TeamsFx (Microsoft Teams Framework)

Adicionar o logon único ao aplicativo do Teams

Adicionar o SSO ao aplicativo Teams para Microsoft Visual Studio Code

Habilitar o suporte ao SSO

Adicionar SSO usando Visual Studio Code

Confira também

Adicionar o SSO ao aplicativo Teams para Microsoft Visual Studio Code

Habilitar o suporte ao SSO

Adicionar SSO usando Visual Studio Code

Adicionar SSO usando a CLI do TeamsFx

Personalizar seu projeto usando o Teams Toolkit

Atualizar seu aplicativo para usar o SSO

Configurar os redirecionamentos Azure AD

Atualize seu aplicativo

Adicionar um novo comando SSO ao bot (Opcional)

Depurar seu aplicativo

Personalizar Azure AD registro de aplicativo

Conceitos de autenticação SSO

Trabalho do SSO no Teams

SSO simplificado com o TeamsFx

Confira também

Recursos adicionais

Recursos adicionais