Compartir vía

Crear complementos de SharePoint de elevada confianza

  • Artículo

Un complemento de elevada confianza es un complemento de SharePoint hospedado por el proveedor que usa certificados digitales para establecer la confianza entre la aplicación web remota y SharePoint. "Elevada confianza" no es lo mismo que "plena confianza". Un complemento de elevada confianza aún tiene que solicitar permisos de complementos. El complemento se considera de "elevada confianza" porque se confía en él para usar las identidades de usuario que necesita, ya que es el responsable de crear la parte de usuario del token de acceso que pasa a SharePoint.

Un complemento de SharePoint de elevada confianza se ha diseñado principalmente para su uso en un entorno local. El complemento de elevada confianza no se puede instalar en Microsoft SharePoint Online y los componentes remotos también suelen instalarse localmente, dentro del firewall corporativo. Por lo tanto, las instancias del complemento de SharePoint son específicas para cada compañía.

Un complemento de elevada confianza usa un certificado en lugar de un token de contexto para establecer la confianza. (Un complemento hospedado por el proveedor que se ha creado para usar Microsoft Azure Access Control Service (ACS) ya que su agente de confianza debe modificarse para que funcione como una aplicación de elevada confianza). Los complementos de elevada confianza necesitan una configuración determinada en la granja de SharePoint y en el servidor que hospeda la aplicación web remota.

En SharePoint, el servicio de token de seguridad (STS) de servidor a servidor proporciona tokens de acceso para la autenticación de servidor a servidor. El STS de servidor a servidor habilita tokens de acceso temporales con acceso a otros servicios de aplicación, tales como Exchange, Lync y complementos de SharePoint. Establezca una relación de confianza entre los servicios de aplicación (por ejemplo, para establecer confianza entre SharePoint y un complemento remoto) mediante cmdlets de Windows PowerShell y un certificado.

Nota:

El uso del STS de servidor a servidor no se ha diseñado para la autenticación de usuarios. Por lo tanto, no verá el STS de servidor a servidor en la página de inicio de sesión de usuario, en la sección Proveedor de autenticación de Administración central ni en el Selector de personas de SharePoint.

En este artículo se muestra cómo crear un complemento de elevada confianza y se ofrecen las instrucciones de instalación para ejecutarlo en Visual Studio seleccionando F5. Aprenderá a:

  • Configurar un complemento para usarlo como complemento de elevada confianza.
  • Configurar SharePoint para usar complementos de elevada confianza.
  • Crear un complemento básico de elevada confianza.

La configuración de un entorno de prueba, de ensayo o de producción son ligeramente diferentes y se describen en el tema Empaquetar y publicar complementos de elevada confianza para SharePoint.

Requisitos previos

Para seguir los procedimientos de este artículo, asegúrese de que dispone de lo siguiente:

Obtener un certificado o crear un certificado de prueba público y privado

Necesita un certificado digital X.509 para la aplicación web remota del complemento de elevada confianza. Para probar por completo el complemento de SharePoint, necesita un certificado emitido por el dominio o un certificado comercial emitido por una entidad de certificación. Pero, para la fase inicial de depuración, puede usar un certificado autofirmado.

El procedimiento siguiente describe cómo crear y exportar un certificado de prueba mediante IIS. Aprenderá a reemplazar el certificado autofirmado por un certificado comercial o emitido por el dominio en la sección Completar la depuración con un certificado comercial o emitido por un dominio más adelante.

También puede usar el programa de prueba MakeCert para generar un certificado X.509. Para obtener más información sobre el uso de MakeCert, vea cómo firmar y comprobar código con Authenticode.

En primer lugar, creará un archivo de certificado .pfx de prueba y luego un archivo .cer de prueba correspondiente. El certificado .pfx contiene la clave privada que usa la aplicación web remota para firmar sus comunicaciones con SharePoint. El certificado .cer contiene la clave pública que utiliza SharePoint descifrar los mensajes, comprobar que proceden de la aplicación web remota y comprobar que la aplicación web remota tiene un token de acceso de un emisor de tokens en el que SharePoint confía. Para obtener más información sobre los archivos .pfx y .cer, vea el artículo sobre el certificado de publicadores de software.

Para crear un archivo de certificado .pfx de prueba autofirmado

  1. Al depurar un complemento de SharePoint de elevada confianza en Visual Studio, la aplicación web remota se hospeda en IIS Express en la máquina donde se ha instalado Visual Studio. Así que el equipo de la aplicación web remota no tiene un Administrador de IIS en donde se pueda crear el certificado. Por este motivo, use IIS en el servidor de prueba de SharePoint para crear el certificado.

En el Administrador de IIS, seleccione el nodo ServerName en la vista de árbol de la izquierda.

  1. Seleccione el icono Certificados de servidor, tal y como se muestra en la ilustración siguiente.

Opción Certificados de servidor de IIS

  1. Seleccione el vínculo Crear certificado autofirmado en el conjunto de vínculos de la derecha.

Vínculo Crear certificado autofirmado

  1. Asigne el nombre HighTrustSampleCert al certificado y seleccione Aceptar.

  2. Haga clic con el botón derecho en el certificado y seleccione Exportar.

Exportar un certificado de prueba

  1. En Windows (o en una línea de comandos), cree una carpeta llamada C:\Certs.

  2. Desde el Administrador de IIS, exporte el archivo a C:\Certs y asígnele una contraseña. En este ejemplo, la contraseña es contraseña.

  3. Si la instalación de SharePoint de prueba no está en el mismo equipo donde se ejecuta Visual Studio, cree una carpeta C:\Certs en el equipo de Visual Studio y mueva el archivo HighTrustSampleCert.pfx a él. Este es el equipo donde se ejecuta la aplicación web remota cuando se depura en Visual Studio.

Para crear un archivo .cer correspondiente

  1. En el servidor de SharePoint, asegúrese de que la identidad del grupo de complementos para los siguientes grupos de complementos de IIS tiene derechos de lectura en la carpeta C:\Certs:

  • SecurityTokenServiceApplicationPool

  • Grupo de complementos que ofrece el sitio web de IIS donde se hospeda la aplicación web del sitio primario de SharePoint para el sitio web de prueba de SharePoint. En el sitio web de IIS SharePoint - 80, el grupo se denomina OServerPortalAppPool.

  1. En el Administrador de IIS, seleccione el nodo ServerName en la vista de árbol de la izquierda.

  2. Haga doble clic en Certificados de servidor.

  3. En la vista Certificados de servidor, haga doble clic en HighTrustSampleCert para mostrar los detalles del certificado.

  4. En la pestaña Detalles, seleccione Copiar a archivo para iniciar el Asistente para exportación de certificados y, después, seleccione Siguiente.

  5. Use el valor predeterminado No exportar la clave privada y seleccione Siguiente.

  6. Use los valores predeterminados y luego seleccione Siguiente.

  7. Seleccione Examinar, vaya a C:\Certs, asigne el nombre HighTrustSampleCert al certificado y seleccione Guardar. El certificado se guarda como archivo .cer.

  8. Seleccione Siguiente.

  9. Seleccione Finalizar.

Configurar SharePoint para usar certificados y configurar la confianza del complemento

El script de Windows PowerShell que cree en esta sección está pensado para permitir el uso de F5 en Visual Studio. No configurará correctamente una instalación de SharePoint de almacenamiento provisional o de producción. Para obtener instrucciones sobre cómo configurar una instancia de SharePoint de producción para usar certificados, vea Empaquetar y publicar complementos de elevada confianza para SharePoint.

Importante

Compruebe que completó los pasos de Configurar servicios en SharePoint para el uso de complementos entre servidores (que aparece como requisito previo en este artículo). Si no es así, deberá configurarlos ahora, antes de continuar.

Para configurar SharePoint

  1. En un editor de texto o de Windows PowerShell, inicie un nuevo archivo y agréguele las siguientes líneas para crear un objeto de certificado:
  $publicCertPath = "C:\Certs\HighTrustSampleCert.cer"
  $certificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($publicCertPath)
  1. Agregue la siguiente línea para asegurarse de que SharePoint trata el certificado como entidad de certificación raíz.
  New-SPTrustedRootAuthority -Name "HighTrustSampleCert" -Certificate $certificate
  1. Agregue la línea siguiente para obtener el identificador del dominio Kerberos de autorización.
  $realm = Get-SPAuthenticationRealm
  1. La aplicación web remota usa un token de acceso para obtener acceso a datos de SharePoint. El token de acceso debe emitirlo un emisor de tokens en el que SharePoint confíe. En un complemento de SharePoint de elevada confianza, el certificado es el emisor de tokens. Agregue las líneas siguientes para construir un identificador de emisor en el formato que SharePoint requiere: _specific_issuer_GUID_@_realm_GUID_.
  $specificIssuerId = "11111111-1111-1111-1111-111111111111"
  $fullIssuerIdentifier = $specificIssuerId + '@' + $realm

Nota:

El valor de $specificIssuerId tiene que ser un GUID porque, en un entorno de producción, cada certificado ha de tener un emisor único. Pero, en este contexto, en el que se usa el mismo certificado para depurar todos los complementos de elevada confianza, puede codificarse de forma rígida el valor. Si, por algún motivo, usa un GUID diferente del que se usa aquí, asegúrese de que las letras del GUID estén en minúsculas. Actualmente, la infraestructura de SharePoint requiere minúsculas para los GUID del emisor.

  1. Agregue las líneas siguientes para registrar el certificado como un emisor de tokens de confianza. El parámetro -Name debe ser único, por lo que, en una configuración de producción, es habitual utilizar un GUID como parte del nombre (o todo el nombre), pero en este contexto, se puede usar un nombre descriptivo. Se necesita el modificador -IsTrustBroker para asegurarse de que puede usar el mismo certificado para todos los complementos de elevada confianza que desarrolle. El comando iisreset es necesario para que el emisor de tokens se registre inmediatamente. Sin él, es posible que tenga que esperar hasta 24 horas para que se registre el nuevo emisor.
  New-SPTrustedSecurityTokenIssuer -Name "High Trust Sample Cert" -Certificate $certificate -RegisteredIssuerName $fullIssuerIdentifier -IsTrustBroker
  iisreset
  1. SharePoint no acepta normalmente certificados autofirmados. Así que si usa un certificado autofirmado para depurar, agregue las siguientes líneas para desactivar el requisito normal de SharePoint sobre que debe usarse HTTPS para llamar a las aplicaciones web remotas en SharePoint. Si no lo hace, obtendrá un mensaje 403 (prohibido) cuando la aplicación web remota llame a SharePoint mediante un certificado autofirmado. Este paso se revertirá en un procedimiento posterior. La desactivación del requisito de HTTPS implica que las solicitudes de la aplicación web remota a SharePoint no se cifran, pero el certificado se sigue usando como emisor de confianza de tokens de acceso, que es su principal finalidad en los complementos de SharePoint de elevada confianza.
  $serviceConfig = Get-SPSecurityTokenServiceConfig
  $serviceConfig.AllowOAuthOverHttp = $true
  $serviceConfig.Update()

  1. Guarde el archivo con el nombre HighTrustConfig-ForDebugOnly.ps1.

  2. Abra el Shell de administración de SharePoint como administrador y ejecute el archivo con la línea siguiente:

  ./HighTrustConfig-ForDebugOnly.ps1

Crear un complemento de SharePoint de elevada confianza

En esta sección, creará un complemento de SharePoint de elevada confianza con Visual Studio.

Nota:

Como se indicó en la sección Requisitos previos para crear complementos de elevada confianza, en este artículo se da por hecho que sabe cómo crear un complemento de SharePoint hospedado por el proveedor. Para obtener más información, vea Introducción a la creación de complementos de SharePoint hospedados por el proveedor.

Para crear un complemento de SharePoint de elevada confianza

  1. En Visual Studio, seleccione Archivo>Nuevo>Proyecto.

  2. En el Asistente para nuevos proyectos, expanda el nodo Visual C# o Visual Basic y luego expanda el nodo Office/SharePoint.

  3. Seleccione Complementos y luego la opción para crear un proyecto Complemento de SharePoint.

  4. Asigne al proyecto el nombre HighTrustSampleApp.

  5. Guarde el proyecto en la ubicación que quiera y seleccione Aceptar.

  6. Especifique la dirección URL completa del sitio para desarrolladores de SharePoint. Por ejemplo: http://TestServer/sites/devsite/

  7. Seleccione la opción Hospedado por el proveedor y luego el botón Siguiente.

  8. Si se le pide que especifique el tipo de proyecto web, elija Aplicación de formularios Web Forms ASP.NET para el ejemplo en curso en este tema y luego seleccione el botón Siguiente.

  9. Se abrirá la página Configurar los parámetros de autenticación. del asistente. Los valores que agregue a este formulario se agregan automáticamente al archivo Web.config. En ¿Cómo quiere que se autentique el complemento?, seleccione Usar un certificado.

  10. Haga clic en el botón Examinar junto al cuadro Ubicación del certificado y vaya a la ubicación del certificado autofirmado (archivo .pfx) que creó (C:\Certs). El valor de este campo tendría que ser la ruta de acceso completa C:\Certs\HighTrustSampleCert.pfx.

  11. Escriba la contraseña para el certificado en el cuadro Contraseña. En este caso, es contraseña.

  12. Escriba el identificador del emisor (11111111-1111-1111-1111-111111111111) en el cuadro Id. del emisor.

  13. Seleccione Finalizar. Gran parte de la configuración se realiza cuando se abre la solución. Se crean dos proyectos en la solución Visual Studio, uno para el complemento de SharePoint y otro para la aplicación web ASP.NET.

Para ejecutar y depurar el complemento

  1. Office Developer Tools para Visual Studio genera automáticamente los archivos default.aspx y default.aspx.cs cuando se crea el proyecto ASP.NET. El código generado captura el título de la web de host de SharePoint y lo imprime en la página predeterminada de la aplicación web remota. El marcado y el código exactos de estos archivos varían según la versión de las herramientas. En este tema, se usan los archivos default.aspx y default.aspx.cs generados sin modificar.

  2. Para probar el complemento de SharePoint y su aplicación web remota, seleccione la tecla F5 en Visual Studio. La aplicación web se implementa en IIS Express en localhost. El complemento de SharePoint se instala en el sitio web de SharePoint de destino. SharePoint le pedirá que conceda los permisos que el complemento de SharePoint solicita. Algunas versiones de Microsoft Office Developer Tools para Visual Studio inician el complemento inmediatamente; otras abrirán la página Contenidos del sitio del sitio web de SharePoint de destino y se verá el nuevo complemento en la lista.

Inicie el complemento si no se inicia automáticamente. La aplicación web remota se abrirá en la página especificada como Página de inicio en el archivo AppManifest.xml, que es Default.aspx. El complemento tendrá un aspecto similar al de la siguiente ilustración.

Aplicación de ejemplo que recupera título web

Completar la depuración con un certificado comercial o emitido por un dominio

El script de Windows PowerShell que creó anteriormente desactivó el requisito habitual de SharePoint de que las aplicaciones web remotas usen el protocolo HTTPS para acceder a SharePoint. Trabajar con HTTPS desactivado podría hacer que, como desarrollador, pase por alto determinados problemas al compilar un complemento que se podrían producir durante una implementación de producción en que se requiere HTTPS. Por consiguiente, no debe considerar las fases de desarrollo y depuración completadas hasta que no haya reemplazado el certificado de prueba con un certificado comercial o emitido por el dominio y haya vuelto a probar el complemento con el requisito de HTTPS activado.

Cuando haya obtenido el nuevo certificado, debe agregarle una contraseña, si aún no la tiene. En un entorno de producción, usaría una contraseña segura, pero para depurar un complemento de SharePoint, no tiene que usar nada. Necesita el certificado en dos formatos, pfx y cer. Si al obtenerlo no está en formato pfx, debe convertirlo en pfx mediante una utilidad. Si tiene un archivo pfx, puede importarlo a IIS y exportar el archivo .cer tal y como se describe en el procedimiento siguiente.

Para importar el nuevo certificado

  1. Coloque el archivo .pfx en C:\Certs en el servidor de SharePoint. A efectos de este artículo, se supone que el archivo se denomina "MyCert.pfx". Debe reemplazar "MyCert" en todas estas instrucciones por el nombre real del certificado.

  2. En el Administrador de IIS, seleccione el nodo ServerName en la vista de árbol de la izquierda.

  3. Haga doble clic en el icono Certificados de servidor.

  4. Seleccione Importar en el panel Acciones de la derecha.

  5. En el cuadro de diálogo Importar certificado, use el botón Examinar para ir a C:\Certs\MyCert.pfx y, después, escriba la contraseña del certificado.

  6. Asegúrese de que la opción Permitir la exportación de este certificado esté habilitada y seleccione Aceptar.

  7. En la lista Certificados de servidor, haga clic con el botón derecho en el certificado y luego seleccione Exportar.

  8. Exporte el archivo a C:\Certs y especifique su contraseña.

  9. Si la instalación de SharePoint de prueba no está en el mismo equipo donde se ejecuta Visual Studio, mueva el archivo MyCert.pfx a la carpeta C:\Certs del equipo de Visual Studio.

  10. En la vista Certificados de servidor, haga doble clic en MyCert para ver los detalles del certificado.

  11. En la pestaña Detalles, seleccione Copiar a archivo para iniciar el Asistente para exportación de certificados y, después, seleccione Siguiente.

  12. Use el valor predeterminado No exportar la clave privada y seleccione Siguiente.

  13. Use valores predeterminados. Seleccione Siguiente.

  14. Seleccione Examinar, vaya a C:\Certs, asigne el nombre MyCert al certificado y seleccione Guardar. El certificado se guarda como archivo .cer.

  15. Seleccione Siguiente.

  16. Seleccione Finalizar.

Para configurar SharePoint para usar el nuevo certificado

  1. Abra el archivo HighTrustConfig-ForDebugOnly.ps1 para su edición y realice los cambios siguientes:

  • Reemplace HighTrustSampleCert en las dos ubicaciones donde aparece por MyCert.

  • Reemplace el identificador del emisor específico (11111111-1111-1111-1111-111111111111) por 22222222-2222-2222-2222-222222222222.

  • Reemplace "Certificado de ejemplo de elevada confianza" por "Mi certificado" u otro nombre descriptivo adecuado.

  • En la línea $serviceConfig.AllowOAuthOverHttp = $true, reemplace true por false. Así se vuelve a cambiar el requisito de que se use HTTPS.

  1. Guarde el archivo.

  2. Abra el Shell de administración de SharePoint como administrador y ejecute el archivo con la línea siguiente:

  ./HighTrustConfig-ForDebugOnly.ps1

Para reconfigurar la aplicación web remota

  1. En Visual Studio, abra el archivo Web.config del proyecto de aplicación web y realice los cambios siguientes:

  • En la clave ClientSigningCertificatePath, reemplace C:\Certs\HighTrustSampleCert.pfx por C:\Certs\<MyCert>.pfx.

  • Reemplace el valor de la clave ClientSigningCertificatePassword por la contraseña real de certificado.

  • Reemplace el valor de la clave IssuerId por 22222222-2222-2222-2222-222222222222.

  1. Seleccione F5 para depurar el complemento.

Cuando termine de desarrollar el complemento de elevada confianza, consulte Empaquetar y publicar complementos de elevada confianza para SharePoint para obtener instrucciones sobre cómo empaquetar y publicar este tipo de complemento de SharePoint.

¿Cuál es la finalidad de los archivos TokenHelper y SharePointContext?

Office Developer Tools para Visual Studio incluye un archivo TokenHelper.cs (o .vb) en la aplicación web remota. Algunas versiones de las herramientas incluyen también un archivo SharePointContext.cs (o .vb).

El código de estos archivos realiza lo siguiente:

  • Configura .NET para que confíe en los certificados al realizar llamadas de red.

  • Recupera un token de acceso de servidor a servidor firmado por el certificado privado de la aplicación web remota en nombre del objeto WindowsIdentity especificado y que SharePoint usa para establecer la confianza.

  • Obtiene el certificado de servicio de token de seguridad (STS) de SharePoint.

  • En complementos que usen el sistema de autorización de baja confianza en lugar del de elevada confianza, estos archivos tienen tareas adicionales, como controlar los tokens de OAuth para el escenario descrito en Flujo de OAuth de token de contexto para complementos de SharePoint. Este escenario se encuentra fuera del ámbito de este artículo.

En un complemento de elevada confianza, no hay ningún token de contexto. El token de contexto es específico de las configuraciones que usan autorización de confianza baja. Sin embargo, sigue siendo necesario un token de acceso. Si usa una configuración de elevada confianza, la aplicación web debe autenticar al usuario de la misma manera que lo hace SharePoint (es decir, el complemento es el responsable de crear el token de acceso, incluidos los identificadores del usuario y el proveedor de identidades).

Al depurar en Visual Studio con F5, Microsoft Office Developer Tools para Visual Studio usa la autenticación de Windows y los dos archivos de código generados usan la identidad de Windows de la persona que ejecuta el complemento para crear el token de acceso. Cuando se publique el complemento, debe configurar la aplicación web remota en el Administrador de IIS para que use la autenticación de Windows si quiere utilizar los dos archivos generados sin modificar.

Si el complemento no va a usar la autenticación de Windows en el entorno de producción, debe personalizar los archivos de código generados, TokenHelper o SharePointContext, para utilizar otro sistema de autenticación. También personalizaría estos archivos si la aplicación web remota obtiene acceso a SharePoint en una identidad distinta a la del usuario que ejecute el complemento de SharePoint. Por último, si la aplicación web remota es PHP, node.js, Java o alguna otra plataforma que no sea ASP.NET, el código tiene que obtener el identificador del usuario desde el sistema de autenticación que se use y luego agregarlo en el token de acceso que crea.

Ver también