Autenticación de aplicaciones anidadas

Nota:

La autenticación de aplicaciones anidadas (NAA) solo se admite en aplicaciones de una sola página (SPA), como pestañas.

NAA es un nuevo protocolo de autenticación para SPA integrados 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 en aplicaciones host compatibles. 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 las 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 MSAL.js. No es necesario usar la función en la getAuthToken biblioteca de cliente JavaScript de Teams (TeamsJS).

  • Puede llamar a servicios como Microsoft Graph con un token de acceso del código de cliente como SPA. No hay necesidad de un servidor de nivel intermedio.

  • Puede usar el consentimiento incremental y dinámico para ámbitos (permisos).

  • No es necesario preautorizar a los hosts, como Teams o Microsoft 365, para que llamen 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 SSO de Entra de Teams tradicional NAA
    Exponer URI de redireccionamiento Obligatorio Obligatorio
    API de registro en Microsoft Entra ID Obligatorio
    Definir un ámbito personalizado en Microsoft Entra ID Obligatorio
    Autorizar aplicaciones cliente de Teams Obligatorio
    Revisar el manifiesto de la aplicación (anteriormente llamado manifiesto de la aplicación de Teams) Obligatorio Recomendado*
    Adquirir el 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 de OBO en el servidor Obligatorio

  • El administrador de TI podría bloquear la aplicación o dar su consentimiento solo para determinados permisos para la aplicación en Microsoft Entra ID. Para evitarlo, debe incluir el id. 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 SSO (y otros permisos) Tom, un nuevo miembro del equipo de diseño de Contoso, necesita usar la aplicación Contoso en las reuniones de Teams para colaborar en pizarras. Al usar por primera vez, 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 en todos los dispositivos.
Reautenticación o acceso condicional Autenticación escalonada Tom, cuando trabaja 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, guiándolo a través del proceso de MFA para seguir usando Contoso.
Errores Tom se enfrenta a un error de inicio de sesión con Contoso debido a un problema con la recuperación de la información de la cuenta. Tom encuentra un botón de reintento que solicita una nueva autenticación. Sin embargo, descubren que el administrador del sistema ha restringido el acceso a Contoso.

Configurar NAA

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

  1. Registra tu SPA
  2. Agregar agentes de confianza
  3. Inicializar aplicación cliente pública
  4. Adquiera su primer token
  5. Llamar a una API

Registra tu SPA

Debe crear un registro de aplicación de 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 la aplicación de Microsoft Entra. Si el complemento requiere el registro de aplicaciones adicional más allá de NAA y SSO, consulte registrar la aplicación de página única.

Agregar 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 a la Plataforma de identidad de Microsoft que los hosts admitidos pueden negociar la aplicación. El URI de redireccionamiento de la aplicación debe ser de tipo aplicación de página única y ajustarse al siguiente esquema:

brk-multihub://<your_domain>

Donde,

  • brk-multihub permite que la autenticación sea negociada por cualquier host compatible con Microsoft 365 que esté configurado para ejecutarse, como 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 debe incluir solo el origen y no sus rutas secundarias. 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 Ampliar las aplicaciones de Teams en Microsoft 365.

Inicializar 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 de 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;
    }
  );
}

Adquiera su primer token

Los tokens adquiridos por MSAL.js a través de 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 del usuario. Intenta obtener un token de acceso de forma silenciosa. Si no se realiza correctamente, solicita el consentimiento del usuario. A continuación, el token se usa para llamar a la API de Microsoft Graph API u otros recursos protegidos con Microsoft Entra ID. A diferencia del flujo OBO, no es necesario autorizar previamente a los hosts para que llamen a los puntos de conexión.

Para adquirir un token, siga estos pasos:

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

  2. Use getActiveAccount la publicClientApplicationAPI para comprobar si hay una cuenta activa para llamar al archivo Si no hay ninguna cuenta activa, intente recuperar una de la caché con getAccount, mediante parámetros de filtro adicionales, como tenantID, homeAccountId, y loginHint desde la interfaz contextual.

    Nota:

    La homeAccountId propiedad es equivalente a userObjectId en TeamsJS.

  3. para publicClientApplication.acquireTokenSilent(accessTokenRequest) 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 un InteractionRequiredAuthErrorarchivo . Llamada publicClientApplication.acquireTokenPopup(accessTokenRequest) para mostrar un cuadro de diálogo interactivo para el usuario. acquireTokenSilent Se puede producir un error si el token expiró o si el usuario no dio su consentimiento para todos los ámbitos solicitados.

    En el siguiente fragmento de código, se 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);
    });

Llamar 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 la API de Microsoft Graph 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
    });

Captura previa de tokens para la autenticación de aplicaciones anidadas (NAA)

Para mejorar el rendimiento y reducir la latencia de autenticación, la autenticación de aplicaciones anidadas (NAA) admite la captura previa de tokens. Esta característica permite al host adquirir tokens de autenticación de forma proactiva antes de iniciar la aplicación, lo que permite un acceso más rápido a los recursos protegidos.

Cómo habilitar la precarga de tokens

Para habilitar la captura previa de tokens, actualice el manifiesto de la aplicación de Teams a la versión 1.22 o posterior e incluya la nestedAppAuthInfo sección dentro webApplicationInfode .

{
 "webApplicationInfo": {
   "id": "33333ddd-0000-0000-0000-88888757bbbb",
   "resource": "api://app.com/botid-33333ddd-0000-0000-0000-88888757bbbb",
   "nestedAppAuthInfo": [
     {
       "redirectUri": "brk-multihub://app.com",
       "scopes": ["openid", "profile", "offline_access"],
       "claims": "{\"access_token\":{\"xms_cc\":{\"values\":[\"CP1\"]}}}"
     }
   ]
 }
}

Importante

  • Para cada solicitud de precaptura del token de NAA, especifique el identificador de cliente de registro de Microsoft Entra ID del agente o la aplicación en el campo opcional clientId de la entrada correspondientenestedAppAuthInfo. Cuando se proporciona, este valor se usa para capturar previamente el token de esa entrada. Si una entrada no incluye clientId, el host lo utiliza webApplicationInfo.id como identificador de cliente para la solicitud de precaptura del token NAA de esa entrada.
  • webApplicationInfo.id es el id. de cliente de reserva para las entradas que no especifican clientId. No es necesario que coincida con todos los clientId de nivel de entrada. Si una aplicación usa solo webApplicationInfo.id para la captura previa del token NAA, ese valor debe coincidir con el id. de cliente del registro de Microsoft Entra ID de la aplicación que se usa para sus solicitudes de token NAA reales.
  • Los valores y webApplicationInfo.id todos los campos incluidos nestedAppAuthInfo deben coincidir exactamente con los parámetros usados en la solicitud de token NAA en tiempo de ejecución de la aplicación. Cualquier disparidad, como diferencias en ámbitos, URI de redireccionamiento o notificaciones, impedirá que el host sirva el token desde la caché.
  • Los tokens capturados previamente se almacenan en la memoria durante un breve período de tiempo y están diseñados para usarse solo durante la carga inicial de la aplicación. Si la aplicación intenta capturar un token más tarde, como en respuesta a una acción de usuario, es posible que el token capturado previamente ya no esté disponible. En tales casos, la aplicación debe iniciar una nueva solicitud de token mediante flujos de autenticación estándar.

Cómo funciona

Cuando se habilita la captura previa de tokens, el entorno host intenta adquirir y almacenar en caché los tokens necesarios antes de que se represente la aplicación. Estos tokens se almacenan en la memoria y están disponibles para la aplicación inmediatamente después de iniciarla.

Este comportamiento es similar a la capacidad de captura previa en el modelo de SSO de Teams heredado, donde la API se desencadenaba automáticamente durante la carga de la getAuthToken pestaña. Con la autenticación de aplicaciones anidadas (NAA), esta funcionalidad se introduce a través de la configuración de manifiestos, lo que mejora el rendimiento sin necesidad de un intercambio de tokens de back-end.

Ventajas de la precarga de tokens en NAA

  • Mejorar el rendimiento mediante la reducción de los retrasos en la autenticación durante el inicio de la aplicación
  • Habilitar el inicio de sesión único (SSO) en aplicaciones anidadas sin inicios de sesión repetidos

Nota:

Actualmente, la captura previa de tokens solo se admite en los clientes web y de escritorio de Microsoft Teams.

Procedimientos recomendados

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

    En algunos casos, se produce un error en el intento de 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).

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

    Nota:

    No debe usar NAA si usa un proveedor de identidad que no sea de 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 indica true compatibilidad con NAA, mientras false que sugiere que no lo es.

  • Prueba tu aplicación en varios entornos: si se espera que tu aplicación funcione en implementaciones tanto de vista web como de navegador, te recomendamos probar tu aplicación en ambos entornos de implementación para asegurarte de que se comporta según lo esperado. Es posible que algunas API que funcionan en el explorador no funcionen en vistas web.

Ejemplo de código

Ejemplo de nombre Descripción .NET Node.js
Autenticación de aplicaciones anidadas En este ejemplo se muestra el inicio de sesión único (SSO) de Microsoft Entra en una pestaña de Microsoft Teams, utilizando el flujo En nombre de (OBO) para llamar a Microsoft Graph API en nombre del usuario. View Ver

Consulte también

  • Last updated on