Ativar o início de sessão único para a aplicação Teams

O Microsoft Teams fornece uma função de início de sessão único (SSO) para uma aplicação obter o token de utilizador com sessão iniciada no Teams para aceder ao Microsoft Graph e a outras APIs. O Microsoft Teams Toolkit simplifica o processo ao incorporar determinados fluxos de trabalho Microsoft Entra e integrações em APIs simples e de alto nível. Como resultado, pode incorporar facilmente capacidades de SSO na sua aplicação Teams. Para obter mais informações, consulte Autenticar utilizadores no Microsoft Teams.

Configurações de chaves

Para ativar o SSO, configure a aplicação Teams da seguinte forma:

• Microsoft Entra manifesto da aplicação: certifique-se de que define URIs, incluindo o URI que identifica a aplicação de autenticação Microsoft Entra e o URI de redirecionamento que devolve o token.

• Manifesto da aplicação Teams: ligue a sua aplicação SSO à sua aplicação Teams ao incorporar a configuração correta.

• Configuração e ficheiros de infraestrutura do Teams Toolkit: certifique-se de que as configurações necessárias estão implementadas para ativar o SSO para a sua aplicação Teams.

• Informações da aplicação SSO nos ficheiros de configuração do Teams Toolkit: certifique-se de que a aplicação de autenticação se regista no serviço de back-end e o Teams Toolkit inicia-o durante a depuração ou pré-visualização da aplicação Teams.

Aplicação de separador

Criar Microsoft Entra manifesto da aplicação

1. Transfira o modelo de manifesto da aplicação Microsoft Entra.

2. Adicione o código do modelo de manifesto de aplicação transferido ao ./aad.manifest.json ficheiro. Isto permite-lhe personalizar diferentes aspetos do registo de aplicações e atualizar o manifesto conforme necessário. Para obter mais informações, consulte o manifesto do aplicativo.

Atualizar manifesto da aplicação Teams

./appPackages/manifest.json No ficheiro, adicione o seguinte código:

"webApplicationInfo": {
  "id": "${{AAD_APP_CLIENT_ID}}",
  "resource": "api://${{TAB_DOMAIN}}/${{AAD_APP_CLIENT_ID}}"
}

webApplicationInfofornece a sua Microsoft Entra ID da Aplicação e informações do Microsoft Graph para ajudar os utilizadores a iniciar sessão na sua aplicação.

Observação

Pode utilizar para referenciar {{ENV_NAME}} variáveis no env/.env.{TEAMSFX_ENV} ficheiro.

Atualizar ficheiros de configuração do Teams Toolkit

1. Localize os seus ficheiros de configuração do Teams Toolkit, tais como ./teamsapp.yml e ./teamsapp.local.yml. Atualize as configurações necessárias relacionadas com Microsoft Entra nestes ficheiros.

2. Adicione a ação aadApp/createprovision em e ./teamsapp.local.yml./teamsapp.yml para criar uma nova aplicação Microsoft Entra utilizada para SSO:

   - uses: aadApp/create
     with:
       name: "YOUR_AAD_APP_NAME"
       generateClientSecret: true
       signInAudience: "AzureADMyOrg"
     writeToEnvironmentFile:
         clientId: AAD_APP_CLIENT_ID
         clientSecret: SECRET_AAD_APP_CLIENT_SECRET
         objectId: AAD_APP_OBJECT_ID
         tenantId: AAD_APP_TENANT_ID
         authority: AAD_APP_OAUTH_AUTHORITY
   

   Observação

   Substitua o name valor pelo nome pretendido para a sua aplicação Teams.

   Para obter mais informações, consulte aadApp/create.

3. Adicione a ação aadApp/updateprovision em e ./teamsapp.local.yml./teamsapp.yml para atualizar a sua aplicação Microsoft Entra:

   - uses: aadApp/update
     with:
       manifestPath: "./aad.manifest.json"
       outputFilePath: "./build/aad.manifest.${{TEAMSFX_ENV}}.json"
   

   Observação

   • Atualize o manifestPath valor para o caminho relativo do modelo aad.manifest.jsonde manifesto da aplicação Microsoft Entra , se tiver alterado o caminho do ficheiro.
   • Numa configuração local, posicione o aad/update após a ação file/createOrUpdateEnvironmentFile . Isto é necessário porque aad/update utiliza o resultado de file/createOrUpdateEnvironmentFile.

   Para obter mais informações, veja aadApp/update

4. Para um projeto React, atualize cli/runNpmCommand em deploy.

5. Se estiver a criar uma aplicação de separador com a estrutura de React na CLI, localize a ação cli/runNpmCommand com build app no teamsapp.yml ficheiro e adicione as seguintes variáveis de ambiente:

   env:
     REACT_APP_CLIENT_ID: ${{AAD_APP_CLIENT_ID}}
     REACT_APP_START_LOGIN_PAGE_URL: ${{TAB_ENDPOINT}}/auth-start.html
   

6. Se estiver a criar uma aplicação de separador com React arquitetura, localize a ação file/createOrUpdateEnvironmentFile de implementação no teamsapp.local.yml ficheiro e adicione as seguintes variáveis de ambiente:

   envs:
     ...
     REACT_APP_CLIENT_ID: ${{AAD_APP_CLIENT_ID}}
     REACT_APP_START_LOGIN_PAGE_URL: ${{TAB_ENDPOINT}}/auth-start.html
   

Atualizar código fonte

Com as alterações acima implementadas, o seu ambiente está preparado. Agora pode atualizar o código para incorporar o SSO na sua aplicação Teams.

Vanilla JavaScript

Para uma aplicação de separador que não utiliza React, utilize o seguinte código como exemplo básico para obter o token de SSO:

function getSSOToken() {
  return new Promise((resolve, reject) => {
    microsoftTeams.authentication.getAuthToken()
      .then((token) => resolve(token))
      .catch((error) => reject("Error getting token: " + error));
  });
}

function getBasicUserInfo() {
  getSSOToken().then((ssoToken) => {
    const tokenObj = JSON.parse(window.atob(ssoToken.split(".")[1]));
    console.log(`username: ${tokenObj.name}`);
    console.log(`user email: ${tokenObj.preferred_username}`);
  });
}

Reagir

Para React projetos, certifique-se de que as seguintes variáveis de ambiente estão definidas no processo de implementação:

• Para um projeto JavaScript, veja o separador JavaScript sample (Exemplo javaScript de separador).

• Para um projeto TypeScript, veja o separador TypeScript sample (Exemplo TypeScript).

Para atualizar o código fonte, siga estes passos:

1. Mova os auth-start.html ficheiros e auth-end.html da auth/public pasta para a public/ pasta . Estes ficheiros HTML servem o objetivo de processar redirecionamentos de autenticação.

2. Mover sso a pasta para baixo auth/ para src/sso/.

   1. InitTeamsFx: este ficheiro executa uma função que inicializa o SDK do TeamsFx. Após a inicialização do SDK, abre o GetUserProfile componente.
   2. GetUserProfile: este ficheiro executa uma função para obter as informações do utilizador ao invocar o microsoft API do Graph.

3. Importe e adicione InitTeamsFxWelcome.*.

Para obter mais informações, veja Aplicação de separador ativada para SSO.

Aplicação de extensão bot/mensagem

Criar Microsoft Entra manifesto da aplicação

1. Transfira o modelo de manifesto da aplicação Microsoft Entra.

2. Adicione o código do modelo de manifesto de aplicação transferido ao ./aad.manifest.json ficheiro. Isto permite-lhe personalizar diferentes aspetos do registo de aplicações e atualizar o manifesto conforme necessário. Para obter mais informações, consulte o manifesto do aplicativo.

Atualizar manifesto da aplicação Teams

1. ./appPackages/manifest.json No ficheiro, adicione o seguinte código:

   "webApplicationInfo": {
     "id": "${{AAD_APP_CLIENT_ID}}",
     "resource": "api://${{TAB_DOMAIN}}/${{AAD_APP_CLIENT_ID}}"
   }
   

   webApplicationInfofornece a sua Microsoft Entra ID da Aplicação e informações do Microsoft Graph para ajudar os utilizadores a iniciar sessão na sua aplicação.

   Observação

   Pode utilizar para referenciar {{ENV_NAME}} variáveis no env/.env.{TEAMSFX_ENV} ficheiro.

2. Registe um ou mais comandos no commandLists.

   Inclui commandLists comandos que o bot pode sugerir aos utilizadores. Se estiver a utilizar o teamsFx modelo de bot, defina os seguintes valores:

   {
     "title": "profile",
     "description": "Show user profile using Single Sign On feature"
   }
   

3. O validDomains campo inclui os domínios dos sites que a aplicação carrega no cliente do Teams. Atualize o seguinte valor:

   "validDomains": [
   "${{BOT_DOMAIN}}"
   ]
   

Atualizar ficheiros de configuração do Teams Toolkit

1. Localize os seus ficheiros de configuração do Teams Toolkit, tais como ./teamsapp.yml e ./teamsapp.local.yml. Atualize as configurações necessárias relacionadas com Microsoft Entra nestes ficheiros.

2. Adicione o seguinte código aadApp/createprovision em e ./teamsapp.yml./teamsapp.local.yml para criar novas aplicações Microsoft Entra utilizadas para o SSO:

   - uses: aadApp/create
     with:
       name: "YOUR_AAD_APP_NAME"
       generateClientSecret: true
       signInAudience: "AzureADMyOrg"
     writeToEnvironmentFile:
         clientId: AAD_APP_CLIENT_ID
         clientSecret: SECRET_AAD_APP_CLIENT_SECRET
         objectId: AAD_APP_OBJECT_ID
         tenantId: AAD_APP_TENANT_ID
         authority: AAD_APP_OAUTH_AUTHORITY
         authorityHost: AAD_APP_OAUTH_AUTHORITY_HOST
   

   Observação

   Substitua o name valor pelo nome pretendido para a sua aplicação Microsoft Teams.

   Para obter mais informações, consulte aadApp/create.

3. Adicione o seguinte código aadApp/updateprovision em ./teamsapp.yml e ./teamsapp.local.yml para atualizar a sua aplicação Microsoft Entra:

   - uses: aadApp/update
     with:
       manifestPath: "./aad.manifest.json"
       outputFilePath: "./build/aad.manifest.${{TEAMSFX_ENV}}.json"
   

   Observação

   Atualize o manifestPath valor para o caminho relativo do modelo aad.manifest.jsonde manifesto da aplicação Microsoft Entra , se tiver alterado o caminho do ficheiro.

   Para obter mais informações, veja aadApp/update

4. Localize a ação createOrUpdateEnvironmentFile no teamsapp.local.yml ficheiro e adicione as seguintes variáveis de ambiente:

   envs:
     ...
     M365_CLIENT_ID: ${{AAD_APP_CLIENT_ID}}
     M365_CLIENT_SECRET: ${{SECRET_AAD_APP_CLIENT_SECRET}}
     M365_TENANT_ID: ${{AAD_APP_TENANT_ID}}
     INITIATE_LOGIN_ENDPOINT: ${{BOT_ENDPOINT}}/auth-start.html
     M365_AUTHORITY_HOST: ${{AAD_APP_OAUTH_AUTHORITY_HOST}}
     M365_APPLICATION_ID_URI: api://botid-${{BOT_ID}}
   

Atualizar Infraestrutura

Atualize as configurações relacionadas com Microsoft Entra no seu serviço remoto. O exemplo seguinte mostra as definições de configuração numa Aplicação Web do Azure:

• M365_CLIENT_ID: Microsoft Entra ID de cliente da aplicação
• M365_CLIENT_SECRET: segredo do cliente da aplicação Microsoft Entra
• M365_TENANT_ID: ID de inquilino da aplicação Microsoft Entra
• INITIATE_LOGIN_ENDPOINT: página inicial de início de sessão para autenticação
• M365_AUTHORITY_HOST: Microsoft Entra anfitrião da autoridade OAuth da aplicação
• M365_APPLICATION_ID_URI: URI do identificador para Microsoft Entra aplicação

Para utilizar o teamsFx modelo de separador ou bot, siga estes passos:

1. Abra o infra/azure.parameters.json ficheiro e adicione o seguinte código:

   "m365ClientId": {
     "value": "${{AAD_APP_CLIENT_ID}}"
   },
   "m365ClientSecret": {
     "value": "${{SECRET_AAD_APP_CLIENT_SECRET}}"
   },
   "m365TenantId": {
     "value": "${{AAD_APP_TENANT_ID}}"
   },
   "m365OauthAuthorityHost": {
     "value": "${{AAD_APP_OAUTH_AUTHORITY_HOST}}"
   }
   

2. Abra infra/azure.bicep o ficheiro e adicione o seguinte código após param location string = resourceGroup().location:

   param m365ClientId string
   param m365TenantId string
   param m365OauthAuthorityHost string
   param m365ApplicationIdUri string = 'api://botid-${botAadAppClientId}'
   @secure()
   param m365ClientSecret string
   

3. Adicione o seguinte código antes output no infra/azure.bicep ficheiro:

   resource webAppSettings 'Microsoft.Web/sites/config@2021-02-01' = {
     name: '${webAppName}/appsettings'
     properties: {
       M365_CLIENT_ID: m365ClientId
       M365_CLIENT_SECRET: m365ClientSecret
       INITIATE_LOGIN_ENDPOINT: uri('https://${webApp.properties.defaultHostName}', 'auth-start.html')
       M365_AUTHORITY_HOST: m365OauthAuthorityHost
       M365_TENANT_ID: m365TenantId
       M365_APPLICATION_ID_URI: m365ApplicationIdUri
       BOT_ID: botAadAppClientId
       BOT_PASSWORD: botAadAppClientSecret
       RUNNING_ON_AZURE: '1'
     }
   }
   

   Observação

   • Para adicionar configurações adicionais à sua Aplicação Web do Azure, adicione as configurações no webAppSettings.
   • Também poderá ter de definir a versão predefinida do nó ao adicionar a seguinte configuração: bash WEBSITE_NODE_DEFAULT_VERSION: '14.20.0'

   Atualizar Código Fonte

   Bot

   1. Mova os ficheiros localizados na auth/sso pasta para src. A ProfileSsoCommandHandler classe funciona como um processador de comandos SSO, concebido para obter informações de utilizador com um token de SSO. Pode adotar este método para desenvolver o seu próprio processador de comandos SSO.

   2. Mova a auth/public pasta para src/public. Esta pasta contém páginas HTML para a aplicação de bot. Ao iniciar fluxos de SSO com Microsoft Entra, o utilizador é redirecionado para estas páginas.

   3. Execute o seguinte comando na ./ pasta:

      npm install copyfiles --save-dev
      

   4. Atualize o seguinte comando no package.json ficheiro:

      "build": "tsc --build && shx cp -r ./src/adaptiveCards ./lib/src && copyfiles src/public/*.html lib/",
      

      As páginas HTML utilizadas para redirecionamento de autenticação são copiadas ao criar este projeto de bot.

   5. No src/index ficheiro, adicione o seguinte comando para importar isomorphic-fetch:

       require("isomorphic-fetch");
      

   6. Adicione o seguinte comando para redirecionar para páginas de autenticação:

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

   7. Atualize commandApp.requestHandler para garantir que a autenticação funciona com o seguinte código:

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

   8. Adicionar ssoConfig e ssoCommands em ConversationBotsrc/internal/initialize:

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

   Extensão de mensagem

   1. Implemente a chave handleMessageExtensionQueryWithSSO de API no TeamsActivityHandler.handleTeamsMessagingExtensionQuery. Para obter mais informações, veja SSO para extensões de mensagens.

   2. Mova a auth/public pasta para src/public. Esta pasta contém páginas HTML para a aplicação de bot. Ao iniciar fluxos de SSO com Microsoft Entra, o utilizador é redirecionado para estas páginas.

   3. Atualize o ficheiro src/index para adicionar o : adequado restify

      const path = require("path");
      
      // Listen for incoming requests.
      server.post("/api/messages", async (req, res) => {
          await adapter.process(req, res, async (context) => {
          await bot.run(context);
          }).catch((err) => {
          // Error message including "412" means it is waiting for user's consent, which is a normal process of SSO, sholdn't throw this error.
          if(!err.message.includes("412")) {
                throw err;
            }
          })
      });
      
      server.get(
          "/auth-:name(start|end).html",
          restify.plugins.serveStatic({
          directory: path.join(__dirname, "public"),
          })
      );
      

   4. Execute os seguintes comandos na ./ pasta:

      npm install @microsoft/teamsfx
      

      npm install isomorphic-fetch
      

   5. Implemente a chave handleMessageExtensionQueryWithSSO de API no TeamsActivityHandler.handleTeamsMessagingExtensionQuery.

   6. Instale copyfiles pacotes npm no projeto de bot TypeScript e atualize o build script no src/package.json ficheiro da seguinte forma:

      "build": "tsc --build && copyfiles ./public/*.html lib/",
      

      As páginas HTML utilizadas para redirecionamento de autenticação são copiadas ao criar este projeto de bot.

   7. Atualize templates/appPackage/aad.template.json o ficheiro com os âmbitos que utiliza na handleMessageExtensionQueryWithSSO função:

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

---

Depurar seu aplicativo

Para depurar a sua aplicação, selecione a chave F5 . O Teams Toolkit utiliza o manifesto Microsoft Entra para registar uma aplicação com SSO ativado. Para obter mais informações, veja depurar a sua aplicação Teams localmente.

Personalizar aplicações Microsoft Entra

O manifesto de aplicação do Teams permite-lhe personalizar diferentes aspetos do registo de aplicações. Pode atualizar o manifesto conforme necessário.

Para incluir permissões de API adicionais para aceder às APIs pretendidas, veja Editar Microsoft Entra manifesto.

Para ver a sua aplicação Microsoft Entra no portal do Azure, veja Editar Microsoft Entra manifesto.

Próxima etapa

Adicionar o logon único ao aplicativo do Teams