Compartir a través de

Habilitación del inicio de sesión único en un complemento de Office con autenticación de aplicaciones anidadas

  • Artículo

Puede usar la biblioteca de MSAL.js con autenticación de aplicaciones anidadas para usar el inicio de sesión único (SSO) desde el complemento de Office. El uso de la autenticación de aplicaciones anidadas (NAA) 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.

Cuentas y hosts compatibles con NAA

NAA admite las identidades tanto de cuentas microsoft como de Microsoft Entra ID (profesional o educativa). No admite Azure Active Directory B2C para escenarios de administración de identidades de negocio a consumidor. En la tabla siguiente se explica la compatibilidad actual por plataforma. Las plataformas enumeradas como disponibilidad general (GA) están listas para el uso de producción en el complemento.

Aplicación Web Windows Mac iOS/iPad Android
Excel En versión preliminar En versión preliminar En versión preliminar En versión preliminar en iPad No aplicable
Outlook GA Disponibilidad general en canal actual y canal mensual de empresa, versión preliminar en canales Semi-Annual GA Disponibilidad general (iOS) GA
PowerPoint En versión preliminar En versión preliminar En versión preliminar En versión preliminar en iPad No aplicable
Word En versión preliminar En versión preliminar En versión preliminar En versión preliminar en iPad No aplicable

Importante

Para usar NAA en plataformas que todavía están en versión preliminar (Word, Excel y PowerPoint), únase al Programa Insider de Microsoft 365 (https://insider.microsoft365.com/join) y elija Canal actual (versión preliminar). No use NAA en complementos de producción para ninguna plataforma en versión preliminar. 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).

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

Tendrá que crear un registro de Microsoft App de Azure para el complemento en el 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 al Plataforma de identidad de Microsoft que el complemento se permite que los hosts admitidos puedan realizar la intermediación. 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

El dominio solo debe incluir el origen y no sus subpaths. Por ejemplo:

✔️ brk-multihub://localhost:3000
✔️ brk-multihub://www.contoso.com
❌ brk-multihub://www.contoso.com/go

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. Se recomienda usar la versión más reciente del paquete (en el momento de la última actualización del artículo era la 3.26.0).

    "dependencies": {
    "@azure/msal-browser": "^3.27.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 Microsoft Entra ID 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 al Graph API de Microsoft.

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.

}

    Importante

    La solicitud de token debe incluir ámbitos distintos de , offline_access, profileopenido email. Puede usar cualquier combinación de los ámbitos anteriores, pero debe incluir al menos un ámbito adicional. Si no es así, la solicitud de token puede producir un error.

  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.

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 a Microsoft Entra ID 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 Microsoft Entra ID 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.

Use el código siguiente para comprobar si se admite NAA cuando se carga el complemento.

   Office.context.requirements.isSetSupported("NestedAppAuth", "1.1");

Para obtener más información, consulte los siguientes recursos.

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 Yes
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)
logout No (produce una excepción)
logoutPopup No (produce una excepción)
logoutRedirect No (produce una excepción)
removeEventCallback Yes
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.

Recursos adicionales