Registrar complementos de SharePoint

Artículo
04/08/2023

Registre sus complementos de SharePoint en Azure ACS con Visual Studio, el panel de vendedores o una página AppRegNew.aspx, y recupere la información de registro.

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.

Para que los componentes remotos de un complemento de SharePoint hospedado por el proveedor interactúen con SharePoint mediante OAuth, el complemento debe registrarse primero con el servicio Azure ACS basado en la nube y el servicio de administración de aplicaciones de SharePoint del espacio empresarial o la granja. (Se denomina "servicio de administración de aplicaciones" porque los complementos de SharePoint se denominaron inicialmente "aplicaciones para SharePoint").

Nota:

Esto no es necesario para complementos hospedados en SharePoint.

Para registrar el complemento con Azure ACS, especifique la siguiente información:

Un GUID para el complemento, llamado identificador de cliente.
Una contraseña para el complemento, llamada secreto de cliente.
El nombre para mostrar del complemento que se usa en la página de consentimiento cuando se pregunta al usuario si confía en el complemento.
La dirección URL del dominio donde el complemento remoto está hospedado.
Una dirección URL de redireccionamiento.

Una vez registrado, el complemento tiene una identidad de complemento y es una entidad de seguridad, conocida como entidad de seguridad de complemento. Cuando se instala el complemento, los administradores de SharePoint pueden recuperar la información sobre esa entidad de seguridad de complemento concreta.

La primera vez que un usuario concede a un complemento permisos de acceso a los recursos de SharePoint (lo que puede suceder durante el tiempo de ejecución o de instalación, según el diseño de la aplicación), SharePoint obtiene información sobre el complemento de Azure ACS. SharePoint almacena esta información en la base de datos del servicio de administración de aplicaciones del espacio empresarial o la granja de SharePoint. El secreto de cliente solo se almacena en Azure ACS. SharePoint no conoce nunca el secreto del complemento. El servicio de contenido de la base de datos y otros componentes, como el servicio de perfiles de usuario, pueden obtener el nombre para mostrar y otra información básica sobre el complemento directamente del servicio compartido de administración de aplicaciones. Para obtener más información, vea Recuperar información sobre el registro del complemento y la entidad de seguridad de complemento en este artículo.

Nota:

En este artículo se supone que está familiarizado con los conceptos básicos y los principios fundamentales relacionados con el marco de OAuth 2.0. Para obtener más información, vea OAuth.net y Protocolo de autorización web (OAuth).

Registrar un complemento de SharePoint en Azure ACS

Puede registrar el complemento eligiendo una de tres opciones, según en qué etapa de desarrollo se encuentra, según la arquitectura de su complemento, y según cómo tiene pensado comercializarlo.

Método de registro	Detalles
Use Visual Studio y Microsoft Office Developer Tools para Visual Studio para crear una identidad de complemento temporal.	El Asistente para Office Developer Tools para Visual Studio crea un registro temporal del complemento en ACS y el servicio de administración de aplicaciones del sitio web de prueba de SharePoint. Al ejecutar el complemento en Visual Studio (F5), se usa esta identidad. Las herramientas insertan también el identificador y el secreto de cliente en los archivos AppManifest.xml y Web.config. Cuando esté preparado para publicar el complemento, puede usar el asistente para publicación de Visual Studio para ir al Panel de vendedores con el fin de registrarlo. Si no va a comercializar el complemento de SharePoint en la Tienda Office, use AppRegNew.aspx para registrarlo. (Los pasos exactos se incluyen en la sección siguiente). Nota: Si el complemento solicita permiso para acceder a los recursos de SharePoint dinámicamente en tiempo de ejecución, en lugar de en la instalación del complemento, no puede usar Visual Studio para crear identidades de complemento.
Registre el complemento en el Panel de vendedores.	Si va a usar el complemento en más de un espacio empresarial o una granja de SharePoint, use el Panel de vendedores para registrarlo, independientemente de si pretende comercializarlo en la Tienda Office o ponerlo a disposición de los usuarios mediante el catálogo de complementos. Cuando se registra en el Panel de vendedores, puede diseñar el complemento con una arquitectura multiempresa sin que sea necesario que los administradores del espacio empresarial o la granja tengan que registrarlo por separado. Además, si tiene previsto publicar el complemento en la Tienda Office, tiene que usar el Panel de vendedores para registrarlo. No tiene que usar la tienda para publicar un complemento que se ha registrado en el Panel de vendedores. Para obtener más información, vea Crear o actualizar id. de cliente y secretos de cliente en el Panel de vendedores.
Use la página AppRegNew.aspx.	Utilice el formulario AppRegNew para registrar el complemento de SharePoint si solo usa el complemento en un espacio empresarial o una granja. Por ejemplo, si crea complementos para una sola organización y va a distribuirlos a través del catálogo de complementos de la organización, puede usar la página AppRegNew.aspx de cualquier sitio web de un espacio empresarial o una granja para registrar el complemento. Un complemento registrado con AppRegNew.aspx no se puede publicar en la Tienda Office. Para complementos que se publican en la Tienda Office, debe obtener una identidad del Panel de vendedores.

Para registrarlo con AppRegNew.aspx

Vaya a <site collection url>/_layouts/15/AppRegNew.aspx mediante un explorador web.

Formulario de página AppRegNew
Escriba los valores para los siguientes campos de formulario:
- Id. de complemento. También denominado identificador de cliente; se trata de un GUID que se puede generar (cuando se selecciona Generar) o pegar en AppRegNew.aspx. El valor debe ser único para cada complemento y debe estar en minúsculas.
- Secreto de complemento. También denominado secreto de cliente, una cadena opaca. Se genera en la página AppRegNew.aspx mediante el botón Generar. Este es un ejemplo de secreto de un complemento : xvVpG0AgVIJfch6ldu4dLUlcZyysmGqBRbpFDu6AfJw=.
  
  Importante
  
  Los secretos de complemento expiran. Si registra el complemento en el Panel de vendedores, puede establecerse una expiración de un máximo de tres años. En el panel puede también agregar nuevos secretos cuando los antiguos lleguen a su fecha de expiración. El nuevo secreto se habilitará en todas las instancias del complemento. Si registra el complemento con AppRegNew.aspx, el secreto expira en un año. Para obtener más información, vea Reemplazar un secreto de cliente a punto de expirar en un complemento para SharePoint.
- Título. Título descriptivo; por ejemplo, Complemento de impresión fotográfica de Contoso. Se pide a los usuarios que concedan o denieguen al complemento los permisos que pide. Este título aparece como nombre del complemento en el mensaje de consentimiento.
- Dominio de complemento. Nombre de host del componente remoto del complemento de SharePoint. Si la aplicación remota no usa el puerto 443, el dominio de complemento debe incluir también el número de puerto. El dominio de complemento debe coincidir con los enlaces de direcciones URL que se usan para la aplicación web. No incluya el protocolo ("https:") ni caracteres "/" en este valor. Si el host de la aplicación web usa un alias DNS CNAME, úselo. Por ejemplo:
  - www.contoso.com:3333
  - www.fabrikam.com
- URI de redirección:. Punto de conexión de la aplicación remota o el servicio al que ACS envía un código de autenticación. En realidad, los complementos de SharePoint no usan este valor. El URI de redireccionamiento es necesario para las aplicaciones web que se inician fuera de SharePoint y usan el flujo del código de autenticación para obtener acceso autorizado a los datos de SharePoint.
  
  El URI de redireccionamiento se ignora para los verdaderos complementos de SharePoint (que se inician desde SharePoint y usan el Flujo de tokens de contexto).
  
  El URI de redireccionamiento suele ser la misma página, el método de controlador o el método de servicio web que solicita el código de autenticación de ACS, pero puede ser otro punto de conexión. El punto de conexión debe tener una lógica que obtenga el código de autorización de la respuesta HTTP que ACS envía y luego use ese código para solicitar un token de acceso y un token de actualización. Para obtener más información, vea Flujo de OAuth de código de autorización para complementos de SharePoint.
  
  El formulario requiere que se escriba un valor válido incluso para los verdaderos complementos de SharePoint, aunque no se use. El valor tiene que ser una URL de punto de conexión completa, incluido el protocolo, que tiene que ser HTTPS. Por ejemplo:
Seleccione Crear en el formulario. La página se vuelve a cargar y muestra una confirmación de los valores que especificó. Cree un registro de estos valores en un formulario que sea fácil de copiar y pegar. Debe especificar los valores en los archivos Web.config y AppManifest.xml en el asistente para publicación de Visual Studio.

Independientemente de cómo registre el complemento de SharePoint, cuando esté listo para implementarlo en una instalación de almacenamiento provisional o de producción, tendrá Especificar los valores de registro en los archivos Web.config y AppManifest.xml. Si usa Visual Studio, Microsoft Office Developer Tools para Visual Studio realiza automáticamente esta configuración.

Especificar los valores de registro en los archivos Web.config y AppManifest.xml

Antes de empaquetar el Complemento de SharePoint y antes de implementar sus componentes remotos, inserte algunos de los valores de registro en los archivos AppManifest.xml y web.config.

Sugerencia

Si publica el complemento de SharePoint con el asistente para publicación de Visual Studio, Visual Studio le pedirá el identificador de cliente y el secreto de cliente durante el proceso de publicación, e insertará la información automáticamente en las ubicaciones correctas.

En el archivo Web.config del proyecto de Visual Studio, escriba el valor del identificador de complemento como el valor de ClientId (reemplazando el valor temporal que las herramientas especificaron).

Importante

Todas las letras del GUID del identificador de cliente tienen que estar en minúsculas.

A continuación se muestra un ejemplo.
```
<appSettings>
  <add key="ClientId" value="a044e184-7de2-4d05-aacf-52118008c44e " />
  .  .  .
</appSettings>
```
Escriba el valor del secreto de complemento como valor de ClientSecret (reemplazando el valor temporal que las herramientas especificaron).

Este es un ejemplo de cómo se usan los valores en el archivo Web.config de una aplicación web.
```
<appSettings>
  <add key="ClientId" value="a044e184-7de2-4d05-aacf-52118008c44e " />
  <add key="ClientSecret" value="l0z/8TzWN0yQBzMBSEZtYts2Vt3Eo/oE3rfCdPaogKQ= " />
</appSettings>
```
En el archivo AppManifest.xml del proyecto de Visual Studio, escriba el valor del identificador de complemento como valor ClientIden letras minúsculas.

Nota:

El manifiesto del complemento no se aplica a las aplicaciones web que solicitan permiso de acceso a los recursos de SharePoint al instante. No son en realidad "complementos de SharePoint". No se instalan en SharePoint y no tienen un manifiesto del complemento. Para obtener más información, vea Flujo de OAuth de código de autorización para complementos de SharePoint.

En el siguiente ejemplo se muestra cómo se usa el valor ClientId en el archivo AppManifest.xml.
```
<AppPrincipal>
  <RemoteWebApplication ClientId="a044e184-7de2-4d05-aacf-52118008c44e"/>
</AppPrincipal>
```
Office Developer Tools para Visual Studio usa el token ~remoteAppUrl del elemento StartPage. (Por ejemplo, <StartPage>~remoteAppUrl/Pages/Default.aspx?{StandardTokens}</StartPage>). Este token se resuelve en la dirección URL del componente remoto si se usa el asistente para publicación de Visual Studio. Si no usa el asistente (o si lo hace, pero no quiere publicar el componente remoto en Azure), tiene que reemplazar manualmente el token por el valor Dominio del complemento que usó para registrar el complemento. Debe ser exactamente el mismo valor, incluido el número de puerto, si procede, salvo que incluya también el protocolo HTTPS. Este es un ejemplo.
```
<StartPage>https://www.contoso.com/Pages/Default.aspx?{StandardTokens}</StartPage>
```
Considere la posibilidad de usar para el elemento Title que hay en el archivo AppManifest.xml el mismo valor que usó para el campo Título en AppRegNew.aspx. El valor del elemento Title es el nombre del complemento que los usuarios ven cuando se este instala. Podría resultar confuso para los usuarios que el complemento tenga un nombre diferente en el cuadro de diálogo de consentimiento y en la interfaz de usuario de SharePoint.

El siguiente ejemplo muestra estos valores en el manifiesto del complemento.
```
<Properties>
  <Title>Contoso photo printing app</Title>
  <StartPage>https://www.contoso.com/Pages/Default.aspx?{StandardTokens}</StartPage>
</Properties>
```

Usar la URL de redireccionamiento en un complemento que pide permisos al instante

Si la aplicación web se inicia desde fuera de SharePoint (y, por lo tanto, no es un verdadero complemento de SharePoint), tiene que diseñarse para que pida permisos en SharePoint durante el tiempo de ejecución. Tiene que incluir el código que usa el URI de redireccionamiento, junto con otra información, para obtener un token de acceso de ACS. Busque el lugar donde se establece este URI y use el valor exacto que usó para el campo URI de redirección en AppRegNew.aspx o en el Panel de vendedores. Podría estar en un archivo de código o un archivo de configuración.

Recuperar información sobre el registro del complemento y la entidad de seguridad de complemento

Puede recuperar la información de registro del complemento y la información de entidad de seguridad de complemento de los complementos que ha instalado o registrado en SharePoint.

Para buscar la información de registro de un complemento que registró, vaya a http://<SharePointWebsite>/_layouts/15/AppInv.aspx.

Para hacer una búsqueda, debe recordar el identificador de cliente (también denominado identificador de complemento) que usó para registrar el complemento. La búsqueda devuelve la siguiente información sobre un identificador de cliente determinado:

Título
Dominio de complemento
Dirección URL de redireccionamiento (es igual al URI de redireccionamiento)

La búsqueda no devuelve el valor del secreto de complemento.

Para ver una lista de entidades de seguridad de complemento registradas, vaya a: http://<SharePointWebsite>/_layouts/15/AppPrincipals.aspx.