Habilitación del inicio de sesión único para la aplicación Teams

Microsoft Teams proporciona una función de inicio de sesión único (SSO) para que una aplicación obtenga el token de usuario de Teams que ha iniciado sesión para acceder a Microsoft Graph y a otras API. Microsoft Teams Toolkit simplifica el proceso mediante la incorporación de ciertos flujos de trabajo e integraciones de Microsoft Entra en API sencillas y de alto nivel. Como resultado, puede incorporar sin esfuerzo funcionalidades de SSO en la aplicación de Teams. Para obtener más información, consulte Autenticación de usuarios en Microsoft Teams.

Configuraciones clave

Para habilitar el inicio de sesión único, configure la aplicación de Teams de la siguiente manera:

• Microsoft Entra manifiesto de aplicación: asegúrese de definir URI, incluido el URI que identifica la aplicación de autenticación de Microsoft Entra y el URI de redireccionamiento que devuelve el token.

• Manifiesto de aplicación de Teams: conecte la aplicación sso a la aplicación de Teams mediante la incorporación de la configuración correcta.

• Archivos de configuración e infraestructura del kit de herramientas de Teams: asegúrese de que se han implementado las configuraciones necesarias para habilitar el inicio de sesión único para la aplicación de Teams.

• Información de la aplicación sso en los archivos de configuración del kit de herramientas de Teams: asegúrese de que la aplicación de autenticación se registra en el servicio back-end y que Teams Toolkit la inicia durante la depuración o la vista previa de la aplicación de Teams.

Aplicación tab

Creación de Microsoft Entra manifiesto de aplicación

1. Descargue la plantilla de manifiesto de aplicación Microsoft Entra.

2. Agregue el código de plantilla de manifiesto de aplicación descargado al ./aad.manifest.json archivo. Esto le permite personalizar diferentes aspectos del registro de la aplicación y actualizar el manifiesto según sea necesario. Para obtener más información, vea manifiesto de aplicación.

Actualización del manifiesto de aplicación de Teams

En el ./appPackages/manifest.json archivo, agregue el código siguiente:

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

webApplicationInfoproporciona su Microsoft Entra id. de aplicación y la información de Microsoft Graph para ayudar a los usuarios a iniciar sesión en la aplicación.

Nota:

Puede usar para hacer {{ENV_NAME}} referencia a variables en el env/.env.{TEAMSFX_ENV} archivo.

Actualizar archivos de configuración del kit de herramientas de Teams

1. Busque los archivos de configuración del kit de herramientas de Teams, como ./teamsapp.yml y ./teamsapp.local.yml. Actualice las configuraciones necesarias relacionadas con Microsoft Entra en estos archivos.

2. Agregue la aadApp/create acción en provision./teamsapp.yml y ./teamsapp.local.yml para crear una nueva aplicación de Microsoft Entra que se usa para el inicio de sesión único:

   - 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
   

   Nota:

   Reemplace el name valor por el nombre deseado para la aplicación de Teams.

   Para obtener más información, vea aadApp/create.

3. Agregue la aadApp/update acción en provision./teamsapp.yml y ./teamsapp.local.yml para actualizar la aplicación de Microsoft Entra:

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

   Nota:

   • Actualice el manifestPath valor a la ruta de acceso relativa de la plantilla aad.manifest.jsonde manifiesto de aplicación Microsoft Entra , si ha cambiado la ruta de acceso del archivo.
   • En una configuración local, coloque después de aad/update la file/createOrUpdateEnvironmentFile acción. Esto es necesario porque aad/update usa la salida de file/createOrUpdateEnvironmentFile.

   Para obtener más información, consulte aadApp/update

4. Para un proyecto de React, actualice cli/runNpmCommand en deploy.

5. Si va a compilar una aplicación de pestaña mediante el marco de React en la CLI, busque la cli/runNpmCommand acción con build app en el teamsapp.yml archivo y agregue las siguientes variables de entorno:

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

6. Si va a compilar una aplicación de pestaña con React marco, busque la acción para la file/createOrUpdateEnvironmentFile implementación en teamsapp.local.yml el archivo y agregue las siguientes variables de entorno:

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

Actualización del código fuente

Con los cambios anteriores implementados, el entorno está preparado. Ahora puede actualizar el código para incorporar el inicio de sesión único en la aplicación de Teams.

JavaScript de vainilla

Para una aplicación de pestaña que no usa React, use el código siguiente como ejemplo básico para obtener el 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}`);
  });
}

React

Para React proyectos, asegúrese de que se establecen las siguientes variables de entorno en el proceso de implementación:

• Para ver un proyecto de JavaScript, consulte la pestaña Ejemplo de JavaScript.

• Para ver un proyecto de TypeScript, consulte la pestaña Ejemplo de TypeScript.

Para actualizar el código fuente, siga estos pasos:

1. Mueva los auth-start.html archivos y auth-end.html de la auth/public carpeta a la public/ carpeta . Estos archivos HTML tienen el propósito de controlar los redireccionamientos de autenticación.

2. Mueva la sso carpeta en auth/ a src/sso/.

   1. InitTeamsFx: este archivo ejecuta una función que inicializa el SDK de TeamsFx. Después de la inicialización del SDK, abre el GetUserProfile componente.
   2. GetUserProfile: este archivo ejecuta una función para recuperar la información del usuario invocando la Graph API de Microsoft.

3. Importe y agregue InitTeamsFxWelcome.*.

Para obtener más información, consulte Aplicación de pestaña habilitada para SSO.

Aplicación de extensión de bot/mensaje

Creación de Microsoft Entra manifiesto de aplicación

1. Descargue la plantilla de manifiesto de aplicación Microsoft Entra.

2. Agregue el código de plantilla de manifiesto de aplicación descargado al ./aad.manifest.json archivo. Esto le permite personalizar diferentes aspectos del registro de la aplicación y actualizar el manifiesto según sea necesario. Para obtener más información, vea manifiesto de aplicación.

Actualización del manifiesto de aplicación de Teams

1. En el ./appPackages/manifest.json archivo, agregue el código siguiente:

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

   webApplicationInfoproporciona su Microsoft Entra id. de aplicación y la información de Microsoft Graph para ayudar a los usuarios a iniciar sesión en la aplicación.

   Nota:

   Puede usar para hacer {{ENV_NAME}} referencia a variables en el env/.env.{TEAMSFX_ENV} archivo.

2. Registre uno o varios comandos en commandLists.

   Incluye commandLists los comandos que el bot puede sugerir a los usuarios. Si usa la plantilla de teamsFx bot, establezca los siguientes valores:

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

3. El validDomains campo incluye los dominios de los sitios web que carga la aplicación dentro del cliente de Teams. Actualice el siguiente valor:

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

Actualizar archivos de configuración del kit de herramientas de Teams

1. Busque los archivos de configuración del kit de herramientas de Teams, como ./teamsapp.yml y ./teamsapp.local.yml. Actualice las configuraciones necesarias relacionadas con Microsoft Entra en estos archivos.

2. Agregue el código aadApp/create siguiente en provision./teamsapp.yml y ./teamsapp.local.yml para crear nuevas aplicaciones de Microsoft Entra usadas para el inicio de sesión único:

   - 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
   

   Nota:

   Reemplace el name valor por el nombre deseado para la aplicación de Microsoft Teams.

   Para obtener más información, vea aadApp/create.

3. Agregue el código aadApp/update siguiente en provision y ./teamsapp.yml./teamsapp.local.yml para actualizar la aplicación de Microsoft Entra:

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

   Nota:

   Actualice el manifestPath valor a la ruta de acceso relativa de la plantilla aad.manifest.jsonde manifiesto de aplicación Microsoft Entra , si ha cambiado la ruta de acceso del archivo.

   Para obtener más información, consulte aadApp/update

4. Busque la acción en teamsapp.local.yml el createOrUpdateEnvironmentFile archivo y agregue las siguientes variables de entorno:

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

Actualizar infra

Actualice las configuraciones relacionadas con Microsoft Entra en el servicio remoto. En el ejemplo siguiente se muestran los valores de configuración en una aplicación web de Azure:

• M365_CLIENT_ID: Microsoft Entra identificador de cliente de la aplicación
• M365_CLIENT_SECRET: Microsoft Entra secreto de cliente de la aplicación
• M365_TENANT_ID: identificador de inquilino de Microsoft Entra aplicación
• INITIATE_LOGIN_ENDPOINT: página de inicio de sesión para la autenticación
• M365_AUTHORITY_HOST: Microsoft Entra host de autoridad de OAuth de la aplicación
• M365_APPLICATION_ID_URI: IDENTIFICADOR URI de Microsoft Entra aplicación

Para usar la plantilla de teamsFx bot o pestaña, siga estos pasos:

1. Abra el infra/azure.parameters.json archivo y agregue el código siguiente:

   "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 el infra/azure.bicep archivo y agregue el código siguiente después de 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. Agregue el código siguiente antes output en el infra/azure.bicep archivo:

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

   Nota:

   • Para agregar configuraciones adicionales a la aplicación web de Azure, agregue las configuraciones en webAppSettings.
   • También puede que tenga que definir la versión predeterminada del nodo agregando la siguiente configuración: bash WEBSITE_NODE_DEFAULT_VERSION: '14.20.0'

   Actualizar código fuente

   Bot

   1. Mueva los archivos ubicados en la auth/sso carpeta a src. La ProfileSsoCommandHandler clase actúa como controlador de comandos sso, diseñado para recuperar información del usuario mediante un token de SSO. Puede adoptar este método para desarrollar su propio controlador de comandos de SSO.

   2. Mueva la auth/public carpeta a src/public. Esta carpeta contiene páginas HTML para la aplicación bot. Al iniciar flujos de SSO con Microsoft Entra, se redirige al usuario a estas páginas.

   3. Ejecute el siguiente comando en la ./ carpeta :

      npm install copyfiles --save-dev
      

   4. Actualice el siguiente comando en el package.json archivo:

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

      Las páginas HTML usadas para la redirección de autenticación se copian al compilar este proyecto de bot.

   5. En src/index el archivo , agregue el siguiente comando para importar isomorphic-fetch:

       require("isomorphic-fetch");
      

   6. Agregue el siguiente comando para redirigir a las páginas de autenticación:

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

   7. Actualice commandApp.requestHandler para asegurarse de que la autenticación funciona con el código siguiente:

      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. Agregue ssoConfig e ssoCommands in ConversationBot en src/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()],
          },
      });
      

   Extensión de mensajería

   1. Implemente la clave handleMessageExtensionQueryWithSSO de API en TeamsActivityHandler.handleTeamsMessagingExtensionQuery. Para obtener más información, consulte SSO para extensiones de mensaje.

   2. Mueva la auth/public carpeta a src/public. Esta carpeta contiene páginas HTML para la aplicación bot. Al iniciar flujos de SSO con Microsoft Entra, se redirige al usuario a estas páginas.

   3. src/index Actualice el archivo para agregar el elemento adecuadorestify:

      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. Ejecute los comandos siguientes en la ./ carpeta :

      npm install @microsoft/teamsfx
      

      npm install isomorphic-fetch
      

   5. Implemente la clave handleMessageExtensionQueryWithSSO de API en TeamsActivityHandler.handleTeamsMessagingExtensionQuery.

   6. Instale copyfiles paquetes npm en el proyecto del bot de TypeScript y actualice el script en src/package.json el build archivo de la siguiente manera:

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

      Las páginas HTML usadas para la redirección de autenticación se copian al compilar este proyecto de bot.

   7. Actualice templates/appPackage/aad.template.json el archivo con los ámbitos que se usan en la handleMessageExtensionQueryWithSSO función :

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

---

Depuración de la aplicación

Para depurar la aplicación, seleccione la tecla F5 . Teams Toolkit usa el manifiesto de Microsoft Entra para registrar una aplicación habilitada para SSO. Para obtener más información, vea Depurar la aplicación de Teams localmente.

Personalización de aplicaciones Microsoft Entra

El manifiesto de aplicación de Teams le permite personalizar diferentes aspectos del registro de la aplicación. Puede actualizar el manifiesto según sea necesario.

Para incluir permisos de API adicionales para acceder a las API deseadas, consulte Editar Microsoft Entra manifiesto.

Para ver la aplicación de Microsoft Entra en Azure Portal, consulta Editar Microsoft Entra manifiesto.

Paso siguiente

Agregar inicio de sesión único a la aplicación de Teams