Habilitación del inicio de sesión único en un complemento de Office mediante la autenticación de aplicaciones anidadas (versión preliminar)

Puede usar la biblioteca de MSAL.js (versión 3.11 y posteriores) con la autenticación de aplicaciones anidadas para usar el inicio de sesión único desde el complemento de Office. El uso de la autenticación de aplicaciones anidadas ofrece varias ventajas sobre el flujo en nombre de (OBO).

• Solo necesita usar la biblioteca MSAL.js y no necesita la getAccessToken función en Office.js.
• Puede llamar a servicios como Microsoft Graph con un token de acceso desde el código de cliente como SPA. No es necesario un servidor de nivel intermedio.
• Puede usar el consentimiento incremental y dinámico para los ámbitos.
• No es necesario autenticar previamente los hosts (por ejemplo, Teams, Office) para llamar a los puntos de conexión.

Importante

La autenticación de aplicaciones anidadas (NAA) está actualmente en versión preliminar. Para probar esta característica, únase al Programa Insider de Microsoft 365 (https://insider.microsoft365.com/join) y elija el canal beta. No use NAA en complementos de producción. Le invitamos a probar NAA en entornos de prueba o desarrollo y recibir comentarios sobre su experiencia a través de GitHub (consulte la sección Comentarios al final de esta página). NAA se admite en las siguientes compilaciones.

• Word, Excel, PowerPoint y Outlook en la compilación 16.0.17531.20000 o posterior de Windows
• Word, Excel, PowerPoint y Outlook en Mac compilación 16.85.24040319 o posterior

La compatibilidad con NAA en el código de activación basado en eventos en Outlook estará disponible próximamente.

Registro de la aplicación de página única

Tendrá que crear un registro de aplicaciones de Microsoft Azure para el complemento en Azure Portal. El registro de la aplicación debe tener como mínimo:

• Un nombre
• Un tipo de cuenta compatible
• Redireccionamiento de SPA

Si el complemento requiere un registro de aplicación adicional más allá de NAA y SSO, consulte Aplicación de página única: Registro de aplicaciones.

Incorporación de un agente de confianza a través del redireccionamiento de SPA

Para habilitar NAA, el registro de la aplicación debe incluir un URI de redireccionamiento específico para indicar a la plataforma de identidad de Microsoft que el complemento se permite a sí mismo ser administrado por hosts admitidos. El URI de redireccionamiento de la aplicación debe ser de tipo Aplicación de página única y cumplir con el siguiente esquema.

brk-multihub://your-add-in-domain

Por ejemplo, si estuviera probando el complemento en el puerto 3000 en el servidor localhost, usaría brk-multihub://localhost:3000 como valor de redireccionamiento.

Los grupos de agentes de confianza son dinámicos por diseño y se pueden actualizar en el futuro para incluir hosts adicionales donde el complemento puede usar flujos NAA. Actualmente, el grupo brk-multihub incluye Office Word, Excel, PowerPoint, Outlook y Teams (para cuando Office está activado dentro).

Configuración de la configuración de MSAL para usar NAA

Configure el complemento para que use NAA llamando a la createNestablePublicClientApplication función en MSAL. MSAL devuelve una aplicación cliente pública que se puede anidar en un host de aplicación nativo (por ejemplo, Outlook) para adquirir tokens para la aplicación.

En los pasos siguientes se muestra cómo habilitar NAA en el taskpane.js archivo o taskpane.ts en un proyecto creado con yo office (proyecto del panel de tareas del complemento de Office ).

1. Agregue el @azure/msal-browser paquete a la dependencies sección del package.json archivo del proyecto. Para obtener más información sobre este paquete, consulte Biblioteca de autenticación de Microsoft para JavaScript (MSAL.js) para aplicaciones Browser-Based Single-Page.

   "dependencies": {
       "@azure/msal-browser": "^3.15.0",
       ...
   

2. Guarde y ejecute npm install para instalar @azure/msal-browser.

3. Agregue el código siguiente a la parte superior del taskpane.js archivo o taskpane.ts . Esto importará la biblioteca del explorador MSAL.

   import { createNestablePublicClientApplication } from "@azure/msal-browser";
   

Inicializar la aplicación cliente pública

A continuación, debe inicializar MSAL y obtener una instancia de la aplicación cliente pública. Esto se usa para obtener tokens de acceso cuando es necesario. Se recomienda colocar el código que crea la aplicación cliente pública en el Office.onReady método .

• En la Office.onReady función, agregue una llamada a como se muestra a createNestablePublicClientApplication continuación. Reemplace el marcador de Enter_the_Application_Id_Here posición por el identificador de aplicación de Azure que guardó anteriormente.

  let pca = undefined;
  Office.onReady(async (info) => {
    if (info.host) {
      document.getElementById("sideload-msg").style.display = "none";
      document.getElementById("app-body").style.display = "flex";
      document.getElementById("run").onclick = run;
  
      // Initialize the public client application
      pca = await createNestablePublicClientApplication({
        auth: {
          clientId: "Enter_the_Application_Id_Here",
          authority: "https://login.microsoftonline.com/common"
        },
      });
    }
  });
  

Nota:

El ejemplo de código anterior establece la autoridad en común, que admite cuentas profesionales y educativas o cuentas personales de Microsoft. Si desea configurar un único inquilino u otros tipos de cuenta, consulte Opciones de configuración de la aplicación para obtener opciones de autoridad adicionales.

Adquisición del primer token

Los tokens adquiridos por MSAL.js a través de NAA se emitirán para el identificador de registro de la aplicación de Azure. En este ejemplo de código, adquirirá un token para Microsoft Graph API. Si el usuario tiene una sesión activa con el identificador de Microsoft Entra, el token se adquiere de forma silenciosa. Si no es así, la biblioteca solicita al usuario que inicie sesión de forma interactiva. A continuación, el token se usa para llamar a Microsoft Graph API.

En los pasos siguientes se muestra el patrón que se va a usar para adquirir un token.

1. Especifique los ámbitos. NAA admite el consentimiento incremental y dinámico, por lo que siempre solicite los ámbitos mínimos necesarios para que el código complete su tarea.
2. Llamar a acquireTokenSilent. Esto obtendrá el token sin necesidad de interacción del usuario.
3. Si acquireTokenSilent se produce un error, llame acquireTokenPopup a para mostrar un cuadro de diálogo interactivo para el usuario. acquireTokenSilent puede producir un error si el token ha expirado o el usuario aún no ha dado su consentimiento a todos los ámbitos solicitados.

En el código siguiente se muestra cómo implementar este patrón de autenticación en su propio proyecto.

1. Reemplace la run función en taskpane.js o taskpane.ts por el código siguiente. El código especifica los ámbitos mínimos necesarios para leer los archivos del usuario.

   async function run() {
   // Specify minimum scopes needed for the access token.
   const tokenRequest = {
     scopes: ["Files.Read", "User.Read", "openid", "profile"],
   };
   let accessToken = null;
   
   // TODO 1: Call acquireTokenSilent.
   
   // TODO 2: Call acquireTokenPopup.
   
   // TODO 3: Log error if token still null.
   
   // TODO 4: Call the Microsoft Graph API.
   
   }
   

2. Reemplace TODO 1 por el código siguiente. Este código llama acquireTokenSilent a para obtener el token de acceso.

   try {
     console.log("Trying to acquire token silently...");
     const userAccount = await pca.acquireTokenSilent(tokenRequest);
     console.log("Acquired token silently.");
     accessToken = userAccount.accessToken;
   } catch (error) {
     console.log(`Unable to acquire token silently: ${error}`);
   }
   

3. Reemplace TODO 2 por el código siguiente. Este código comprueba si se adquiere el token de acceso. Si no es así, intenta obtener interactivamente el token de acceso llamando a acquireTokenPopup.

   if (accessToken === null) {
     // Acquire token silent failure. Send an interactive request via popup.
     try {
       console.log("Trying to acquire token interactively...");
       const userAccount = await pca.acquireTokenPopup(tokenRequest);
       console.log("Acquired token interactively.");
       accessToken = userAccount.accessToken;
     } catch (popupError) {
       // Acquire token interactive failure.
       console.log(`Unable to acquire token interactively: ${popupError}`);
     }
   }
   

4. Reemplace TODO 3 por el código siguiente. Si se produce un error en el inicio de sesión silencioso e interactivo, registre el error y vuelva.

   // Log error if both silent and popup requests failed.
   if (accessToken === null) {
     console.error(`Unable to acquire access token.`);
     return;
   }
   

Llamada a una API

Después de adquirir el token, úselo para llamar a una API. En el ejemplo siguiente se muestra cómo llamar a Microsoft Graph API mediante una llamada con fetch el token adjunto en el encabezado Authorization .

• Reemplace TODO 4 por el código siguiente.

  // Call the Microsoft Graph API with the access token.
  const response = await fetch(
    `https://graph.microsoft.com/v1.0/me/drive/root/children?$select=name&$top=10`,
    {
      headers: { Authorization: accessToken },
    }
  );
  
  if (response.ok) {
    // Write file names to the console.
    const data = await response.json();
    const names = data.value.map((item) => item.name);
  
    // Be sure the taskpane.html has an element with Id = item-subject.
    const label = document.getElementById("item-subject");
  
    // Write file names to task pane and the console.
    const nameText = names.join(", ");
    if (label) label.textContent = nameText;
    console.log(nameText);
  } else {
    const errorText = await response.text();
    console.error("Microsoft Graph call failed - error text: " + errorText);
  }
  

Una vez agregado todo el código anterior a la run función, asegúrese de que un botón del panel de tareas llama a la run función. A continuación, puede transferir localmente el complemento y probar el código.

¿Qué es la autenticación de aplicaciones anidadas?

La autenticación de aplicaciones anidadas habilita el inicio de sesión único para las aplicaciones anidadas dentro de las aplicaciones admitidas de Microsoft. Por ejemplo, Excel en Windows ejecuta el complemento dentro de una vista web. En este escenario, el complemento es una aplicación anidada que se ejecuta dentro de Excel, que es el host. NAA también admite aplicaciones anidadas en Teams. Por ejemplo, si una pestaña de Teams hospeda Excel y se carga el complemento, se anida dentro de Excel, que también está anidado dentro de Teams. De nuevo, NAA admite este escenario anidado y puede acceder al inicio de sesión único para obtener la identidad de usuario y los tokens de acceso del usuario que ha iniciado sesión.

Cuentas y hosts compatibles con NAA

NAA admite identidades de Microsoft Accounts e Microsoft Entra ID (profesionales o educativas). No admite escenarios B2C. Para la versión preliminar, NAA es compatible con Office en Windows y en Mac. Para disponibilidad general, NAA también admitirá Office en la web y Outlook mobile en Android y en iOS.

Procedimientos recomendados

Se recomiendan los siguientes procedimientos recomendados al usar MSAL.js con NAA.

Usar la autenticación silenciosa siempre que sea posible

MSAL.js proporciona el método que controla la acquireTokenSilent renovación de tokens mediante la realización de solicitudes de token silenciosas sin preguntar al usuario. El método busca primero un token almacenado en caché válido. Si no encuentra una, la biblioteca realiza la solicitud silenciosa al identificador de Microsoft Entra y, si hay una sesión de usuario activa, se devuelve un token nuevo.

En algunos casos, se produce un error en el acquireTokenSilent intento del método de obtener el token. Algunos ejemplos de esto son cuando hay una sesión de usuario expirada con el identificador de Microsoft Entra o un cambio de contraseña por parte del usuario, lo que requiere la interacción del usuario. Cuando se produce un error en acquireTokenSilent, debe llamar al método de token interactivo acquireTokenPopup .

Tener una reserva cuando no se admite NAA

Aunque nos esforzamos por proporcionar un alto grado de compatibilidad con estos flujos en todo el ecosistema de Microsoft, es posible que el complemento se cargue en un host de Office anterior que no admita NAA. En estos casos, el complemento no admitirá el inicio de sesión único de conexión directa y es posible que tenga que recurrir a un método alternativo para autenticar al usuario. En general, querrá usar el patrón de autenticación de MSAL SPA con la API de diálogo de Office JS. Para obtener más información, consulte los siguientes recursos.

• Autentíquese y autorice con la API de cuadro de diálogo de Office.
• Ejemplo de identidad de Microsoft para SPA y JavaScript
• Ejemplos de identidad de Microsoft para varios tipos de aplicaciones y marcos

API de MSAL.js compatibles con NAA

En la tabla siguiente se muestran las API que se admiten cuando NAA está habilitado en la configuración de MSAL.

Método	Compatible con NAA
acquireTokenByCode	NO (produce una excepción)
acquireTokenPopup	SÍ
acquireTokenRedirect	NO (produce una excepción)
acquireTokenSilent	SÍ
addEventCallback	SÍ
addPerformanceCallback	NO (produce una excepción)
disableAccountStorageEvents	NO (produce una excepción)
enableAccountStorageEvents	NO (produce una excepción)
getAccountByHomeId	SÍ
getAccountByLocalId	SÍ
getAccountByUsername	SÍ
getActiveAccount	SÍ
getAllAccounts	SÍ
getConfiguration	SÍ
getLogger	SÍ
getTokenCache	NO (produce una excepción)
handleRedirectPromise	NO
initialize	SÍ
initializeWrapperLibrary	SÍ
loginPopup	SÍ
loginRedirect	NO (produce una excepción)
Cerrar sesión	NO (produce una excepción)
logoutPopup	NO (produce una excepción)
logoutRedirect	NO (produce una excepción)
removeEventCallback	SÍ
removePerformanceCallback	NO (produce una excepción)
setActiveAccount	NO
setLogger	SÍ
ssoSilent	SÍ

Informes de seguridad

Si encuentra un problema de seguridad con nuestras bibliotecas o servicios, notifique el problema con secure@microsoft.com la mayor cantidad de detalles que pueda proporcionar. Su envío puede ser apto para obtener una recompensa a través del programa de recompensas de Microsoft . No publique problemas de seguridad en GitHub ni en ningún otro sitio público. Nos pondremos en contacto con usted poco después de recibir el informe de problemas. Le recomendamos que obtenga nuevas notificaciones de incidentes de seguridad visitando las notificaciones de seguridad técnica de Microsoft para suscribirse a alertas de avisos de seguridad.

Ejemplos de código

Ejemplo de nombre	Descripción
Complemento de Office con SSO mediante la autenticación de aplicaciones anidadas	Muestra cómo usar MSAL.js autenticación de aplicaciones anidadas (NAA) en un complemento de Office para acceder a las API de Microsoft Graph para el usuario que ha iniciado sesión. En el ejemplo se muestra el nombre y el correo electrónico del usuario que ha iniciado sesión. También inserta los nombres de los archivos de la cuenta de Microsoft OneDrive del usuario en el documento.
Complemento de Outlook con SSO mediante la autenticación de aplicaciones anidadas	Muestra cómo usar MSAL.js autenticación de aplicaciones anidadas (NAA) en un complemento de Outlook para acceder a las API de Microsoft Graph para el usuario que ha iniciado sesión. En el ejemplo se muestra el nombre y el correo electrónico del usuario que ha iniciado sesión. También inserta los nombres de los archivos de la cuenta de Microsoft OneDrive del usuario en un nuevo cuerpo del mensaje.