Flujo de OAuth de tokens de contexto para complementos de SharePoint
En SharePoint, el flujo de autorización y autenticación OAuth para un complemento de baja confianza hospedado por el proveedor implica una serie de interacciones entre el complemento, SharePoint, el servidor de autorización y el explorador en el tiempo de ejecución. El servidor de autorización en este escenario es Microsoft Azure Access Control Service (ACS).
Importante
Azure Access Control (ACS), un servicio de Azure Active Directory (Azure AD), se retirará el 7 de noviembre de 2018. La retirada de este producto no afecta al modelo de complemento de SharePoint, que usa el nombre de host https://accounts.accesscontrol.windows.net (que no est? afectado por esta retirada). Para obtener más información, vea Impacto de la retirada de Azure Access Control para Complementos de SharePoint.
Con un complemento hospedado por el proveedor, tiene una aplicación web remota o un servicio web remoto independientes de SharePoint, que no forman parte de la granja de SharePoint ni del espacio empresarial de SharePoint Online. Puede estar hospedado en la nube o en un servidor local. En este artículo, el componente remoto se denomina Contoso.com.
Nota:
El componente remoto puede hospedar también receptores de eventos que responden a los eventos que se produzcan en elementos de SharePoint, como listas o elementos de lista. Los ejemplos de eventos remotos que Contoso.com podría querer responder son eventos de lista, como agregar o quitar un elemento de lista, o eventos web, como agregar o eliminar un sitio. Para obtener más información sobre cómo crear receptores de eventos remotos, vea Crear un receptor de eventos remotos en complementos de SharePoint.
Contoso.com utiliza el modelo de objetos de cliente (CSOM) de SharePoint o las API REST de SharePoint para realizar llamadas a SharePoint. La aplicación de Contoso.com usa un flujo de transmisión de tokens de OAuth para autenticarse con SharePoint. SharePoint y Contoso.com no confían entre sí; pero ambos confían en ACS y aceptarán los tokens emitidos por ACS.
Intervienen tres tokens: SharePoint hace que ACS cree un token de contexto que SharePoint reenvía a Contoso.com. Contoso.com valida que ACS emitió el token de contexto porque confía en él. Después, Contoso.com extrae un token de actualización del token de contexto y lo usa para obtener un token de acceso directamente desde ACS. Incluye el token de acceso en todas las solicitudes a SharePoint. SharePoint valida que ACS emitió el token de acceso, por lo que responde a las solicitudes de Contoso.com.
El código de administración de tokens se proporciona en el componente remoto (pero si el componente remoto está hospedado en .NET, Microsoft Office Developer Tools para Visual Studio proporciona código de ejemplo que realiza automáticamente la mayor parte del trabajo). Para obtener más información sobre el código de control de tokens, vea Controlar tokens de seguridad en los complementos de SharePoint de baja confianza hospedados por el proveedor.
Requisitos previos
Hay que completar los pasos preliminares siguientes para que un complemento de SharePoint pueda usar el flujo de tokens de contexto.
Los siguientes requisitos solo se aplican si instala el complemento de SharePoint local además de SharePoint Online. Sin embargo, no se aplican si solo instala el complemento de SharePoint en SharePoint Online.
- Es necesario que la granja de servidores esté configurada para admitir complementos. Se trata en realidad de un requisito de instalación de los complementos de SharePoint en la granja, aunque no usen el flujo de tokens de contexto. Para obtener más información, vea Herramientas y entornos para desarrollar complementos de SharePoint
- El cliente que instala el complemento debe tener una cuenta de Office 365. Se necesita para tener acceso a ACS. El cliente no tiene que usar su cuenta con otros fines.
- La granja de servidores debe configurarse para compartir la relación de confianza que Office 365 tiene con ACS. Esto se realiza fácilmente con los scripts de Windows PowerShell. Para obtener más información, vea Usar un sitio de Office 365 SharePoint para autorizar complementos hospedados por el proveedor en un sitio de SharePoint local.
Independientemente de que el complemento se instale en SharePoint Online o en una granja de SharePoint local, el complemento de SharePoint debe registrarse con ACS. Para obtener más información sobre cómo puede hacerse, vea Registrar complementos de SharePoint. Entre otras cosas, el complemento proporciona a ACS el identificador de cliente y el secreto de cliente como parte del registro.
Flujo de tokens de contexto
En la ilustración siguiente se muestra el flujo de autorización y autenticación OAuth para un complemento de SharePoint hospedado por el proveedor.
Flujo de tokens de contexto de OAuth
Estos son los pasos que corresponden a los números de la figura:
Un usuario inicia la Complemento de SharePoint desde SharePoint. El diseño del complemento determina cómo se hace:
- Si el complemento se ha diseñado para exponer la aplicación web remota (en Contoso.com) en un elemento de complemento (que es básicamente un contenedor alrededor de un IFRAME), el inicio del complemento simplemente implica navegar a una página de SharePoint que contiene el elemento de complemento. (Si el usuario no ha iniciado sesión todavía, SharePoint pide al usuario que inicie sesión). SharePoint procesa la página y detecta que hay un componente de la aplicación de Contoso.com en ella. Para obtener más información sobre los elementos de complemento, vea Crear elementos de complemento para instalarlos con el complemento de SharePoint.
- Si el complemento se ha diseñado para usarse como página completa en el explorador, el usuario selecciona el icono del complemento en la página Contenidos del sitio del sitio web de SharePoint para iniciarlo. (Una variante de esto se produce cuando en el complemento incluye un menú personalizado o un elemento de cinta que inicia el componente remoto).
Independientemente de cómo se inicie el complemento, SharePoint debe obtener un token de contexto que pueda enviar a la aplicación de Contoso.com, por lo que pide a ACS que cree un token de contexto con información sobre el contexto de SharePoint, incluido el usuario actual, la dirección URL de la aplicación remota y otra información. El token de contexto contiene también un token de actualización cifrado.
ACS firma el token de contexto con un algoritmo que usa el secreto del complemento de Contoso.com y lo devuelve a SharePoint. Solo ACS y el complemento de Contoso.com saben el secreto.
Si la aplicación de Contoso.com se exponga en un elemento de complemento, SharePoint representa la página que hospeda el elemento de complemento y agrega el token de contexto a la dirección URL a la que el IFRAME del complemento llama para obtener su contenido. Si la aplicación de Contoso.com es una página completa, SharePoint redirige el explorador a Contoso.com e incluye el token de contexto como parte de la respuesta de redireccionamiento.
El token de contexto se incluye en la solicitud del explorador que se envía al servidor de Contoso.com.
El servidor de Contoso.com obtiene el token de contexto y valida la firma, lo que puede hacer porque conoce el secreto de cliente. Esto asegura a Contoso.com que el token fue emitido por ACS y no se trata de un impostor que pretende pasar por SharePoint. Contoso.com extrae el token de actualización del token de contexto y lo envía, junto con otra información, como el identificador de cliente y el secreto de cliente, a ACS en una solicitud de un token de acceso que le permita tener acceso a SharePoint.
ACS valida el token de actualización para que quede claro que emitió el token y luego devuelve un token de acceso a Contoso.com. Contoso.com también puede almacenar este token de acceso en caché para no tener que pedir a ACS un token de acceso cada vez que acceda a SharePoint. De forma predeterminada, los tokens de acceso son válidos durante unas horas cada vez. (En el momento de redactarse este artículo, los tokens de acceso emitidos por ACS para SharePoint tenían una expiración predeterminada de 12 horas, pero esto podría cambiar).
Cada token de acceso es específico de la cuenta de usuario indicada en la solicitud de autorización original y únicamente concede acceso al servicio (en este caso, SharePoint) que se especifica en dicha solicitud. Los tokens de actualización tienen una duración mayor (seis meses en el momento de redactarse este artículo) y también se pueden almacenar en caché. Por lo tanto, el mismo token de actualización se puede canjear por un nuevo token de acceso de ACS hasta que el token de actualización expire. Para obtener más información sobre el almacenamiento de tokens en caché, vea Controlar tokens de seguridad en los complementos de SharePoint de baja confianza hospedados por el proveedor.
Cuando el token de actualización expira, Contoso.com puede obtener uno nuevo mediante un nuevo token de contexto. Para obtener más información, vea Obtener un nuevo token de contexto.
- Contoso.com usa el token de acceso para realizar una llamada de API REST de SharePoint o una solicitud de CSOM a spnv. Para ello, pasa el token de acceso de OAuth en el encabezado Authorization de HTTP. (Si el componente remoto está hospedado en una plataforma. NET, en Office Developer Tools para Visual Studio se ofrece código de ejemplo para crear el encabezado).
- SharePoint valida el token de acceso para que quede claro que ACS emitió el token. Después, envía a Contoso.com los datos que Contoso.com solicitó, o lleva a cabo la operación de crear, leer, actualizar o eliminar (CRUD) que Contoso.com solicitó.
- La página de la aplicación de Contoso.com se representa en el explorador (o en el IFRAME del elemento de complemento).