Información general sobre autenticación y autorización en los complementos de Office

  • Artículo

Los complementos de Office permiten el acceso anónimo de forma predeterminada, pero se puede requerir que los usuarios inicien sesión para usar el complemento con una cuenta de Microsoft, una cuenta Microsoft 365 Educación, una cuenta profesional u otra cuenta común. Esta tarea se denomina autenticación de usuario porque indica al complemento quién es el usuario.

El complemento también puede obtener el consentimiento del usuario para acceder a sus datos de Microsoft Graph (como su perfil de Microsoft 365, archivos de OneDrive y datos de SharePoint) o datos en otros orígenes externos como Google, Facebook, LinkedIn, SalesForce y GitHub. Esta tarea se denomina autorización de complemento (o aplicación), porque es el complemento que se está autorizando, no el usuario.

Recursos clave para la autenticación y la autorización

En esta documentación se explica cómo compilar y configurar complementos de Office para implementar correctamente la autenticación y la autorización. Sin embargo, muchos de los conceptos y las tecnologías de seguridad mencionados están fuera del ámbito de esta documentación. Por ejemplo, los conceptos de seguridad generales, como los flujos de OAuth, el almacenamiento en caché de tokens o la administración de identidades no se explican aquí. Esta documentación tampoco documenta nada específico de Microsoft Azure ni del Plataforma de identidad de Microsoft. Le recomendamos que consulte los siguientes recursos si necesita más información en esas áreas.

Escenarios del SSO

El uso del inicio de sesión único (SSO) es conveniente para el usuario, ya que solo se tiene que iniciar sesión una vez en Office. No es necesario que inicien sesión por separado en el complemento. El inicio de sesión único no se admite en todas las versiones de Office, por lo que deberá implementar un enfoque de inicio de sesión alternativo mediante el Plataforma de identidad de Microsoft. Para obtener más información sobre las versiones de Office admitidas, consulte Conjunto de requisitos de la API de identidad

Obtención de la identidad de usuario a través del SSO

A menudo, el complemento solo necesita la identidad de usuario. Por ejemplo, puede que solo desee personalizar el complemento y mostrar el nombre de usuario en el panel de tareas. O puede que desee un id. único para asociar al usuario con sus datos en la base de datos. Para ello, solo tiene que obtener el token de acceso para el usuario de Office.

Para obtener la identidad del usuario mediante SSO, llame al método getAccessToken. El método devuelve un token de acceso que también es un token de identidad que contiene varias notificaciones que son únicas para el usuario que ha iniciado sesión en ese momento, incluido preferred_username, name, sub y oid. Para obtener más información sobre estas propiedades, consulte Tokens de identificación de la Plataforma de identidad de Microsoft. Para obtener un ejemplo del token devuelto por getAccessToken, consulte Ejemplo de token de acceso.

Si el usuario no ha iniciado sesión, Office abrirá un cuadro de diálogo y usará el Plataforma de identidad de Microsoft para solicitar al usuario que inicie sesión. A continuación, el método devolverá un token de acceso o dará un error si no puede iniciar sesión en el usuario.

En un escenario en el que necesite almacenar datos para el usuario, consulte Tokens de identificación de la Plataforma de identidad de Microsoft para obtener información sobre cómo obtener un valor con el token para identificar de forma única al usuario. Use ese valor para buscar al usuario en una tabla de usuarios o base de datos de usuarios que usted tenga. Use la base de datos para almacenar información relativa al usuario, como las preferencias del usuario o el estado de la cuenta del usuario. Dado que usa el inicio de sesión único, los usuarios no inician sesión por separado en el complemento, por lo que no es necesario almacenar una contraseña para el usuario.

Antes de empezar a implementar la autenticación de usuario con sso, asegúrese de que está familiarizado con el artículo Habilitación del inicio de sesión único para complementos de Office.

Acceder a las API web a través del SSO

Si el complemento tiene API del lado servidor que requieren un usuario autorizado, llame al método getAccessToken para obtener un token de acceso. El token de acceso proporciona acceso a su propio servidor web (configurado mediante un registro de aplicaciones de Microsoft Azure). Al llamar a las API en el servidor web, también pasa el token de acceso para autorizar al usuario.

El código siguiente indica cómo se construye una solicitud HTTPS GET a la API del servidor web del complemento para obtener algunos datos. El código se ejecuta en el lado cliente, como en un panel de tareas. Primero obtiene el token de acceso llamando a getAccessToken. A continuación, crea una llamada AJAX con el encabezado de autorización y la dirección URL correctos para la API del servidor.

function getOneDriveFileNames() {

    let accessToken = await Office.auth.getAccessToken();

    $.ajax({
        url: "/api/data",
        headers: { "Authorization": "Bearer " + accessToken },
        type: "GET"
    })
        .done(function (result) {
            //... work with data from the result...
        });
}

En el código siguiente se muestra de ejemplo un controlador /api/data para la llamada REST del ejemplo de código anterior. El código es el código ASP.NET que se ejecuta en un servidor web. El [Authorize] atributo requerirá que se pase un token de acceso válido desde el cliente o devolverá un error al cliente.

    [Authorize]
    // GET api/data
    public async Task<HttpResponseMessage> Get()
    {
        //... obtain and return data to the client-side code...
    }

Acceder a Microsoft Graph mediante SSO

En algunos escenarios, no solo necesita la identidad del usuario, sino que también tiene que acceder a los recursos de Microsoft Graph en nombre del usuario. Por ejemplo, puede que necesite enviar un correo electrónico o crear un chat en Teams en nombre del usuario. Estas acciones y mucho más se pueden realizar a través de Microsoft Graph. Tendrá que seguir estos pasos:

  1. Obtenga el token de acceso para el usuario actual mediante SSO llamando a getAccessToken. Si el usuario no ha iniciado sesión, Office abrirá un cuadro de diálogo e iniciará sesión con el Plataforma de identidad de Microsoft. Cuando el usuario inicie sesión, o si ya lo ha hecho, el método devolverá un token de acceso.
  2. Pase el token de acceso al código del lado servidor.
  3. En el lado servidor, use el flujo con derechos delegados OAuth 2.0 para cambiar el token de acceso por un nuevo token de acceso que contenga la identidad del usuario delegado y los permisos necesarios para llamar a Microsoft Graph.

Nota:

Para obtener la mejor seguridad con el fin de evitar la pérdida del token de acceso, lleve a cabo siempre el flujo con derechos delegados en el lado servidor. Llame a las API de Microsoft Graph desde el servidor, no desde el cliente. No devuelva el token de acceso al código del lado cliente.

Antes de empezar a implementar el inicio de sesión único para acceder a Microsoft Graph en el complemento, asegúrese de que está familiarizado con los artículos siguientes.

También debe leer al menos uno de los siguientes artículos que le guiarán a través de la creación de un complemento de Office para usar el inicio de sesión único y acceder a Microsoft Graph. Incluso si no lleva a cabo los pasos, estos contienen información valiosa sobre cómo se implementan el SSO y el flujo con derechos delegados.

Escenarios sin SSO

En algunos escenarios, es posible que no quiera usar el inicio de sesión único. Por ejemplo, puede que tenga que autenticarse con un proveedor de identidades diferente al de la Plataforma de identidad de Microsoft. Además, el inicio de sesión único no se admite en todos los escenarios. Por ejemplo, las versiones anteriores de Office no admiten SSO. En este caso, tendría que recurrir a un sistema de autenticación alternativo para el complemento.

Autenticar con la Plataforma de identidad de Microsoft

El complemento puede iniciar la sesión de los usuarios mediante la Plataforma de identidad de Microsoft como proveedor de autenticación. Una vez que haya iniciado sesión en el usuario, puede usar el Plataforma de identidad de Microsoft para autorizar el complemento a Microsoft Graph u otros servicios administrados por Microsoft. Use este enfoque como método de inicio de sesión alternativo cuando el SSO a través de Office no esté disponible. Además, hay escenarios en los que desea que los usuarios inicien sesión en el complemento por separado, incluso cuando esté disponible el inicio de sesión único; por ejemplo, si desea que tengan la opción de iniciar sesión en el complemento con un identificador diferente al que ha iniciado sesión actualmente en Office.

Es importante tener en cuenta que el Plataforma de identidad de Microsoft no permite que su página de inicio de sesión se abra en un iframe. Cuando un complemento de Office se ejecuta en Office en la Web, el panel de tareas es un iframe. Esto quiere decir que tendrá que abrir la página de inicio de sesión mediante un cuadro de diálogo abierto con la API de cuadros de diálogo de Office. Esto afecta al uso de las bibliotecas de asistentes de autenticación. Para obtener más información, vea Autenticación con la API de cuadros de diálogo de Office.

Para obtener información sobre cómo implementar la autenticación con la Plataforma de identidad de Microsoft, consulte Introducción a la Plataforma de identidad de Microsoft (v2.0). La documentación contiene muchos tutoriales y guías, así como vínculos a bibliotecas y ejemplos relevantes. Como se explica en Autenticación con la API de cuadros de diálogo de Office, es posible que tenga que cambiar algunas partes del código de los ejemplos para que funcionen en el cuadro de diálogo de Office.

Acceder a Microsoft Graph sin SSO

Puede obtener autorización a los datos de Microsoft Graph para el complemento mediante la obtención de un token de acceso para Microsoft Graph desde la Plataforma de identidad de Microsoft. Puede hacerlo sin depender del inicio de sesión único a través de Office (o si se produjo un error en el inicio de sesión único o no se admite). Para más información sobre cómo hacerlo, consulte Acceso a Microsoft Graph sin SSO, que contiene más información y vínculos a ejemplos.

Acceso a orígenes de datos que no son de Microsoft

Los servicios en línea más populares, como Google, Facebook, LinkedIn, SalesForce y GitHub, permiten a los desarrolladores proporcionar a los usuarios acceso a sus cuentas en otras aplicaciones. Esto le abre la posibilidad de incluir estos servicios en su complemento de Office. Vaya a Autorizar servicios externos en un complemento de Office para ver las distintas maneras en las que su complemento puede llevar esto acabo.

Importante

Antes de empezar a codificar, averigüe si el origen de datos permite que su página de inicio de sesión se abra en un iframe. Cuando un complemento de Office se ejecuta en Office en la Web, el panel de tareas es un iframe. Si el origen de datos no permite que su página de inicio de sesión se abra en un iframe, deberá abrir la página de inicio de sesión en un cuadro de diálogo abierto con la API de diálogo de Office. Para obtener más información, vea Autenticación con la API de cuadros de diálogo de Office.

Recursos adicionales