Compilación de una pestaña inicio de sesión único de Microsoft Teams con el kit de herramientas de Microsoft Graph

Artículo
03/26/2023

En este tema se describe cómo usar Microsoft Graph Toolkit en una solución de Microsoft Teams. Esta guía es para una aplicación de página única con inicio de sesión único (SSO) y requiere un back-end. Si va a implementar una pestaña de Teams con inicio de sesión interactivo, consulte Compilación de una pestaña de Microsoft Teams.

La creación de una pestaña sso implica los pasos siguientes:

Agregue el kit de herramientas de Microsoft Graph.
Cree la página emergente de autenticación.
Creación de un identificador de aplicación o cliente
Creación del back-end
Inicialice el proveedor MSAL2 de Teams.
Agregar componentes.
Pruebe la aplicación.

Adición del kit de herramientas de Microsoft Graph

Puede usar el kit de herramientas de Microsoft Graph en la aplicación haciendo referencia al cargador directamente (a través de unpkg) o instalando los paquetes npm. Para usar el kit de herramientas, también necesitará el SDK de Microsoft Teams.

unpkg
npm

Para usar el kit de herramientas y el SDK de Teams a través de los cargadores, agregue la referencia en un script al código:

<!-- Microsoft Teams sdk must be referenced before the toolkit -->
<script src="https://unpkg.com/@microsoft/teams-js@2/dist/MicrosoftTeams.min.js" crossorigin="anonymous"></script>
<script src="https://unpkg.com/@microsoft/mgt@2/dist/bundle/mgt-loader.js"></script>

El uso del kit de herramientas a través de módulos ES6 le proporcionará control total del proceso de agrupación y le permitirá agrupar solo el código que necesita para la aplicación. Para usar los módulos ES6, agregue los paquetes npm para el kit de herramientas y el SDK de Microsoft Teams al proyecto:

npm install @microsoft/teams-js @microsoft/mgt-element @microsoft/mgt-teams-msal2-provider @microsoft/mgt-components

A menos que un administrador dé su consentimiento previo a la aplicación, es posible que los usuarios deban dar su consentimiento a los permisos. Para habilitar esto, deberá proporcionar una página que la aplicación de Teams abrirá en un elemento emergente para seguir el flujo de autenticación. Puede hacer que la ruta de acceso a la página sea cualquier cosa siempre que esté en el mismo dominio que la aplicación (por ejemplo, https://yourdomain.com/tabauth). El único requisito para esta página es llamar al TeamsMsal2Provider.handleAuth() método , pero puede agregar cualquier contenido o progreso de carga que desee.

A continuación se muestra un ejemplo de una página básica que controla el flujo de autenticación en el elemento emergente.

unpkg
npm

<!DOCTYPE html>
<html>
  <head>
    <script src="https://unpkg.com/@microsoft/teams-js@2/dist/MicrosoftTeams.min.js" crossorigin="anonymous"></script>
    <script src="https://unpkg.com/@microsoft/mgt@2/dist/bundle/mgt-loader.js"></script>
  </head>

  <body>
    <script>
      mgt.TeamsMsal2Provider.handleAuth();
    </script>
  </body>
</html>

import { TeamsMsal2Provider } from '@microsoft/mgt-teams-msal2-provider';

TeamsMsal2Provider.handleAuth();

Creación de un identificador de aplicación o cliente

La pestaña debe ejecutarse como una aplicación de Azure AD registrada para obtener un token de acceso de Azure AD. Registre la aplicación en el inquilino y conceda permiso a Microsoft Teams para obtener tokens de acceso en su nombre:

Abra un explorador y vaya al Centro de administración de Azure Active Directory. Inicie sesión con una cuenta personal (cuenta Microsoft) o una cuenta profesional o educativa.
En el panel izquierdo, seleccione Azure Active Directory y, a continuación, seleccione Registros de aplicaciones en Administrar.
Seleccione Nuevo registro. En la página Registrar una aplicación, establezca los valores siguientes:
- Establezca NombreNode.js Teams SSO en (o un nombre de su elección).
- Establezca Tipos de cuenta admitidos en Cuentas en cualquier directorio de organización y cuentas personales de Microsoft.
- En URI de redirección, establezca la primera lista desplegable Single Page Application en y establezca el valor en la dirección URL de página de autenticación que creó en el paso anterior; por ejemplo, https://myapp.ngrok.io/tabauth.
En la página de información general de la aplicación, copie el valor del identificador de aplicación (cliente) para más adelante. Necesitará este valor al crear un nuevo proveedor y en el back-end.
En Administrar, vaya a Secretos de certificados&. Seleccione el botón Nuevo secreto de cliente. Escriba un valor en Descripción, y seleccione una de las opciones para Expira, y después, Agregar.
Copie el valor del secreto del cliente antes de salir de esta página. Necesitará esto para el servicio back-end.

Importante

El secreto de cliente no se vuelve a mostrar, así que asegúrese de copiarlo en este momento.
En Administrar, vaya a Permisos de API. Seleccione Agregar un permiso>Permisos delegados deMicrosoft Graph> y agregue los permisos siguientes: email, offline_access, openid, profile, User.Read. Seleccione Agregar permisos.
(OPCIONAL) Si desea dar su consentimiento previo a cualquier otro ámbito, puede agregar más permisos. Si usa componentes diferentes o planea usar otras API de Microsoft Graph, es posible que necesite permisos adicionales. Para obtener más información sobre los permisos necesarios, consulte la documentación de cada componente.
- Para realizar el consentimiento previo como administrador, seleccione Conceder consentimiento de administrador y, a continuación, seleccione Sí.
En Administrar, vaya a Exponer una API. En la parte superior de la página, junto a Application ID URI, seleccione Establecer. Esto genera una API en forma de: api://{AppID}. Actualícelo para agregar el subdominio; por ejemplo, api://myapp.ngrok.io/{appID}.
En la misma página, seleccione Agregar un ámbito. Rellene los campos de la siguiente manera y seleccione Agregar ámbito:
- Nombre del ámbito: access_as_user
- ¿Quién puede dar su consentimiento?: administradores y usuarios
- Administración nombre para mostrar del consentimiento:Teams can access the user’s profile
- Administración descripción del consentimiento:Allows Teams to call the app’s web APIs as the current user
- Nombre para mostrar del consentimiento del usuario: Teams can access the user profile and make requests on the user's behalf
- Descripción del consentimiento del usuario: Enable Teams to call this app’s APIs with the same rights as the user.
- Estado: habilitado
La dirección URL de la API debe tener el siguiente aspecto: api://myapp.ngrok.io/{appID}/access_as_user.
A continuación, agregue dos aplicaciones cliente. Esto es para los clientes de escritorio o móviles de Teams y el cliente web. En la sección Aplicaciones cliente autorizadas , seleccione Agregar una aplicación cliente. Rellene el id. de cliente y seleccione el ámbito que ha creado. A continuación, seleccione Agregar aplicación. Haga esto para los siguientes identificadores:
- 5e3ce6c0-2b1f-4285-8d4b-75ee78787346
- 1fec8e78-bli4-4aaf-ab1b-5451cc387264

Creación del back-end

El back-end puede ser cualquier back-end que permita intercambiar el token de autenticación de Microsoft Teams con un token que se pueda usar para llamar a Microsoft Graph a través del flujo en nombre de .

Para obtener referencia, consulte el ejemplo de nodo de INICIO de sesión único de Teams.

A continuación se muestra una implementación de referencia de un servidor express de nodo:

import dotenv from 'dotenv';
import express from 'express';
import path from 'path';
import * as msal from '@azure/msal-node';
import { NextFunction, Request, Response } from 'express';
import jwt, { JwtHeader, SigningKeyCallback } from 'jsonwebtoken';
import jwksClient from 'jwks-rsa';
import jwt_decode from 'jwt-decode';

// Load .env file
dotenv.config();

/**
 * Validates a JWT
 * @param {Request} req - The incoming request
 * @param {Response} res - The outgoing response
 * @returns {Promise<string | null>} - Returns the token if valid, returns null if invalid
 */
function validateJwt(req: Request, res: Response, next: NextFunction): void {
  const authHeader = req.headers.authorization!;
  const ssoToken = authHeader.split(' ')[1];
  if (ssoToken) {
    const validationOptions = {
      audience: process.env.CLIENT_ID,
    };
    jwt.verify(ssoToken, getSigningKey, validationOptions, (err, payload) => {
      if (err) {
        return res.sendStatus(403);
      }
      next();
    });
  } else {
    res.sendStatus(401);
  }
}

/**
 * Parses the JWT header and retrieves the appropriate public key
 * @param {JwtHeader} header - The JWT header
 * @param {SigningKeyCallback} callback - Callback function
 */
function getSigningKey(header: JwtHeader, callback: SigningKeyCallback): void {
  const client = jwksClient({
    jwksUri: 'https://login.microsoftonline.com/common/discovery/keys'
  });
  client.getSigningKey(header.kid!, (err, key) => {
    if (err) {
      callback(err, undefined);
    } else {
      callback(null, key.getPublicKey());
    }
  });
}

/**
 * Gets an access token for the user using the on-behalf-of flow
 * @param authHeader - The Authorization header value containing a JWT bearer token
 * @returns {Promise<string | null>} - Returns the access token if successful, null if not
 */
async function getAccessTokenOnBehalfOf(req: Request, res: Response): Promise<void> {
  // The token has already been validated, just grab it
  const authHeader = req.headers.authorization!;
  const ssoToken = authHeader.split(' ')[1];

  // Create an MSAL client
  const msalClient = new msal.ConfidentialClientApplication({
    auth: {
      clientId: req.body.clientid,
      clientSecret: process.env.APP_SECRET
    }
  });

  try {
    const result = await msalClient.acquireTokenOnBehalfOf({
      authority: `https://login.microsoftonline.com/${jwt_decode<any>(ssoToken).tid}`,
      oboAssertion: ssoToken,
      scopes: req.body.scopes,
      skipCache: true
    });
    res.json({ access_token: result?.accessToken });
  } catch (error) {
    if (error.errorCode === 'invalid_grant' || error.errorCode === 'interaction_required') {
      // This is expected if it's the user's first time running the app ( user must consent ) or the admin requires MFA
      res.status(403).json({ error: 'consent_required' }); // This error triggers the consent flow in the client.
    } else {
      // Unknown error
      res.status(500).json({ error: error.message });
    }
  }
}

////////////////////////
// create and run server
////////////////////////

const app = express();
const PORT = process.env.port || process.env.PORT || 8000;

// Support JSON payloads
app.use(express.json());
app.use(express.static(path.join(__dirname, 'client')));

// An example for using POST and with token validation using middleware
app.post('/api/token', validateJwt, async (req, res) => {
  await getAccessTokenOnBehalfOf(req, res);
});

app.listen(PORT, () => {
  console.log(`⚡️[server]: Server is running at http://localhost:${PORT}`);
});

Inicializar el proveedor MSAL2 de Teams

Los proveedores de Microsoft Graph Toolkit habilitan la autenticación y el acceso a Microsoft Graph. Para más información, vea Usar los proveedores. El proveedor MSAL2 de Teams controla toda la lógica y las interacciones que deben implementarse con el SDK de Teams para autenticar al usuario.

En el modo sso, asegúrese de proporcionar sso-url / ssoUrl y hacer que apunte a la API de back-end.

HTML
JavaScript

Agregue en el mgt-teams-msal2-provider HTML.

<mgt-teams-msal2-provider
  client-id="<YOUR_CLIENT_ID>"
  auth-popup-url="/tabauth"
  scopes="User.Read,Mail.ReadBasic"
  sso-url="http://localhost:8000/api/token"
  http-method="POST"
  ></mgt-teams-msal2-provider>

Reemplace por <YOUR_CLIENT_ID> el identificador de cliente de la aplicación, reemplace auth-popup-url por la ruta de acceso completa o relativa a la página de autenticación y reemplace por sso-url la ruta de acceso completa o relativa al servicio back-end.

Para inicializar el proveedor en el código JavaScript, importe TeamsMsal2Provider y establezca .globalProvider

import {Providers} from '@microsoft/mgt-element';
import {TeamsMsal2Provider, HttpMethod} from '@microsoft/mgt-teams-msal2-provider';
import * as MicrosoftTeams from "@microsoft/teams-js";

TeamsMsal2Provider.microsoftTeamsLib = MicrosoftTeams;

Providers.globalProvider = new TeamsMsal2Provider({
  clientId: `<YOUR_CLIENT_ID>`,
  authPopupUrl: '/tabauth',
  scopes: ['User.Read','Mail.ReadBasic'],
  ssoUrl: 'http://localhost:8000/api/token',
  httpMethod: HttpMethod.POST
});

Reemplace por <YOUR_CLIENT_ID> el identificador de cliente de la aplicación, reemplace authPopupUrl por la ruta de acceso completa o relativa a la página de autenticación y reemplace por ssoUrl la ruta de acceso completa o relativa al servicio back-end.

Agregar componentes

Ahora, está listo para agregar cualquiera de los componentes del kit de herramientas de Microsoft Graph.

Puede agregar componentes al código HTML como lo haría normalmente. Por ejemplo, para agregar el Person componente, agregue el código siguiente al código HTML.

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

Si usa React, se recomienda usar los componentes de React en su lugar desde la mgt-react biblioteca. Para obtener más información, consulte Uso del kit de herramientas de Microsoft Graph con React.

Prueba del ejemplo

Para obtener información sobre la implementación completa, consulte el ejemplo de nodo sso de Teams.

Si todo se ha configurado correctamente, verá el Person componente representado sin necesidad de iniciar sesión.

Importante

Si no ha dado su consentimiento previo, es posible que tenga que dar su consentimiento a través de un aviso.

Pasos siguientes

Pruebe los componentes del área de juegos.
Haga una pregunta en Microsoft Q&A.
Informe de errores o deje una solicitud de característica en GitHub.

Compilación de una pestaña inicio de sesión único de Microsoft Teams con el kit de herramientas de Microsoft Graph

Adición del kit de herramientas de Microsoft Graph

Creación de un identificador de aplicación o cliente

Creación del back-end

Inicializar el proveedor MSAL2 de Teams

Agregar componentes

Prueba del ejemplo

Pasos siguientes

Recursos adicionales

Recursos adicionales

Compilación de una pestaña inicio de sesión único de Microsoft Teams con el kit de herramientas de Microsoft Graph

Adición del kit de herramientas de Microsoft Graph

Crear la página emergente de autenticación

Creación de un identificador de aplicación o cliente

Creación del back-end

Inicializar el proveedor MSAL2 de Teams

Agregar componentes

Prueba del ejemplo

Pasos siguientes

Recursos adicionales

Recursos adicionales