Compartir a través de

Autenticación de aplicaciones anidadas

  • Artículo

Nota:

NAA es un nuevo protocolo de autenticación para SPA que se inserta en entornos host, como Teams, Outlook y Microsoft 365. Simplifica el proceso de autenticación para facilitar el inicio de sesión único (SSO) entre las aplicaciones anidadas dentro de las aplicaciones host admitidas. El modelo NAA admite una identidad principal para la aplicación host que incluye varias identidades de aplicación para aplicaciones anidadas. Microsoft usa este modelo en pestañas de Teams, aplicaciones personales y complementos de Office.

El modelo NAA proporciona varias ventajas sobre el flujo en nombre de (OBO):

  • NAA requiere que use solo la biblioteca de MSAL.js. No es necesario usar la función en la getAuthToken biblioteca cliente JavaScript de Teams (TeamsJS).
  • 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 (permisos).
  • No es necesario autenticar previamente los hosts, como Teams o Microsoft 365, para llamar a los puntos de conexión.

En la tabla siguiente se describe la diferencia entre Teams Microsoft Entra SSO y NAA:

Pasos necesarios para el desarrollo Inicio de sesión único tradicional de Teams Entra NAA
Exponer el URI de redireccionamiento Obligatorio Obligatorio
Registro de LA API en Microsoft Entra ID Obligatorio
Definir un ámbito personalizado en Microsoft Entra ID Obligatorio
Autorización de aplicaciones cliente de Teams Obligatorio
Revisión del manifiesto de aplicación (anteriormente denominado manifiesto de aplicación de Teams) Obligatorio Recomendado*
Adquisición de un token de acceso a través del SDK de TeamsJS Obligatorio
Solicitar el consentimiento del usuario para obtener más permisos Obligatorio
Realizar un intercambio OBO en el servidor Obligatorio
  • El administrador de TI puede bloquear la aplicación o dar su consentimiento solo a determinados permisos para la aplicación en Microsoft Entra ID. Para evitarlo, debe incluir el identificador de la aplicación y el recurso predeterminado en el manifiesto de la aplicación para que el administrador apruebe los permisos en el Centro de administración de Teams.

Casos de uso para NAA

Escenario Descripción
Consentimiento al inicio de sesión único (y otros permisos) Tom, un nuevo miembro del equipo de diseño de Contoso, debe usar la aplicación Contoso en las reuniones de Teams para colaborar en pizarras. Tras el primer uso, un cuadro de diálogo solicita a Tom que conceda permisos, incluida la lectura de su perfil para su avatar (User.Read). Después de dar su consentimiento, Tom puede usar Contoso sin problemas en futuras reuniones entre dispositivos.
Autenticación de reautenticación o acceso condicional autenticación de paso a paso Tom, al trabajar desde Australia, encuentra un desencadenador de acceso condicional que requiere autenticación multifactor (MFA) para acceder a Contoso en Teams. Un cuadro de diálogo informa a Tom de que se necesita más verificación, lo que les lleva a través del proceso de MFA para continuar usando Contoso.
Errores Tom se enfrenta a un error de inicio de sesión con Contoso debido a un problema al recuperar la información de la cuenta. Tom encuentra un botón de reintento que le pide que vuelva a autenticarse. Sin embargo, descubren que el administrador del sistema tiene acceso restringido a Contoso.

Configuración de NAA

Nota:

  • Dado que NAA está en versión preliminar para desarrolladores y no es compatible con todos los entornos host, asegúrese de comprobar el estado de soporte técnico mediante la función isNAAChannelRecommended() y proporcione una experiencia de reserva para entornos no admitidos.
  • Si la API devuelve el valor como true, llame a La biblioteca de autenticación de Microsoft (MSAL) para el flujo NAA. Si devuelve false, siga usando el método de recuperación de tokens existente.

Para configurar la autenticación anidada, siga estos pasos:

  1. Registro de su SPA
  2. Incorporación de agentes de confianza
  3. Inicializar la aplicación cliente pública
  4. Adquisición del primer token
  5. Llamada a una API

Registro de su SPA

Debe crear un registro de aplicación Microsoft Entra ID para el complemento en Azure Portal. El registro de la aplicación debe tener un nombre, un tipo de cuenta compatible y un redireccionamiento spa. Después del registro de la aplicación, Azure Portal genera un identificador de registro de aplicación Microsoft Entra. Si el complemento requiere un registro de aplicación adicional más allá de NAA y SSO, consulte Registro de la aplicación de página única.

Incorporación de agentes de confianza

Para configurar la autenticación de aplicaciones anidadas, la aplicación debe configurar activamente un URI de redireccionamiento para la aplicación. El URI de redireccionamiento indica al Plataforma de identidad de Microsoft que los hosts admitidos pueden intermediar la aplicació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_domain>

Donde,

  • brk-multihub permite que la autenticación se broker mediante cualquier host compatible con Microsoft 365 que esté configurado para ejecutarse en, por ejemplo, Teams, Outlook o Microsoft365.com.
  • < > your_domain es el nombre de dominio completo donde se hospeda la aplicación. Por ejemplo, brk-multihub://contoso.com.

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

✔️ brk-multihub://myapp.teams.microsoft.com
❌ brk-multihub://myapp.teams.microsoft.com/go

Para obtener más información sobre cómo actualizar la aplicación de Teams para que se ejecute en Outlook y Microsoft365.com, consulte Extensión de aplicaciones de Teams en Microsoft 365.

Inicializar la aplicación cliente pública

Nota:

Para garantizar una autenticación correcta, inicialice TeamsJS antes de inicializar MSAL.

Inicialice MSAL y obtenga una instancia de la aplicación cliente pública para obtener tokens de acceso, cuando sea necesario.

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

const msalConfig = {
  auth: {
    clientId: "your_client_id",
    authority: "https://login.microsoftonline.com/{your_tenant_id}",
    supportsNestedAppAuth: true
  },
};

let pca: IPublicClientApplication;

export function initializePublicClient() {
  console.log("Starting initializePublicClient");
  return createNestablePublicClientApplication(msalConfig).then(
    (result) => {
      console.log("Client app created");
      pca = result;
      return pca;
    }
  );
}

Adquisición del primer token

Los tokens adquiridos por MSAL.js mediante la autenticación de aplicaciones anidadas se emiten para el identificador de registro de la aplicación Microsoft Entra. MSAL.js controla la adquisición de tokens para la autenticación de usuario. Intenta obtener un token de acceso de forma silenciosa. Si no se realiza correctamente, solicita al usuario su consentimiento. A continuación, el token se usa para llamar a microsoft Graph API u otros recursos protegidos Microsoft Entra ID. A diferencia del flujo de OBO, no es necesario autenticar previamente los hosts para llamar a los puntos de conexión.

Para adquirir un token, siga estos pasos:

  1. Usa MSAL.js para adquirir tokens para el identificador de la aplicación. Para obtener más información, consulte Adquisición y uso de un token de acceso.

  2. Use getActiveAccount la API para comprobar si hay una cuenta activa para llamar a publicClientApplication. Si no hay ninguna cuenta activa, intente recuperar una de la memoria caché con getAccount, mediante parámetros de filtro adicionales, como tenantID, homeAccountIdy loginHint desde la interfaz Context.

    Nota:

    La homeAccountId propiedad es equivalente a userObjectId en TeamsJS.

  3. Llame publicClientApplication.acquireTokenSilent(accessTokenRequest) a para adquirir el token de forma silenciosa sin interacción del usuario. accessTokenRequest especifica los ámbitos para los que se solicita el token de acceso. NAA admite el consentimiento incremental y dinámico. Asegúrese de solicitar siempre los ámbitos mínimos necesarios para que el código complete su tarea.

  4. Si no hay ninguna cuenta disponible, MSAL.js devuelve .InteractionRequiredAuthError Llame publicClientApplication.acquireTokenPopup(accessTokenRequest) a para mostrar un cuadro de diálogo interactivo para el usuario. acquireTokenSilent puede producir un error si el token expiró o si el usuario no accedía a todos los ámbitos solicitados.

El siguiente fragmento de código muestra un ejemplo para acceder a un token:


  // MSAL.js exposes several account APIs, logic to determine which account to use is the responsibility of the developer
  const account = publicClientApplication.getActiveAccount();

  const accessTokenRequest = {
  scopes: ["user.read"],
  account: account,
  };

  publicClientApplication
    .acquireTokenSilent(accessTokenRequest)
    .then(function (accessTokenResponse) {
      // Acquire token silent success
      let accessToken = accessTokenResponse.accessToken;
      // Call your API with token
      callApi(accessToken);
    })
    .catch(function (error) {
      //Acquire token silent failure, and send an interactive request
      if (error instanceof InteractionRequiredAuthError) {
        publicClientApplication
          .acquireTokenPopup(accessTokenRequest)
          .then(function (accessTokenResponse) {
            // Acquire token interactive success
            let accessToken = accessTokenResponse.accessToken;
            // Call your API with token
            callApi(accessToken);
          })
          .catch(function (error) {
            // Acquire token interactive failure
            console.log(error);
          });
      }
      console.log(error);
    });

Llamada a una API

Después de recibir el token, úselo para llamar a la API. Esto garantiza que se llama a la API con un token válido para realizar solicitudes autenticadas al servidor.

En el ejemplo siguiente se muestra cómo realizar una solicitud autenticada a Microsoft Graph API para acceder a los datos de Microsoft 365:


var headers = new Headers();
var bearer = "Bearer " + access_token;
headers.append("Authorization", bearer);
var options = {
    method: "GET",
    headers: headers
};

var graphEndpoint = "<https://graph.microsoft.com/v1.0/me>";

fetch(graphEndpoint, options)
    .then(function (response) {
        //do something with response
    });

Procedimientos recomendados

  • Use la autenticación silenciosa siempre que sea posible: MSAL.js proporciona el método , que controla la acquireTokenSilent renovación de tokens realizando solicitudes de token silenciosas sin preguntar al usuario. El método busca primero un token almacenado en caché válido en el almacenamiento del explorador. Si no encuentra una, la biblioteca realiza una solicitud silenciosa para Microsoft Entra ID y si hay una sesión de usuario activa (determinada por un conjunto de cookies en el explorador en el dominio Microsoft Entra), Microsoft Entra ID devuelve un token nuevo. La biblioteca no invoca automáticamente el acquireTokenSilent método . Se recomienda llamar a acquireTokenSilent en la aplicación antes de realizar una llamada API para obtener un token válido.

    En algunos casos, se produce un error al intentar obtener el token mediante el acquireTokenSilent método . Por ejemplo, cuando hay una sesión de usuario expirada con Microsoft Entra ID o un cambio de contraseña por parte del usuario de la aplicación, acquireTokenSilent se produce un error. Llame al método de token de adquisición interactivo (acquireTokenPopup).

  • Tener una reserva: los flujos NAA ofrecen compatibilidad en todo el ecosistema de Microsoft. Sin embargo, es posible que la aplicación aparezca en clientes de nivel inferior o heredados que no se actualicen para admitir NAA. En tales casos, la aplicación no puede admitir el inicio de sesión único de conexión directa y es posible que deba invocar API especiales para interactuar con el usuario para abrir diálogos de autenticación. Para obtener más información, consulte Habilitación del inicio de sesión único para la aplicación de pestaña.

    Nota:

    No debe usar NAA si usa un proveedor de identidades que no es Microsoft Entra, puede usar la autenticación emergente en su lugar.

  • Compatibilidad con NAA: es posible que NAA no se admita en todos los entornos de aplicaciones host. Para comprobar si el cliente actual admite esta característica, puede invocar la API especificada para determinar su estado. Un valor devuelto de true indica la compatibilidad con NAA, mientras que false sugiere que no se admite.

  • Probar la aplicación en varios entornos: si se espera que la aplicación funcione tanto en la vista web como en las implementaciones del explorador, se recomienda probar la aplicación en ambos entornos de implementación para asegurarse de que se comporta como espera. Es posible que algunas API que funcionan en el explorador no funcionen dentro de vistas web.

Ejemplo de código

Ejemplo de nombre Descripción .NET Node.js
Autenticación de aplicaciones anidadas En este ejemplo se muestra cómo crear un protocolo NAA para SPA incrustado en entornos host, como Teams, Outlook y Microsoft 365. View Ver

Consulte también