Tipos de directivas de autorización de complementos en SharePoint
Antes de leer este artículo, tiene que familiarizarse primero con los artículos Permisos de complementos en SharePoint y Flujo de OAuth de token de contexto para complementos de SharePoint.
Información general sobre los tipos de directivas de autorización de complementos
SharePoint ofrece tres tipos de directivas de autorización:
Directiva de solo complemento. Cuando se usa la directiva de solo complemento, SharePoint comprueba solo los permisos de la entidad de seguridad del complemento. Las comprobaciones de autorización solo son correctas si el complemento actual tiene permisos para realizar la acción en cuestión, independientemente de los permisos del usuario actual (si los tuviera) .
Un complemento de aprobación de gastos es un ejemplo de un complemento que puede estar diseñado para usar esta directiva. El complemento permite a usuarios, que de otro modo no podrían aprobar gastos, aprobar los gastos por debajo de una cantidad determinada. Para obtener un ejemplo, vea el escenario en la sección siguiente.
Nota:
Algunas API requieren un contexto de usuario y no se pueden ejecutar con una directiva de solo complemento. Estas incluyen muchas API para interactuar con Project Server y Project Online y para realizar consultas de búsqueda.
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 usuario y complemento. Cuando se usa la directiva user+add-in, SharePoint comprueba los permisos del usuario y de la entidad de seguridad del complemento. La comprobación de autorización solo es correcta si ambos tienen suficientes permisos para realizar la acción en cuestión.
Por ejemplo, esta directiva se usa cuando un complemento de SharePoint quiere obtener acceso a los recursos del usuario en SharePoint. (El código de los componentes remotos de Complemento de SharePoint debe estar diseñado para realizar llamadas de usuario y complemento a SharePoint.)
Escenario de ejemplo de un complemento que usa la directiva de solo complemento
Supongamos que un director de ventas de Contoso, Adam, compra un complemento de envío de gastos que usa la directiva de solo complemento. Cuando Adam decide comprar el complemento, se le solicita que permita que el complemento eleve los permisos de usuario, es decir, que permita que el complemento realice llamadas de solo complemento a SharePoint. Adam concede al complemento los permisos solicitados. A continuación, compra suficientes licencias del complemento para todos los usuarios de ventas de Contoso e instala el complemento en el sitio web de SharePoint del equipo de ventas.
Pronto, los vendedores enviarán informes de gastos mediante el nuevo complemento de envío de gastos. Los vendedores normalmente no pueden aprobar sus propios informes de gastos, pero pueden hacerlo al usar el complemento porque Adán le concedió la capacidad de aprobar automáticamente informes por debajo de 50 USD. El complemento asigna automáticamente a Adán una tarea para aprobar informes de 50 USD o más.
Esto se podría implementar otorgando el Complemento de SharePointpermiso de escrituraSharePoint a una lista de gastos aprobados. Pero, entre los usuarios, solo los gestores de recursos humanos tienen permiso de escritura en la lista. El código del complemento está diseñado para agregar el gasto a la lista realizando una llamada de solo complemento a SharePoint, cuando el gasto es inferior a 50 $. Dado que no se comprueban los permisos del usuario, los envíos de cualquier usuario por debajo de 50 USD se agregan automáticamente a la lista de gastos aprobados, incluso si el usuario no tiene permiso de escritura en la lista.
Cómo los complementos obtienen permiso para usar la directiva de solo complemento
Para poder realizar llamadas de solo complemento a SharePoint, el complemento debe solicitar permiso para usar la directiva de solo complemento. Esta solicitud se realiza en el manifiesto del complemento. Para ello, agregue el atributo AllowAppOnlyPolicy al elemento AppPermissionRequests y lo establezca en true , como se muestra en el marcado siguiente:
<AppPermissionRequests AllowAppOnlyPolicy="true">
...
</AppPermissionRequests>
Nota:
SharePoint Add-ins used to be called "apps for SharePoint." To maintain backward compatibility, the app manifest schema was not changed, so the string "app" appears in many element and attribute names.
Se pide a un usuario que instale el complemento que apruebe esta solicitud. Si el complemento solicita permisos de ámbito de inquilino, solo un administrador de inquilinos puede conceder el uso de la directiva de solo complemento, por lo que solo un administrador de inquilinos puede instalar el complemento.
Si el complemento no solicita ningún permiso con un ámbito superior a la colección de sitios, un administrador de la colección de sitios puede instalar el complemento. Para obtener más información sobre los ámbitos de permisos, vea Permisos de complemento en SharePoint.
Cómo los complementos realizan llamadas de solo complemento
La diferencia entre una llamada de solo complemento a SharePoint y una llamada de usuario y complemento es el tipo de token de acceso que se incluye en la llamada. El siguiente código muestra cómo obtener tokens de acceso de solo complemento, y de usuario y complemento en el código administrado. La codificación detallada se realiza en el archivo TokenHelper.cs (o .vb) que Office Developer Tools para Visual Studio agrega automáticamente al proyecto de de Visual Studio.
string contextTokenString = TokenHelper.GetContextTokenFromRequest(Request);
if (contextTokenString != null)
{
//Get context token.
SharePointContextToken contextToken =
TokenHelper.ReadAndValidateContextToken(contextTokenString, Request.Url.Authority);
Uri sharepointUrl = new Uri(Request.QueryString["SPHostUrl"]);
//Get user+add-in access token.
string accessToken =
TokenHelper.GetAccessToken(contextToken, sharepointUrl.Authority).AccessToken;
ClientContext clientContext =
TokenHelper.GetClientContextWithAccessToken(sharepointUrl.ToString(), accessToken);
//Do something.
...
//Get add-in-only access token.
string addinOnlyAccessToken =
TokenHelper.GetAppOnlyAccessToken(contextToken.TargetPrincipalName,
sharepointUrl.Authority, contextToken.Realm).AccessToken;
//Do something.
...
}
Nota:
Los complementos que no realizan llamadas autenticadas de OAuth (por ejemplo, complementos que solo son JavaScript que se ejecutan en la web del complemento) no pueden usar la directiva de solo complemento. Pueden solicitar el permiso, pero no pueden aprovecharlo porque para ello es necesario pasar un token de OAuth solo de complemento. Solo los complementos con aplicaciones web que se ejecuten fuera de SharePoint pueden crear y pasar tokens de solo complemento.
En general, se necesita un usuario actual para realizar una llamada. En el caso de una directiva de solo complemento, SharePoint crea un SHAREPOINT\APP, similar al usuario existente de SHAREPOINT\SYSTEM. SHAREPOINT\APP realiza todas las solicitudes de solo complemento. No hay ninguna manera de autenticarse como SHAREPOINT\APP a través de la autenticación basada en el usuario.
Instrucciones de uso de la directiva de solo complemento
Dado que las llamadas solo de complemento elevan eficazmente los privilegios de usuario, debe ser conservador en la creación de complementos que soliciten permiso para crearlos. Las llamadas solo deben usar la directiva de solo complemento si:
El complemento necesita elevar sus permisos por encima del usuario para una llamada específica, por ejemplo, para aprobar un informe de gastos bajo condiciones evaluadas por el complemento.
El complemento no actúa en nombre de ningún usuario, por ejemplo, un complemento que realiza tareas de mantenimiento nocturnas en una biblioteca de documentos de SharePoint.