TeamsFx SDK

TeamsFx ayuda a reducir las tareas mediante el inicio de sesión único (SSO) de Microsoft Teams y el acceso a los recursos en la nube a instrucciones de línea única sin configuración. Puede usar el SDK de TeamsFx en el explorador y Node.js entornos. Se puede acceder a las funcionalidades principales de TeamsFx en entornos de cliente y servidor. Puede escribir código de autenticación de usuario para:

• Pestaña Teams
• Bot de Teams
• Función de Azure

Requisitos previos

Debe instalar las siguientes herramientas y configurar el entorno de desarrollo:

Para obtener más información sobre Node.js compatibilidad de versiones, consulte Requisitos previos para crear la aplicación de Teams mediante Visual Studio Code.

Debe tener conocimientos prácticos de:

• Código fuente
• Paquete (NPM)
• Documentación de referencia de API
• Ejemplos

Comenzar

El SDK de TeamsFx está preconfigurado en un proyecto con scaffolding mediante el kit de herramientas de TeamsFx o la CLI. Para obtener más información, consulte Proyecto de la aplicación de Teams.

Instale el paquete @microsoft/teamsfx.

Instale el SDK de TeamsFx para TypeScript o JavaScript con npm:

npm install @microsoft/teamsfx

Funcionalidades básicas de TeamsFx

Clase TeamsFx

La instancia de la clase TeamsFx accede a todas las configuraciones de TeamsFx desde las variables de entorno de forma predeterminada. Puede establecer valores de configuración personalizados para invalidar los valores predeterminados. Para obtener más información, consulte invalidación de la configuración para obtener más información. Al crear una instancia de TeamsFx, debe especificar el tipo de identidad.

En la lista siguiente se proporcionan dos tipos diferentes de identidades:

• Identidad de usuario: representa el usuario actual de Teams.

• Identidad de la aplicación: representa la propia aplicación.

  Nota:

  Los constructores y métodos de TeamsFx no son los mismos para estos dos tipos de identidad.

Puede obtener más información sobre la identidad de usuario y la identidad de la aplicación en la sección siguiente:

Credential

Las clases de credenciales implementan la TokenCredential interfaz que se usa ampliamente en las API de biblioteca de Azure diseñadas para proporcionar tokens de acceso para ámbitos específicos. Para obtener más información sobre las clases relacionadas con credenciales y flujos de autenticación, consulte carpeta de credenciales.

Hay tres clases de credenciales para simplificar la autenticación. Estos son los escenarios correspondientes para cada destino de clase de credencial:

const authConfig: TeamsUserCredentialAuthConfig = {
  clientId: process.env.REACT_APP_CLIENT_ID,
  initiateLoginEndpoint: process.env.REACT_APP_START_LOGIN_PAGE_URL,
};

const credential = new TeamsUserCredential(authConfig);

const oboAuthConfig: OnBehalfOfCredentialAuthConfig = {
  authorityHost: process.env.M365_AUTHORITY_HOST,
  clientId: process.env.M365_CLIENT_ID,
  tenantId: process.env.M365_TENANT_ID,
  clientSecret: process.env.M365_CLIENT_SECRET,
};

const oboCredential = new OnBehalfOfUserCredential(ssoToken, oboAuthConfig);

const appAuthConfig: AppCredentialAuthConfig = {
  authorityHost: process.env.M365_AUTHORITY_HOST,
  clientId: process.env.M365_CLIENT_ID,
  tenantId: process.env.M365_TENANT_ID,
  clientSecret: process.env.M365_CLIENT_SECRET,
};
const appCredential = new AppCredential(appAuthConfig);

Inicio de sesión único de bot

Las clases relacionadas con bots se almacenan en la carpeta bot.

TeamsBotSsoPrompt se integra con el marco de bots. Simplifica el proceso de autenticación al desarrollar una aplicación bot y desea usar el inicio de sesión único del bot.

El código siguiente es un ejemplo para crear TeamsBotSsoPrompt:

const TeamsBotSsoPromptId = "TEAMS_BOT_SSO_PROMPT";

const settings: TeamsBotSsoPromptSettings = {
  scopes: ["User.Read"],
  timeout: 900000,
  endOnInvalidMessage: true,
};

const authConfig: OnBehalfOfCredentialAuthConfig = {
  authorityHost: process.env.M365_AUTHORITY_HOST,
  clientId: process.env.M365_CLIENT_ID,
  tenantId: process.env.M365_TENANT_ID,
  clientSecret: process.env.M365_CLIENT_SECRET,
};
const loginUrl = process.env.INITIATE_LOGIN_ENDPOINT;
const ssoPrompt = new TeamsBotSsoPrompt(authConfig, loginUrl, TeamsBotSsoPromptId, settings);

Funciones compatibles

El SDK de TeamsFx proporciona varias funciones para facilitar la configuración de bibliotecas de terceros. Se encuentran en la carpeta principal.

• Microsoft Graph Service:createMicrosoftGraphClient, createMicrosoftGraphClientWithCredentialy MsGraphAuthProvider ayuda a crear una instancia de Graph autenticada.

  Nota:

  createMicrosoftGraphClient la función ha quedado en desuso. Se recomienda usar createMicrosoftGraphClientWithCredential en su lugar para mejorar la experiencia de codificación.

• SQL: getTediousConnectionConfig devuelve una configuración de conexión tediosa.

  Configuración necesaria:

  • Si desea usar la identidad de usuario, se sqlServerEndpointrequiere , sqlUsernamey sqlPassword .
  • Si desea usar la identidad MSI, se sqlServerEndpointrequiere y sqlIdentityId .

  Nota:

  La getTediousConnectionConfig función ha quedado en desuso. Se recomienda que cree su propia configuración tediosa para una mayor flexibilidad.

Invalidación de la configuración de la clase TeamsFx

Puede pasar la configuración personalizada al crear una nueva TeamsFx instancia para invalidar la configuración predeterminada o establecer los campos obligatorios cuando environment variables faltan.

Control de errores

El tipo básico de respuesta de error de API es ErrorWithCode, que contiene el código de error y el mensaje de error. Por ejemplo, para filtrar un error específico, puede usar el siguiente fragmento de código:

try {
  const teamsfx = new TeamsFx();
  await teamsfx.login("User.Read");
} catch (err: unknown) {
  if (err instanceof ErrorWithCode && err.code !== ErrorCode.ConsentFailed) {
    throw err;
  } else {
    // Silently fail because user cancels the consent dialog
    return;
  }
}

try {
  const authConfig: TeamsUserCredentialAuthConfig = {
    clientId: process.env.REACT_APP_CLIENT_ID,
    initiateLoginEndpoint: process.env.REACT_APP_START_LOGIN_PAGE_URL,
  };

  const credential = new TeamsUserCredential(authConfig);  
  await credential.login("User.Read");
} catch (err: unknown) {
  if (err instanceof ErrorWithCode && err.code !== ErrorCode.ConsentFailed) {
    throw err;
  } else {
    // Silently fail because user cancels the consent dialog
    return;
  }
}

Si se usa una instancia de credencial en otra biblioteca, como Microsoft Graph, es posible que se detecte y transforme un error.

Escenarios de Microsoft Graph

En esta sección se proporcionan varios fragmentos de código para escenarios comunes relacionados con Microsoft Graph. En estos escenarios, el usuario puede llamar a las API con permisos diferentes en front-end o back-end.

• Permiso delegado de usuario en front-end (usar TeamsUserCredential)

  Uso de Graph API en la aplicación de pestaña

  Este fragmento de código muestra cómo usar TeamsUserCredential y createMicrosoftGraphClientWithCredential obtener perfiles de usuario de Microsoft Graph en la aplicación de pestaña. También muestra cómo detectar y resolver un objeto GraphError.

  1. Importe las clases necesarias.

     import {
      createMicrosoftGraphClientWithCredential,
      TeamsUserCredential,
     } from "@microsoft/teamsfx";
     

  2. Cree TeamsUserCredential una instancia.

     const authConfig: TeamsUserCredentialAuthConfig = {
     clientId: process.env.REACT_APP_CLIENT_ID!,
     initiateLoginEndpoint: process.env.REACT_APP_START_LOGIN_PAGE_URL!,
     };
     
     const teamsUserCredential = new TeamsUserCredential(authConfig);
     

  3. Use teamsUserCredential.login() para obtener el consentimiento del usuario.

     // Put these code in a call-to-action callback function to avoid browser blocking automatically showing up pop-ups.
     await teamsUserCredential.login(["User.Read"]); // Login with scope
     

  4. Puede inicializar una instancia de TeamsFx y un cliente de grafos y obtener información de Microsoft Graph por parte de este cliente.

     try {
      const graphClient = createMicrosoftGraphClientWithCredential(teamsUserCredential, ["User.Read"]); // Initializes MS Graph SDK using our MsGraphAuthProvider
      const profile = await graphClient.api("/me").get();
     } catch (err: unknown) {
      // ErrorWithCode is handled by Graph client
      if (err instanceof GraphError && err.code?.includes(ErrorCode.UiRequiredError)) {
        // Need to show login button to ask for user consent.
      }
     }
     

  Para obtener más información sobre el ejemplo para usar Graph API en la aplicación de pestaña, vea Ejemplo de aplicación graph conector.

  Integración con Microsoft Graph Toolkit

  La biblioteca del kit de herramientas de Microsoft Graph es una colección de diversos proveedores de autenticación y componentes de interfaz de usuario con tecnología de Microsoft Graph.

  El @microsoft/mgt-teamsfx-provider paquete expone la clase que usa TeamsFx la TeamsFxProvider clase para iniciar sesión a los usuarios y adquirir tokens para usarlos con Microsoft Graph.

  1. Puede instalar los siguientes paquetes necesarios:

        npm install @microsoft/mgt-element @microsoft/mgt-teamsfx-provider @microsoft/teamsfx
     

  2. Inicialice el proveedor dentro del componente.

     // Import the providers and credential at the top of the page
     import {Providers} from '@microsoft/mgt-element';
     import {TeamsFxProvider} from '@microsoft/mgt-teamsfx-provider';
     import {TeamsUserCredential} from "@microsoft/teamsfx";
     
     const scope = ["User.Read"];
     const teamsfx = new TeamsFx();
     const provider = new TeamsFxProvider(teamsfx, scope);
     Providers.globalProvider = provider;   
     

  3. Puede usar el método para obtener el teamsfx.login(scopes) token de acceso necesario.

     // Put these code in a call-to-action callback function to avoid browser blocking automatically showing up pop-ups. 
     await teamsfx.login(this.scope);
     Providers.globalProvider.setState(ProviderState.SignedIn);
     

  4. Puede agregar cualquier componente en la página HTML o en el render() método con React para usar el TeamsFx contexto para acceder a Microsoft Graph.

     <mgt-person query="me" view="threeLines"></mgt-person>
     

     public render(): void {
     return (
      <div>
          <Person personQuery="me" view={PersonViewType.threelines}></Person>
      </div>
     );
     }    
     

  Para obtener más información sobre el ejemplo para inicializar el proveedor TeamsFx, consulte el ejemplo de exportador de contactos.

• Permiso delegado de usuario en back-end (usar OnBehalfOfUserCredential)

  Uso de Graph API en la aplicación bot

  Este fragmento de código muestra cómo usar TeamsBotSsoPrompt para establecer un cuadro de diálogo y, a continuación, iniciar sesión para obtener un token de acceso.

  1. Inicializar y agregar TeamsBotSsoPrompt al conjunto de diálogos.

     const { ConversationState, MemoryStorage } = require("botbuilder");
     const { DialogSet, WaterfallDialog } = require("botbuilder-dialogs");
     const { TeamsBotSsoPrompt, OnBehalfOfCredentialAuthConfig, TeamsBotSsoPromptSettings } = require("@microsoft/teamsfx");
     
     const convoState = new ConversationState(new MemoryStorage());
     const dialogState = convoState.createProperty("dialogState");
     const dialogs = new DialogSet(dialogState);
     
     const TeamsBotSsoPromptId = "TEAMS_BOT_SSO_PROMPT";
     
     const settings: TeamsBotSsoPromptSettings = {
     scopes: ["User.Read"],
     timeout: 900000,
     endOnInvalidMessage: true,
     };
     
     const authConfig: OnBehalfOfCredentialAuthConfig = {
      authorityHost: process.env.M365_AUTHORITY_HOST,
      clientId: process.env.M365_CLIENT_ID,
      tenantId: process.env.M365_TENANT_ID,
      clientSecret: process.env.M365_CLIENT_SECRET,
     };
     const loginUrl = process.env.INITIATE_LOGIN_ENDPOINT;
     const ssoPrompt = new TeamsBotSsoPrompt(authConfig, loginUrl, TeamsBotSsoPromptId, settings);
     
     dialogs.add(ssoPrompt);    
     

  2. Inicie el cuadro de diálogo e inicie sesión.

     dialogs.add(
       new WaterfallDialog("taskNeedingLogin", [
        async (step) => {
          return await step.beginDialog("TeamsBotSsoPrompt");
        },
        async (step) => {
         const token = step.result;
         if (token) {
           // ... continue with task needing access token ...
         } else {
          await step.context.sendActivity(`Sorry... We couldn't log you in. Try again later.`);
          return await step.endDialog();
         }
       },
      ])
     );    
     

  Para obtener más información sobre el ejemplo para usar Graph API en la aplicación bot, consulte ejemplo bot-sso.

  Uso de Graph API en la extensión de mensaje

  El siguiente fragmento de código muestra cómo invalidar handleTeamsMessagingExtensionQuery que se extiende desde TeamsActivityHandlery el uso handleMessageExtensionQueryWithSSO proporcionado por el SDK de TeamsFx para iniciar sesión y obtener un token de acceso:

  
   const authConfig: OnBehalfOfCredentialAuthConfig = {
    authorityHost: process.env.M365_AUTHORITY_HOST,
    clientId: process.env.M365_CLIENT_ID,
    tenantId: process.env.M365_TENANT_ID,
    clientSecret: process.env.M365_CLIENT_SECRET,
   };
   const loginUrl = process.env.INITIATE_LOGIN_ENDPOINT;
   public async handleTeamsMessagingExtensionQuery(context: TurnContext, query: any): Promise<any> {
    return await handleMessageExtensionQueryWithSSO(context, authConfig, loginUrl, 'User.Read', 
      async (token: MessageExtensionTokenResponse) => {
        // ... continue to query with access token ...
      });
   }    
  

  Para obtener más información sobre el ejemplo para usar graph API en la extensión de mensaje, consulte message-extension-sso-sample.

  Uso de Graph API en el bot de comandos

  Este fragmento de código muestra cómo implementar TeamsFxBotSsoCommandHandler para que el bot de comandos llame a La API de Microsoft.

   import { Activity, TurnContext } from "botbuilder";
   import {
    CommandMessage,
    TriggerPatterns,
    createMicrosoftGraphClientWithCredential,
    TeamsFxBotSsoCommandHandler,
    TeamsBotSsoPromptTokenResponse,
   } from "@microsoft/teamsfx";
  
   const authConfig: OnBehalfOfCredentialAuthConfig = {
    authorityHost: process.env.M365_AUTHORITY_HOST,
    clientId: process.env.M365_CLIENT_ID,
    tenantId: process.env.M365_TENANT_ID,
    clientSecret: process.env.M365_CLIENT_SECRET,
   };
   const loginUrl = process.env.INITIATE_LOGIN_ENDPOINT;
  
   export class ProfileSsoCommandHandler implements TeamsFxBotSsoCommandHandler {
    triggerPatterns: TriggerPatterns = "profile";
  
    async handleCommandReceived(
      context: TurnContext,
      message: CommandMessage,
      tokenResponse: TeamsBotSsoPromptTokenResponse,
    ): Promise<string | Partial<Activity> | void> {
  
      const oboCredential = new OnBehalfOfUserCredential(tokenResponse.ssoToken, oboAuthConfig);
  
      // Add scope for your Azure AD app. For example: Mail.Read, etc.
      const graphClient = createMicrosoftGraphClientWithCredential(oboCredential, ["User.Read"]);
  
      // Call graph api use `graph` instance to get user profile information
      const me = await graphClient.api("/me").get();
  
      if (me) {
        // Bot will send the user profile info to user
        return `Your command is '${message.text}' and you're logged in as ${me.displayName}`;
      } else {
        return "Could not retrieve profile information from Microsoft Graph.";
      }
    }
   }    
  
  

  Para obtener más información sobre cómo implementar el controlador de comandos sso en el bot de comandos, consulte Incorporación del inicio de sesión único a la aplicación Teams. Además, hay un proyecto de ejemplo command-bot-with-sso que puede probar el bot de comandos de SSO.

  Llamada a la función de Azure en la aplicación de pestaña: flujo en nombre de

  Este fragmento de código muestra cómo usar CreateApiClient o axios biblioteca para llamar a Azure Function y cómo llamar a Graph API en Azure Function para obtener perfiles de usuario.

  1. Puede usar CreateApiClient el sdk de TeamsFx para llamar a Azure Function:

     async function callFunction() {
       const authConfig: TeamsUserCredentialAuthConfig = {
      clientId: process.env.REACT_APP_CLIENT_ID,
      initiateLoginEndpoint: process.env.REACT_APP_START_LOGIN_PAGE_URL,
       };
      const teamsUserCredential = new TeamsUserCredential(authConfig);
      // Create an API client by providing the token and endpoint.
      const apiClient = CreateApiClient(
        "https://YOUR_API_ENDPOINT", // Create an API Client that uses SSO token to authenticate requests
        new BearerTokenAuthProvider(async () =>  (await teamsUserCredential.getToken(""))!.token) // Call API hosted in Azure Functions on behalf of user to inject token to request header
      );
      // Send a GET request to "RELATIVE_API_PATH", "/api/functionName" for example.
       const response = await apiClient.get("RELATIVE_API_PATH");
       return response.data;
     }    
     

     También puede usar axios la biblioteca para llamar a Azure Function.

     async function callFunction() {
       const authConfig: TeamsUserCredentialAuthConfig = {
         clientId: process.env.REACT_APP_CLIENT_ID,
         initiateLoginEndpoint: process.env.REACT_APP_START_LOGIN_PAGE_URL,
       };
       const teamsUserCredential = new TeamsUserCredential(authConfig);
       const accessToken = await teamsUserCredential.getToken(""); // Get SSO token 
       const endpoint = "https://YOUR_API_ENDPOINT";
       const response = await axios.default.get(endpoint + "/api/" + functionName, {
         headers: {
           authorization: "Bearer " + accessToken.token,
         },
       });
       return response.data;
     }    
     
     

  2. Llame a Graph API en Azure Function en nombre del usuario en respuesta.

     
     export default async function run(
     context: Context,
     req: HttpRequest,
     teamsfxContext: TeamsfxContext
     ): Promise<Response> {
      const res: Response = { status: 200, body: {},};
     
      const authConfig: OnBehalfOfCredentialAuthConfig = {
        authorityHost: process.env.M365_AUTHORITY_HOST,
        clientId: process.env.M365_CLIENT_ID,
        tenantId: process.env.M365_TENANT_ID,
        clientSecret: process.env.M365_CLIENT_SECRET,
      };
      const oboCredential = new OnBehalfOfUserCredential(tokenResponse.ssoToken, oboAuthConfig);
     
      // Query user's information from the access token.
      try {
       const currentUser: UserInfo = await oboCredential.getUserInfo();
       if (currentUser && currentUser.displayName) {
         res.body.userInfoMessage = `User display name is ${currentUser.displayName}.`;
       } else {
         res.body.userInfoMessage = "No user information was found in access token.";
       }
      } catch (e) {
      }
      // Create a graph client to access user's Microsoft 365 data after user has consented.
      try {
       const graphClient: Client = createMicrosoftGraphClientWithCredential(oboCredential, [".default"]);
       const profile: any = await graphClient.api("/me").get();
       res.body.graphClientMessage = profile;
      } catch (e) {
      }
      return res;
      }
     
     

  Para obtener más información sobre el ejemplo para usar Graph API en la aplicación bot, consulte ejemplo hello-world-tab-with-backend.

• Permiso de aplicación en back-end

  Uso de la autenticación basada en certificados en la función de Azure

  Este fragmento de código muestra cómo usar el permiso de aplicación basado en certificados para obtener el token que se puede usar para llamar a Graph API.

  1. Puede inicializar appAuthConfig proporcionando un PEM-encoded key certificateobjeto .

      const appAuthConfig: AppCredentialAuthConfig = {
        authorityHost: process.env.M365_AUTHORITY_HOST,
        clientId: process.env.M365_CLIENT_ID,
        tenantId: process.env.M365_TENANT_ID,
        certificateContent: 'PEM-encoded key certificate',
       };
     
     

  2. Puede usar AppCredential para obtener el token.

     const appCredential = new AppCredential(appAuthConfig);
     const token = appCredential.getToken();    
     

  Uso de la autenticación de secreto de cliente en Azure Function

  Este fragmento de código muestra cómo usar el permiso de aplicación secreta de cliente para obtener el token que se usa para llamar a Graph API.

  1. Puede inicializar authConfig proporcionando un client secretobjeto .

     const appAuthConfig: AppCredentialAuthConfig = {
      authorityHost: process.env.M365_AUTHORITY_HOST,
      clientId: process.env.M365_CLIENT_ID,
      tenantId: process.env.M365_TENANT_ID,
      clientSecret: process.env.M365_CLIENT_SECRET,
     };
     

  2. Puede usar para authConfig obtener el token.

     const appCredential = new AppCredential(appAuthConfig);
     const token = appCredential.getToken();    
     

  Para obtener más información sobre el ejemplo para usar Graph API en la aplicación bot, consulte el ejemplo hello-world-tab-with-backend.

Otros escenarios

En esta sección se proporcionan varios fragmentos de código para otros escenarios relacionados con Microsoft Graph. Puede crear un cliente de API en Bot o Azure Function y acceder a SQL Database en Azure Function.

// Create an API Key auth provider. In addition to APiKeyProvider, following auth providers are also available:
// BearerTokenAuthProvider, BasicAuthProvider, CertificateAuthProvider.
const authProvider = new ApiKeyProvider("YOUR_API_KEY_NAME",
  "YOUR_API_KEY_VALUE",
  ApiKeyLocation.Header
);

// Create an API client using above auth provider.
// You can also implement AuthProvider interface and use it here.
const apiClient = createApiClient(
  "YOUR_API_ENDPOINT",
  authProvider
);

// Send a GET request to "RELATIVE_API_PATH", "/api/apiname" for example.
const response = await apiClient.get("RELATIVE_API_PATH");  

Personalización avanzada

Configuración del registro

Puede establecer el nivel de registro del cliente y redirigir las salidas al usar esta biblioteca.

Habilitación del registro mediante la configuración del nivel de registro

Cuando se establece el nivel de registro, el registro se habilita. Imprime información de registro en la consola de forma predeterminada.

Establezca el nivel de registro mediante el siguiente fragmento de código:

// Only need the warning and error messages.
setLogLevel(LogLevel.Warn);

Redireccionamiento mediante la configuración del registrador personalizado

setLogLevel(LogLevel.Info);
// Set another logger if you want to redirect to Application Insights in Azure Function
setLogger(context.log);

Redireccionamiento mediante la configuración de la función de registro personalizada

setLogLevel(LogLevel.Info);
// Only log error message to Application Insights in bot application.
setLogFunction((level: LogLevel, message: string) => {
  if (level === LogLevel.Error) {
    this.telemetryClient.trackTrace({
      message: message,
      severityLevel: Severity.Error,
    });
  }
});

Actualización a la versión más reciente del SDK

Si usa la versión del SDK que tiene loadConfiguration(), puede realizar los pasos siguientes para actualizar a la versión más reciente del SDK:

1. En lugar de llamar a loadConfiguration(), use las clases de configuración de autenticación específicas para personalizar la configuración de cada tipo de credencial. Por ejemplo, use AppCredentialAuthConfig para AppCredential, OnBehalfOfUserCredentialAuthConfig para OnBehalfOfUserCredentialy TeamsUserCredentialAuthConfig para TeamsUserCredential.
2. Reemplazar new TeamsUserCredential() por new TeamsUserCredential(authConfig).
3. Reemplazar new M365TenantCredential() por new AppCredential(authConfig).
4. Reemplazar new OnBehalfOfUserCredential(ssoToken) por new OnBehalfOfUserCredential(authConfig).

Vea también

• Introducción al kit de herramientas de Teams
• CLI del kit de herramientas de Teams
• Galería de muestra de Microsoft TeamsFx.
• Agregar inicio de sesión único a la aplicación de Teams