Crear complementos de SharePoint que usan la autorización de baja confianza

  • Artículo

Los componentes remotos de un complemento de SharePoint (o aplicación externa) pueden obtener autorización para los recursos de SharePoint pasando un token de acceso a SharePoint con cada solicitud HTTP. Los componentes remotos obtienen el token de acceso de una cuenta de Microsoft Azure Access Control Service (ACS) que está asociada al inquilino Office 365 del cliente. Azure ACS actúa como servidor de autorización en una transacción de OAuth 2.0 , denominada flujo, con SharePoint como servidor de recursos y los componentes remotos como cliente. Para obtener especificaciones de protocolo relacionadas, consulte Protocolo de autorización web (oauth).

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.

Los complementos de SharePoint hospedados por el proveedor que usan el sistema de autorización de baja confianza se pueden vender en la Tienda Office e instalarse en Microsoft Office SharePoint Online o en una granja de SharePoint local que se haya configurado para usar el inquilino de Office 365 del cliente para establecer la confianza con Azure ACS. El cliente debe tener un inquilino de Office 365 para instalar Complementos de SharePoint que usen el sistema de baja confianza. Sin embargo, no es necesario que el cliente use el inquilino para otros fines. Para obtener instrucciones sobre cómo vincular una granja local a un inquilino de Office 365, consulte Uso de un sitio de SharePoint de Office 365 para autorizar complementos hospedados por el proveedor en un sitio de SharePoint local.

Registro con Azure ACS

Para usar el sistema de baja confianza, el complemento de SharePoint debe registrarse primero con Azure ACS y con el servicio de administración de aplicaciones de la granja de servidores de SharePoint o el inquilino de SharePoint Online. (Se denomina "servicio de administración de aplicaciones" porque los complementos de SharePoint se denominaron inicialmente "aplicaciones para SharePoint").

En el caso de los complementos vendidos a través de la Tienda Office, el registro en ACS se realiza en el Panel de vendedores y el registro en el servicio se realiza al instalar el complemento.

En el caso de los complementos que se distribuyen en el catálogo de complementos de la organización, el registro en ACS y el servicio se realiza en la página _Layouts\15\AppRegNew.aspx de cualquier inquilino o granja de SharePoint donde se va a instalar el complemento. También es necesario registrar aplicaciones externas que no sean de SharePoint que tengan acceso a SharePoint. Esta categoría incluye complementos de Office, aplicaciones de la Tienda Windows, aplicaciones web y aplicaciones de dispositivo, como aplicaciones de smartphone.

Nota:

El registro requiere que la aplicación tenga un dominio de Internet. Cualquier dominio existente se puede usar para este propósito, pero no puede estar 100 % seguro de que cualquier dominio que no posea siempre existirá, por lo que una aplicación web tendría que formar parte de una aplicación de dispositivo nativa incluso si el componente de aplicación web no desempeñara otro rol que habilitar el registro. Para obtener un ejemplo de código avanzado diseñado de esta manera, consulte Aprovisionamiento de sitios en lotes con el modelo de complemento.

Para obtener más información sobre el registro, vea Registrar Complementos de SharePoint.

Expiración del secreto de complemento

El secreto de complemento debe reemplazarse cada 12 meses. Para obtener más información, vea Reemplazar un secreto de cliente a punto de expirar en un complemento para SharePoint.

Directivas de autorización

Un Complemento de SharePoint se puede diseñar para usar una de las tres directivas de autorización:

  • Directiva de solo usuario. Cuando se usa la directiva de solo usuario, SharePoint comprueba solo los permisos para el usuario. SharePoint usa su directiva cuando el usuario accede a los recursos directamente sin usar un complemento, como cuando un usuario abre por primera vez la página de inicio de SharePoint 2010 o accede a las API de SharePoint desde PowerShell.

  • Directiva de solo complemento. Un complemento que usa esta directiva puede realizar cualquier acción que tenga permiso para realizar, incluso si el usuario no tiene permiso para la acción. El desarrollador debe pedir que esta directiva se use en el manifiesto del complemento. La solicitud la tiene que aprobar el usuario que instala el complemento. Esta directiva se permite solo para Complementos de SharePoint hospedados por el proveedor.

  • Directiva de usuario y complemento. Los complementos que usan esta directiva solo pueden realizar acciones que tanto el complemento como el usuario tienen permiso para realizar. Esta es la directiva predeterminada que se usa a menos que el desarrollador realice pasos específicos para usar otra.

Para obtener más información sobre las directivas de autorización, vea Tipos de directivas de autorización de complementos en SharePoint.

Dos flujos en tiempo de ejecución de OAuth

Cada vez que se ejecuta un complemento de SharePoint hospedado en la nube o una aplicación externa que accede a SharePoint, se ejecuta un flujo o una serie de interacciones entre el complemento, SharePoint, ACS y, a veces, el usuario final. El resultado final del flujo es que SharePoint recibe un token de acceso incluido con cada solicitud de creación, lectura, actualización y eliminación (CRUD) que la aplicación realiza a SharePoint.

SharePoint usa dos flujos principales de OAuth. Una es para complementos de SharePoint hospedados en la nube. El otro, denominado "sobre la marcha", es para aplicaciones en otras plataformas que acceden a datos de SharePoint.

  • Flujo de token de contexto. El componente remoto del complemento de SharePoint usa el modelo de objetos de cliente (CSOM) de SharePoint o los puntos de conexión REST para realizar llamadas a SharePoint. SharePoint solicita un token de contexto al ACS que puede enviar al servidor remoto. El servidor remoto usa el token de contexto para solicitar un token de acceso a ACS. Luego, el servidor remoto usa el token de acceso para responder a SharePoint.

    Para obtener más información sobre este flujo, vea Flujo de OAuth de token de contexto para Complementos de SharePoint.

  • Flujo de código authenticaton. A un complemento de SharePoint se le conceden los permisos que necesita para los recursos de SharePoint cuando se instala. En cambio, las aplicaciones que no están instaladas en SharePoint deben pedir permisos "sobre la marcha", es decir, cada vez que se ejecutan. En este flujo no hay token de contexto de SharePoint. Cuando el complemento se ejecuta y trata de obtener acceso a SharePoint, SharePoint le pide al usuario que conceda permisos a la aplicación que está solicitando. Cuando el usuario concede los permisos, SharePoint obtiene un código de autorización de ACS que pasa a la aplicación. La aplicación usa el código para obtener un token de acceso del ACS que se puede usar para comunicarse con SharePoint.

    Para obtener más información sobre este flujo, vea Flujo de OAuth de código de autorización para complementos de SharePoint.

Solución de problemas de complementos de SharePoint de baja confianza

En este artículo se ofrecen instrucciones generales e información de solución de problemas específicos de complementos de SharePoint que usan el sistema de autorización de baja confianza.

Usar la herramienta Fiddler

La herramienta Fiddler gratuita puede usarse para capturar las solicitudes HTTP enviadas por el componente remoto del complemento a SharePoint. Hay una extensión gratuita para la herramienta que descodifica automáticamente los tokens de acceso en las solicitudes.

Desactivar el requisito de HTTPS para OAuth durante el desarrollo

OAuth requiere que SharePoint ejecute HTTPS (no solo el servicio, sino también SharePoint). Esto puede afectar al desarrollo del complemento. Por ejemplo, puede obtener un mensaje 403 (prohibido) al intentar realizar una llamada a SharePoint cuando esté depurando el complemento porque no hay ninguna compatibilidad con SSL presente en el "localhost" donde se está ejecutando el complemento.

Puede desactivar el requisito HTTPS durante el desarrollo por medio de los siguientes cmdlets de Windows PowerShell.

$serviceConfig = Get-SPSecurityTokenServiceConfig
$serviceConfig.AllowOAuthOverHttp = $true
$serviceConfig.Update()

Para volver a activar el requisito HTTPS más tarde, use los siguientes cmdlets de Windows PowerShell.

$serviceConfig = Get-SPSecurityTokenServiceConfig
$serviceConfig.AllowOAuthOverHttp = $false
$serviceConfig.Update()

Si los nombres de dominio en los archivos de configuración y en los formularios de registro no coinciden, podría impedir la autorización. Los siguientes cuatro valores tienen que ser exactamente los mismos:

  • El dominio del complemento que se especifica cuando se registra el complemento de SharePoint en AppRegNew.aspx o en el Panel de vendedores.

  • El dominio donde se registró el certificado de seguridad de la aplicación web remota.

  • La parte de dominio del valor de la StartPage en el archivo AppManifest.xml.

  • La parte del dominio de las direcciones URL de los receptores de eventos especificados en el archivo AppManifest.xml.

En relación con este punto, tenga en cuenta lo siguiente:

  • Si el componente remoto del complemento de SharePoint usa cualquier puerto distinto de 443, debe incluir explícitamente el puerto como parte del dominio en los cuatro lugares; por ejemplo, contoso.com:3333. (Debe usar el protocolo HTTPS cuyo puerto predeterminado es 443).

  • Si crea un alias DNS CNAME para su aplicación web remota, use el alias CNAME para el valor del dominio en los cuatro lugares. Por ejemplo, si la aplicación se hospeda en contoso.cloudapp.net y crea un CNAME contososoftware.com para esta, use contososoftware.com como dominio.

  • El dominio debe necesariamente estar codificado de forma rígida en el valor de la StartPage (y en todas las direcciones URL de receptores de eventos) del archivo AppManifest.xml antes de empaquetar el complemento. Si usa el Asistente para publicar en Visual Studio para empaquetar el complemento, se le pedirá el dominio y Office Developer Tools para Visual Studio lo insertará en el valor startpage automáticamente (en lugar del token que se usa durante la ~remoteWebUrl depuración. Pero si no usa el Asistente para publicación, o incluso si está pero la aplicación web remota se implementa en Azure, debe reemplazar manualmente el token por el dominio (y el protocolo); por ejemplo https://contososoftware.com o https://MyCloudVM:3333.

Error: "Se cerró la conexión subyacente: no se pudo establecer una relación de confianza para el canal seguro SSL/TLS".

Este error es una cuestión de protocolo de enlace de SSL, no una cuestión de OAuth. Asegúrese de que el certificado que use es de confianza para SharePoint, y que el certificado coincide con el nombre del extremo.

Errores al usar el método HTTP DAV para leer archivos de SharePoint

HTTP DAV no funciona con OAuth. Si usa el modelo de objetos cliente SharePoint (CSOM), use el siguiente código para leer un archivo.

File f = clientContext.Web.GetFileByServerRelativeUrl( url);
ClientResult<Stream> r = f.OpenBinaryStream();
clientContext.ExecuteQuery();

Ver también