Configuración de la autenticación de IdP de OAuth de terceros

  • Artículo

Nota:

Para que la autenticación funcione para la pestaña en clientes móviles, asegúrese de que usa la versión 1.4.1 o posterior de la biblioteca cliente javascript de Microsoft Teams (TeamsJS).

Es posible que la aplicación de Microsoft Teams necesite interactuar con varios servicios, como Facebook, Twitter y Teams. La mayoría de estos servicios requieren autenticación y autorización para el acceso. Teams almacena la información del perfil de usuario en Microsoft Entra id. mediante Microsoft Graph. Este artículo se centra principalmente en el uso de Microsoft Entra id. para la autenticación para acceder a esta información.

OAuth 2.0, un estándar abierto para la autenticación, es utilizado por Microsoft Entra id. y muchos otros proveedores de servicios. La comprensión de OAuth 2.0 es esencial al tratar con la autenticación en Teams y el identificador de Microsoft Entra. Los ejemplos proporcionados emplean el flujo de concesión implícita de OAuth 2.0, que recupera la información de perfil del usuario de Microsoft Entra id. y Microsoft Graph.

El código del artículo procede de la aplicación de ejemplo de Teams Ejemplo de autenticación de Microsoft Teams (Nodo). Contiene una pestaña estática que solicita un token de acceso para Microsoft Graph y muestra la información básica del perfil del usuario actual del identificador de Microsoft Entra.

Para obtener información general sobre el flujo de autenticación de las pestañas, consulte Flujo de autenticación en pestañas.

El flujo de autenticación en pestañas difiere del flujo de autenticación en los bots.

Nota:

En este tema se refleja la versión 2.0.x de la biblioteca cliente JavaScript de Microsoft Teams (TeamsJS). Si usa una versión anterior, consulte la introducción a la biblioteca TeamsJS para obtener instrucciones sobre las diferencias entre la versión más reciente de TeamsJS y las versiones anteriores.

Configuración de la aplicación para usar Microsoft Entra id. como proveedor de identidades

Los proveedores de identidades compatibles con OAuth 2.0 no autentican solicitudes de aplicaciones no registradas. Por lo tanto, es esencial registrar las aplicaciones de antemano. Para registrar una aplicación con Microsoft Entra identificador, siga estos pasos:

  1. Abra el Portal de registro de aplicaciones.

  2. Seleccione la aplicación para ver sus propiedades o seleccione el botón "Nuevo registro". Busque la sección URI de redirección de la aplicación.

  3. Seleccione Web en el menú desplegable y actualice la dirección URL al punto de conexión de autenticación. En las aplicaciones de ejemplo TypeScript/Node.js y C# disponibles en GitHub, las direcciones URL de redireccionamiento siguen un patrón similar:

    URL de redireccionamientohttps://<hostname>/bot-auth/simple-start

Reemplace por <hostname> el host real. Este host puede ser un sitio de hospedaje dedicado, como Azure, Glitch o un túnel ngrok a localhost en la máquina de desarrollo, como abcd1234.ngrok.io. Si no tiene esta información, asegúrese de que ha completado o hospedado la aplicación (o la aplicación de ejemplo). Reanude este proceso cuando tenga esta información.

Nota:

Puede elegir cualquier proveedor de OAuth de terceros, como LinkedIn, Google y otros. El proceso para habilitar la autenticación para estos proveedores es similar al uso de Microsoft Entra id. como proveedor de OAuth de terceros. Para obtener más información sobre el uso de cualquier proveedor de OAuth de terceros, visite el sitio web del proveedor en particular.

Iniciar el flujo de autenticación

Nota:

Si está habilitada la creación de particiones de almacenamiento experimental de terceros , se produce un error en la autenticación de terceros. La aplicación solicita autenticación repetidamente, ya que los valores no se almacenan localmente.

Desencadene el flujo de autenticación mediante una acción del usuario. Evite abrir el elemento emergente de autenticación automáticamente, ya que es probable que desencadene el bloqueador emergente del explorador y confunda al usuario.

Agregue un botón a la página de configuración o contenido para permitir que el usuario inicie sesión cuando sea necesario. Esto se puede hacer en la página de configuración de la pestaña o en cualquier página de contenido.

Microsoft Entra identificador, al igual que la mayoría de los proveedores de identidades, no permite que su contenido se coloque en .iframe Esto significa que tendrá que agregar una página emergente para hospedar el proveedor de identidades. En el ejemplo siguiente, esta página es /tab-auth/simple-start. Use la authentication.authenticate() función de la biblioteca TeamsJS para iniciar esta página cuando se seleccione el botón.

import { authentication } from "@microsoft/teams-js";
authentication.authenticate({
    url: window.location.origin + "/tab/simple-start-v2",
    width: 600,
    height: 535})
.then((result) => {
    console.log("Login succeeded: " + result);
    let data = localStorage.getItem(result);
    localStorage.removeItem(result);
    let tokenResult = JSON.parse(data);
    showIdTokenAndClaims(tokenResult.idToken);
    getUserProfile(tokenResult.accessToken);
})
.catch((reason) => {
    console.log("Login failed: " + reason);
    handleAuthError(reason);
});

Notas

  • La dirección URL a la que se pasa authenticate() es la página de inicio del flujo de autenticación. En este ejemplo que es /tab-auth/simple-start. Esto debe coincidir con lo que registró en el portal de registro de aplicaciones de Microsoft Entra.

  • El flujo de autenticación debe iniciarse en una página que esté en el dominio. Este dominio también debe aparecer en la sección validDomains del manifiesto. Si no lo hace, se producirá un elemento emergente vacío.

  • Si no puede usar authenticate(), es posible que el elemento emergente no se cierre al final del proceso de inicio de sesión, lo que provocará un problema.

Vaya a la página de autorización desde la página emergente.

Cuando se muestra la página emergente (/tab-auth/simple-start) se ejecuta el código siguiente. El objetivo principal de la página es redirigir al proveedor de identidades para que el usuario pueda iniciar sesión. Este redireccionamiento se puede realizar en el lado servidor mediante HTTP 302, pero en este caso se realiza en el lado cliente mediante una llamada a window.location.assign(). Esto también permite app.getContext() usarse para recuperar información de sugerencias, que se puede pasar a Microsoft Entra identificador.

app.getContext().then((context) => {
    // Generate random state string and store it, so we can verify it in the callback
    let state = _guid(); // _guid() is a helper function in the sample
    localStorage.setItem("simple.state", state);
    localStorage.removeItem("simple.error");

    // Go to the Azure AD authorization endpoint
    let queryParams = {
        client_id: "{{appId}}",
        response_type: "id_token token",
        response_mode: "fragment",
        scope: "https://graph.microsoft.com/User.Read openid",
        redirect_uri: window.location.origin + "/tab/simple-end",
        nonce: _guid(),
        state: state,
        // The context object is populated by Teams; the loginHint attribute
        // is used as hinting information
        login_hint: context.user.loginHint,
    };

    let authorizeEndpoint = `https://login.microsoftonline.com/${context.user.tenant.id}/oauth2/v2.0/authorize?${toQueryString(queryParams)}`;
    window.location.assign(authorizeEndpoint);
});

Una vez que el usuario completa la autorización, se redirige al usuario a la página de devolución de llamada que especificó para la aplicación en /tab-auth/simple-end.

Notas

  • Consulte Obtención de información de contexto de usuario para obtener ayuda para crear solicitudes de autenticación y direcciones URL. Por ejemplo, puede usar el nombre de inicio de sesión del usuario como login_hint valor para Microsoft Entra inicio de sesión, lo que significa que es posible que el usuario tenga que escribir menos. Recuerde que no debe usar este contexto directamente como prueba de identidad, ya que un atacante podría cargar la página en un explorador malintencionado y proporcionarle toda la información que desee.
  • Aunque el contexto de pestaña proporciona información útil sobre el usuario, no use esta información para autenticar al usuario, ya sea como parámetros de dirección URL en la dirección URL del contenido de la pestaña o llamando a la función en la app.getContext() biblioteca cliente javaScript de Microsoft Teams (TeamsJS). Un actor malintencionado podría invocar la dirección URL de contenido de la pestaña con sus propios parámetros y una página web que suplanta Microsoft Teams podría cargar la dirección URL de contenido de la pestaña en un iframe y devolver sus propios datos a la función getContext(). Debe tratar la información relacionada con la identidad en el contexto de tabulación simplemente como sugerencias y validarla antes de usarla.
  • El parámetro state se usa para confirmar que el servicio que llama al URI de devolución de llamada es el servicio al que llamó. Si el state parámetro de la devolución de llamada no coincide con el parámetro que envió durante la llamada, la llamada de devolución no se comprueba y debe finalizarse.
  • No es necesario incluir el dominio del proveedor de identidades en la validDomains lista en el archivo manifest.json de la aplicación.

Página de devolución de llamada

En la última sección, llamó al servicio de autorización de Microsoft Entra y pasó información de usuario y aplicación para que Microsoft Entra identificador pudiera presentar al usuario su propia experiencia de autorización monolítica. La aplicación no tiene control sobre lo que sucede en esta experiencia. Todo lo que sabe es lo que se devuelve cuando Microsoft Entra id. llama a la página de devolución de llamada que proporcionó (/tab-auth/simple-end).

En esta página, debe determinar si se ha realizado correctamente o no en función de la información devuelta por Microsoft Entra id. y llamar a authentication.notifySuccess() o authentication.notifyFailure(). Si el inicio de sesión se realizó correctamente, tendrá acceso a los recursos del servicio.

// Split the key-value pairs passed from Azure AD
// getHashParameters is a helper function that parses the arguments sent
// to the callback URL by Azure AD after the authorization call
let hashParams = getHashParameters();
if (hashParams["error"]) {
    // Authentication/authorization failed
    localStorage.setItem("simple.error", JSON.stringify(hashParams));
} else if (hashParams["access_token"]) {
    // Get the stored state parameter and compare with incoming state
    let expectedState = localStorage.getItem("simple.state");
    if (expectedState !== hashParams["state"]) {
        // State does not match, report error
        localStorage.setItem("simple.error", JSON.stringify(hashParams));
        authentication.notifyFailure("StateDoesNotMatch");
    } else {
        // Success -- return token information to the parent page.
        // Use localStorage to avoid passing the token via notifySuccess; instead we send the item key.
        let key = "simple.result";
        localStorage.setItem(key, JSON.stringify({
            idToken: hashParams["id_token"],
            accessToken: hashParams["access_token"],
            tokenType: hashParams["token_type"],
            expiresIn: hashParams["expires_in"]
        }));
        authentication.notifySuccess(key);
    }
} else {
    // Unexpected condition: hash does not contain error or access_token parameter
    localStorage.setItem("simple.error", JSON.stringify(hashParams));
    authentication.notifyFailure("UnexpectedFailure");
}

Este código analiza los pares clave-valor recibidos de Microsoft Entra id. en window.location.hash el uso de la getHashParameters() función auxiliar. Si encuentra un access_token y el valor state es el mismo que el proporcionado al principio del flujo de autenticación, devuelve el token de acceso a la pestaña llamando a notifySuccess(); de lo contrario, notifica un error con notifyFailure().

Notas

NotifyFailure() tiene los siguientes motivos de error predefinidos:

  • CancelledByUser el usuario cerró la ventana emergente antes de completar el flujo de autenticación.

    Nota:

    Se recomienda no usar same-origin ni valores para Cross-Origin-Opener-Policy el encabezado de respuesta en las páginas de inicio de sesión, ya que interrumpe la conexión a la ventana primaria y hace que la llamada a la API de autenticación devuelva prematuramente un CancelledByUsersame-origin-allow-popups error.

  • FailedToOpenWindow no se pudo abrir la ventana emergente. Cuando Microsoft Teams se ejecuta en un explorador, este error indica que la ventana fue bloqueada por el bloqueador de elementos emergentes del explorador.

Si se ejecuta correctamente, puede actualizar o volver a cargar la página y mostrar contenido relevante para el usuario ahora autenticado. Si se produce un error en la autenticación, muestra un mensaje de error.

La aplicación puede establecer su propia cookie de sesión para que el usuario no tenga que volver a iniciar sesión cuando vuelva a la pestaña del dispositivo actual.

Nota:

  • Chrome 80, programado para lanzarse a principios de 2020, presenta nuevos valores de cookies e impone directivas de cookies de forma predeterminada. Se recomienda establecer el uso previsto para las cookies en lugar de basarse en el comportamiento predeterminado del explorador. ConsulteAtributo de cookie SameSite (actualización de 2020).
  • Para obtener el token adecuado para los usuarios invitados y gratuitos de Microsoft Teams, asegúrese de que las aplicaciones usan el punto de conexión https://login.microsoftonline.com/**{tenantId}**específico del inquilino. Puede adquirir el valor tenantId del mensaje del bot o del contexto de la pestaña. Si las aplicaciones usan https://login.microsoftonline.com/common, es posible que los usuarios reciban tokens incorrectos, lo que hace que inicien sesión en el inquilino "principal" en lugar del inquilino en el que han iniciado sesión actualmente.

Para obtener más información sobre el inicio de sesión único (SSO), consulte el artículo Autenticación silenciosa.

Ejemplo de código

Código de ejemplo que muestra el proceso de autenticación de tabulación mediante el identificador de Microsoft Entra:

Ejemplo de nombre Descripción .NET Node.js Manifiesto
Inicio de sesión único de pestaña Esta aplicación de ejemplo muestra Microsoft Entra inicio de sesión único para las pestañas de Teams. View Ver,
Kit de herramientas de Teams		 ND
Inicio de sesión único de tab, bot y extensión de mensaje (ME) En este ejemplo se muestra el inicio de sesión único para Tab, Bot y ME- search, action, link unfurl. View View Ver

Consulte también