Introducción a los permisos seleccionados en OneDrive y SharePoint

SharePoint y OneDrive tienen un modelo de permisos establecido desde hace mucho tiempo que no encaja exactamente en el modelo de ámbitos. Por ejemplo, un ámbito global que proporciona acceso ReadWrite a una sola lista del inquilino no existe. En su lugar, los ámbitos seleccionados admiten estos escenarios. Inicialmente, Sites.Selected existía para restringir el acceso de una aplicación a una única colección de sitios. Ahora también se admiten listas, elementos de lista, carpetas y archivos, y todos los ámbitos seleccionados ahora admiten modos de aplicación y delegados.

Nota

Debido a la evolución de los requisitos de nomenclatura de ámbito, los ámbitos más recientes se enumeran como una tupla *.SelectedOperations.Selectedcompleta. No hay ninguna diferencia funcional entre este formato y el Sites.Selected formato.

Scopes

En la tabla siguiente se enumeran los ámbitos de permisos seleccionados.

Scopes	Descripción
Sites.Selected	Administra el acceso a la aplicación en el nivel de colección de sitios, lo que proporciona acceso a una colección de sitios específica.
Lists.SelectedOperations.Selected	Administra el acceso a la aplicación en el nivel de lista, lo que proporciona acceso a una lista específica.
ListItems.SelectedOperations.Selected	Administra el acceso a la aplicación en el nivel de archivos, elemento de lista o carpeta, lo que proporciona acceso a uno o varios elementos de lista.
Files.SelectedOperations.Selected	Administra el acceso a la aplicación en el nivel de carpeta de archivo o biblioteca, lo que proporciona acceso a uno o varios archivos.

Cómo funcionan los ámbitos seleccionados con permisos de SharePoint y OneDrive

Cuando un administrador da su consentimiento a ámbitos seleccionados para una aplicación, delega la administración de permisos de recursos a los propietarios de ese recurso dentro de la carga de trabajo. En el caso de otros ámbitos, como Files.Read.All, en cuanto se da su consentimiento al ámbito, la aplicación puede acceder a los recursos que representa. Los ámbitos seleccionados requieren una acción de asignación explícita; una aplicación consentida para Lists.SelectedOperations.Selected inicialmente no tendría acceso.

Los ámbitos seleccionados requieren una serie de pasos para funcionar, lo que proporciona varios medios de control para los administradores. En el ejemplo siguiente se usa el Lists.SelectedOperations.Selected ámbito, pero los pasos se aplican a todos los *. Ámbitos seleccionados.

1. La aplicación debe dar su consentimiento en Id. de entra para tener la aplicación o el ámbito delegado Lists.SelectedOperations.Selected .
2. Se deben conceder permisos a la aplicación a una lista a través de una llamada a POST /sites/{siteid}/lists/{listid}/permissions con un rol específico.
3. La aplicación debe adquirir un token válido que contenga el Lists.SelectedOperations.Selected ámbito de las llamadas a la lista con permisos.

Si se pierde cualquiera de los tres pasos, la aplicación no tiene acceso. Los administradores dos puntos de control:

• Quite los permisos de una lista específica mediante una llamada a DELETE /sites/{siteid}/lists/{listid}/permissions/{id}, que quita el acceso a la lista de esa aplicación.
• Revoque el consentimiento de Lists.SelectedOperations.Selected ámbito en Entra ID, lo que impide que la aplicación acceda a cualquier lista a la que se le hayan concedido permisos anteriormente.

En función de esto, puede dar su consentimiento a una aplicación en el Lists.SelectedOperations.Selected ámbito de Entra ID, pero no conceder permisos a ninguna lista, lo que significa que la aplicación no tiene acceso. Del mismo modo, puede llamar a POST /sites/{siteid}/lists/{listid}/permissions cualquier aplicación, pero sin que aparezcan los ámbitos adecuados en el token, la aplicación no tiene acceso. Los tres pasos deben completarse para garantizar el acceso esperado. Esto también se aplica al otro *. Ámbitos seleccionados y sus respectivos niveles.

Nota

La asignación de permisos de aplicación a listas, elementos de lista, carpetas o archivos interrumpe la herencia en el recurso asignado, por lo que debe tener en cuenta los límites de servicio para permisos únicos en el diseño de la solución. Los permisos en el nivel de colección de sitios no interrumpen la herencia porque esta es la raíz de la herencia de permisos.

Se muestra un ejemplo de configuración de permisos para sitios; la lógica es similar para listas, elementos de lista, archivos o carpetas.

¿Cuál es la diferencia entre los ámbitos files y listItems?

En SharePoint, todos los archivos son elementos de lista, pero todos los elementos de lista no son archivos. Como resultado, las aplicaciones que llevan el ListItems.SelectedOperations.Selected ámbito pueden acceder a todos los elementos y archivos de lista y operar en ellos hasta su rol permitido. Las aplicaciones con Files.SelectedOperations.Selected solo pueden funcionar en archivos (elementos de lista) dentro de bibliotecas de documentos u otras listas marcadas como que contienen documentos. Esto imita el comportamiento Files.Read.All y Files.ReadWrite.All que existe actualmente, pero aislado en un único archivo. Este comportamiento no cambia en función de la ruta de acceso de Microsoft Graph usada, como con /drives/{driveid}/items/{itemid} y /sites/{siteid}/lists/{listid}/items/{itemid}; en su lugar, el destino al que se va a acceder controla el comportamiento.

Funciones

En la tabla siguiente se enumeran los cuatro roles que se pueden asignar a una aplicación para un recurso determinado.

Role	Descripción
read	Lea los metadatos y el contenido del recurso.
write	Lea y modifique los metadatos y el contenido del recurso.
owner	Representa el rol de propietario.
fullcontrol	Representa el control total del recurso.

Solicitud

HTTP

HTTP

POST https://graph.microsoft.com/v1.0/sites/{siteId}/permissions
Content-Type: application/json

{
  "roles": ["write"],
  "grantedTo": {
    "application": {
      "id": "89ea5c94-7736-4e25-95ad-3fa95f62b66e"
    }
  }
}

C#

C#

// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new Permission
{
	Roles = new List<string>
	{
		"write",
	},
	GrantedTo = new IdentitySet
	{
		Application = new Identity
		{
			Id = "89ea5c94-7736-4e25-95ad-3fa95f62b66e",
		},
	},
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Sites["{site-id}"].Permissions.PostAsync(requestBody);

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

CLI

Bash

mgc sites permissions create --site-id {site-id} --body '{\
  "roles": ["write"],\
  "grantedTo": {\
    "application": {\
      "id": "89ea5c94-7736-4e25-95ad-3fa95f62b66e"\
    }\
  }\
}\
'

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Ir

Go

// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

requestBody := graphmodels.NewPermission()
roles := []string {
	"write",
}
requestBody.SetRoles(roles)
grantedTo := graphmodels.NewIdentitySet()
application := graphmodels.NewIdentity()
id := "89ea5c94-7736-4e25-95ad-3fa95f62b66e"
application.SetId(&id) 
grantedTo.SetApplication(application)
requestBody.SetGrantedTo(grantedTo)

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
permissions, err := graphClient.Sites().BySiteId("site-id").Permissions().Post(context.Background(), requestBody, nil)

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Java

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

Permission permission = new Permission();
LinkedList<String> roles = new LinkedList<String>();
roles.add("write");
permission.setRoles(roles);
IdentitySet grantedTo = new IdentitySet();
Identity application = new Identity();
application.setId("89ea5c94-7736-4e25-95ad-3fa95f62b66e");
grantedTo.setApplication(application);
permission.setGrantedTo(grantedTo);
Permission result = graphClient.sites().bySiteId("{site-id}").permissions().post(permission);

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

JavaScript

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const permission = {
  roles: ['write'],
  grantedTo: {
    application: {
      id: '89ea5c94-7736-4e25-95ad-3fa95f62b66e'
    }
  }
};

await client.api('/sites/{siteId}/permissions')
	.post(permission);

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

PHP

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\Permission;
use Microsoft\Graph\Generated\Models\IdentitySet;
use Microsoft\Graph\Generated\Models\Identity;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new Permission();
$requestBody->setRoles(['write', 	]);
$grantedTo = new IdentitySet();
$grantedToApplication = new Identity();
$grantedToApplication->setId('89ea5c94-7736-4e25-95ad-3fa95f62b66e');
$grantedTo->setApplication($grantedToApplication);
$requestBody->setGrantedTo($grantedTo);

$result = $graphServiceClient->sites()->bySiteId('site-id')->permissions()->post($requestBody)->wait();

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

PowerShell

PowerShell

Import-Module Microsoft.Graph.Sites

$params = @{
	roles = @(
	"write"
)
grantedTo = @{
	application = @{
		id = "89ea5c94-7736-4e25-95ad-3fa95f62b66e"
	}
}
}

New-MgSitePermission -SiteId $siteId -BodyParameter $params

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Python

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.permission import Permission
from msgraph.generated.models.identity_set import IdentitySet
from msgraph.generated.models.identity import Identity
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = Permission(
	roles = [
		"write",
	],
	granted_to = IdentitySet(
		application = Identity(
			id = "89ea5c94-7736-4e25-95ad-3fa95f62b66e",
		),
	),
)

result = await graph_client.sites.by_site_id('site-id').permissions.post(request_body)

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Encabezados de solicitud

Nombre	Descripción
Authorization	{token} de portador. Obligatorio. Obtenga más información sobre la autenticación y la autorización.
Content-Type	application/json. Necesario.

Respuesta

HTTP

HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": "1",
    "@deprecated.GrantedToIdentities": "GrantedToIdentities has been deprecated. Refer to GrantedToIdentitiesV2",
    "roles": ["write"],
    "grantedToIdentities": [{
      "application": {
        "id": "89ea5c94-7736-4e25-95ad-3fa95f62b66e",
        "displayName": "Contoso Time Manager App"
      }
    }],
    "grantedToIdentitiesV2": [{
      "application": {
        "id": "89ea5c94-7736-4e25-95ad-3fa95f62b66e",
        "displayName": "Contoso Time Manager App"
      }
    }]
}

Para ver ejemplos que muestran cómo administrar permisos, consulte los temas de API /permissions para site, list, listItem y driveItem.

¿Qué permisos necesito para administrar permisos?

Los requisitos de permisos varían según el nivel. En todos los casos delegados, los casos en los que el usuario actual también necesita permisos suficientes para administrar el acceso mediante una llamada a la API. En la tabla siguiente se incluyen ámbitos y ámbitos y roles asignados al recurso primario. Por ejemplo, si tiene el ámbito Sites.Selected y el rol FullControl (Sites.Selected+FullControl), puede administrar los recursos dentro de esa colección de sitios.

Recurso	Permisos de recursos necesarios	Notas
sitio	Sites.FullControl.All	Dado que puede conceder permisos de control total a una colección de sitios mediante Sites.Selected, este requisito es necesariamente alto.
lista	Sites.FullControl.All, Sites.Selected+FullControl, Sites.Selected+Owner
listItem	Sites.FullControl.All, Sites.Selected+FullControl, Sites.Selected+Owner, Lists.SelectedOperations.Selected+FullControl, Lists.SelectedOperations.Selected+Owner
archivo	Sites.FullControl.All, Sites.Selected+FullControl, Sites.Selected+Owner, Lists.SelectedOperations.Selected+FullControl, Lists.SelectedOperations.Selected+Owner

Cómo se calcula el acceso

Hay dos tipos de tokens: solo aplicación y delegado. Los escenarios de solo aplicación no tienen ningún usuario presente y se consideran de mayor riesgo. Con delegado, la aplicación nunca puede superar los permisos existentes del usuario actual y se puede considerar de menor riesgo en muchos escenarios. Se prefiere delegar siempre que sea posible, pero ambos modos están disponibles para satisfacer sus necesidades.

Se almacena una tupla de identificador de aplicación, identificador de recurso y rol. Como tal, la [aplicación] tiene acceso [rol] al [recurso]. Especifique la aplicación y el rol cuando se cree un permiso a través de la API y la ruta de acceso resuelta le proporciona el recurso. Por ejemplo, la aplicación Z tiene acceso de lectura a la lista en /sites/dev/lists/list1.

Para calcular el acceso, use los valores proporcionados en el token para seguir aproximadamente este flujo:

1. Revise el tipo de token (aplicación o delegado).

2. Busque el registro de aplicación para el identificador de aplicación proporcionado en el recurso o un elemento primario jerárquico protegible (herencia).

3. Se produce una de las siguientes acciones:

   • Para el acceso a la aplicación, si se encuentra un registro para la aplicación y el rol permite la operación solicitada (leer un elemento, actualizar una lista), se concede acceso.
   • En el escenario delegado, tanto los permisos de aplicación como de usuario se calculan y, a continuación, se intersecan, lo que significa que la aplicación nunca puede superar los permisos del usuario y el usuario nunca puede superar (a través de la aplicación) los permisos de aplicación consentidos.

Notas del comportamiento del consentimiento

Las notas siguientes se aplican al comportamiento del consentimiento:

• Las aplicaciones pueden tener varios consentimientos seleccionados y esos consentimientos se pueden aplicar en varios niveles en todo el inquilino.
• El acceso a la aplicación se pierde en cuanto se revoca un ámbito. Si una aplicación tiene Lists.* y Sites.* y se le da acceso a una colección de sitios y a una lista específica de esa colección de sitios, y, a continuación, se revoca el consentimiento de Sites.*, la aplicación mantiene el acceso a la lista a la que se le dio acceso específico a través del consentimiento de Lists.* y la llamada anterior a list/permissions.
• Si una aplicación tiene permisos para una lista a través de una llamada a list/permissionsy el acceso se quita a través de una llamada a DELETE lists/permissions/id, pierde el acceso a esa lista y a todos los elementos de esa lista, independientemente de los permisos explícitos establecidos en esos elementos de lista. Posteriormente, puede regular permisos de elementos específicos si es necesario.
• Los ámbitos de nivel superior, como Sitios.* se pueden usar para conceder permisos específicos de archivo, pero los ámbitos inferiores nunca pueden proporcionar acceso a recursos de nivel superior. Esto permite que las aplicaciones tengan acceso a un nivel específico.
• El consentimiento es un concepto externo, consumido por OneDrive y SharePoint a través del token proporcionado, y se respetan los ámbitos presentados en el token.