Vue d’ensemble des autorisations sélectionnées dans OneDrive et SharePoint

SharePoint et OneDrive ont un modèle d’autorisations de longue date qui ne s’intègre pas exactement dans le modèle d’étendues. Par exemple, une étendue globale qui fournit un accès ReadWrite à une seule liste dans votre locataire n’existe pas. Au lieu de cela, les étendues sélectionnées prennent en charge ces scénarios. Initialement, Sites.Selected existait pour restreindre l’accès d’une application à une seule collection de sites. Désormais, les listes, les éléments de liste, les dossiers et les fichiers sont également pris en charge, et toutes les étendues sélectionnées prennent désormais en charge les modes délégués et d’application.

Remarque

En raison de l’évolution des exigences de nommage d’étendue, les étendues plus récentes sont répertoriées en tant que tuple *.SelectedOperations.Selectedcomplet . Il n’existe aucune différence fonctionnelle entre ce format et le Sites.Selected format.

Étendues

Le tableau suivant répertorie les étendues d’autorisation sélectionnées.

Étendues	Description
Sites.Selected	Gère l’accès aux applications au niveau de la collection de sites, en fournissant l’accès à une collection de sites spécifique
Lists.SelectedOperations.Selected	Gère l’accès aux applications au niveau de la liste, en fournissant l’accès à une liste spécifique
ListItems.SelectedOperations.Selected	Gère l’accès aux applications au niveau des fichiers, des éléments de liste ou des dossiers, en fournissant l’accès à un ou plusieurs éléments de liste
Files.SelectedOperations.Selected	Gère l’accès à l’application au niveau du dossier des fichiers ou des bibliothèques, en fournissant l’accès à un ou plusieurs fichiers

Fonctionnement des étendues sélectionnées avec les autorisations SharePoint et OneDrive

Lorsqu’un administrateur consent aux étendues sélectionnées pour une application, il délégue la gestion des autorisations de ressource aux propriétaires de cette ressource au sein de la charge de travail. Pour les autres étendues, telles que Files.Read.All, dès que l’étendue est autorisée, l’application peut accéder aux ressources qu’elle représente. Les étendues sélectionnées nécessitent une action d’affectation explicite ; une application autorisée pour Lists.SelectedOperations.Selected n’aurait initialement aucun accès.

Les étendues sélectionnées nécessitent une série d’étapes pour fonctionner, ce qui fournit plusieurs moyens de contrôle pour les administrateurs. L’exemple suivant utilise l’étendue Lists.SelectedOperations.Selected , mais les étapes s’appliquent à tous les *. Étendues sélectionnées.

1. L’application doit être autorisée dans l’ID Entra pour avoir l’application ou l’étendue déléguée Lists.SelectedOperations.Selected .
2. L’application doit se voir accorder des autorisations sur une liste via un appel à POST /sites/{siteid}/lists/{listid}/permissions avec un rôle spécifique.
3. L’application doit acquérir un jeton valide qui contient l’étendue Lists.SelectedOperations.Selected des appels à la liste autorisée.

Si l’une des trois étapes est manquée, l’application n’y a pas accès. Deux points de contrôle pour les administrateurs :

• Supprimez les autorisations sur une liste spécifique via un appel à DELETE /sites/{siteid}/lists/{listid}/permissions/{id}, ce qui supprime l’accès à la liste pour cette application.
• Révoquez le Lists.SelectedOperations.Selected consentement d’étendue dans l’ID Entra, ce qui empêche l’application d’accéder à toute liste pour laquelle des autorisations lui ont été précédemment accordées.

Sur cette base, vous pouvez donner à une application l’étendue Lists.SelectedOperations.Selected dans l’ID Entra, mais ne pas accorder d’autorisations à une liste, ce qui signifie que l’application n’a pas accès. De même, vous pouvez appeler POST /sites/{siteid}/lists/{listid}/permissions pour n’importe quelle application, mais si les étendues appropriées n’apparaissent pas dans le jeton, l’application n’a pas accès. Les trois étapes doivent être effectuées pour garantir l’accès attendu. Cela s’applique également à l’autre *. Étendues sélectionnées et leurs niveaux respectifs.

Remarque

L’attribution d’autorisations d’application à des listes, des éléments de liste, des dossiers ou des fichiers interrompt l’héritage sur la ressource affectée. Par conséquent, gardez à l’esprit les limites de service pour les autorisations uniques dans la conception de votre solution. Les autorisations au niveau de la collection de sites n’interrompent pas l’héritage, car il s’agit de la racine de l’héritage des autorisations.

Un exemple de définition d’autorisations est présenté pour les sites ; la logique est similaire pour les listes, les éléments de liste, les fichiers ou les dossiers.

Quelle est la différence entre les étendues fichiers et listItems ?

Dans SharePoint, tous les fichiers sont des éléments de liste, mais tous les éléments de liste ne sont pas des fichiers. Par conséquent, les applications qui portent l’étendue ListItems.SelectedOperations.Selected peuvent accéder à tous les éléments et fichiers de liste et les utiliser jusqu’à leur rôle autorisé. Les applications avec Files.SelectedOperations.Selected peuvent uniquement fonctionner sur des fichiers (éléments de liste) dans des bibliothèques de documents ou d’autres listes marquées comme contenant des documents. Cela imite le comportement Files.Read.All et Files.ReadWrite.All qui existe aujourd’hui, mais isolé dans un seul fichier. Ce comportement ne change pas en fonction du chemin d’accès Microsoft Graph utilisé, par exemple avec /drives/{driveid}/items/{itemid} et /sites/{siteid}/lists/{listid}/items/{itemid}; au lieu de cela, la destination à accéder contrôle le comportement.

Rôles

Le tableau suivant répertorie les quatre rôles qui peuvent être attribués à une application pour une ressource donnée.

Role	Description
read	Lisez les métadonnées et le contenu de la ressource.
write	Lisez et modifiez les métadonnées et le contenu de la ressource.
owner	Représente le rôle propriétaire.
fullcontrol	Représente le contrôle total de la ressource.

Demande

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#

// 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);

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

CLI

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

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

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)

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

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);

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

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);

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

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();

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

PowerShell

Import-Module Microsoft.Graph.Sites

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

New-MgSitePermission -SiteId $siteId -BodyParameter $params

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

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)

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

En-têtes de demande

Nom	Description
Autorisation	Porteur {token}. Obligatoire. En savoir plus sur l’authentification et l’autorisation.
Content-Type	application/json. Obligatoire.

Réponse

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"
      }
    }]
}

Pour obtenir des exemples qui montrent comment gérer les autorisations, consultez les rubriques d’API /permissions pour site, listItem et driveItem.

De quelles autorisations ai-je besoin pour gérer les autorisations ?

Les exigences d’autorisation varient selon le niveau. Dans tous les cas délégués, l’utilisateur actuel a également besoin d’autorisations suffisantes pour gérer l’accès en appelant l’API. Le tableau suivant inclut les étendues et les étendues + les rôles attribués à la ressource parente. Par exemple, si vous avez l’étendue Sites.Selected et le rôle FullControl (Sites.Selected+FullControl), vous pouvez gérer les ressources au sein de cette collection de sites.

Ressource	Autorisations de ressources requises	Notes
site	Sites.FullControl.All	Étant donné que vous pouvez accorder des autorisations de contrôle total à une collection de sites à l’aide de Sites.Selected, cette exigence est nécessairement élevée.
liste	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
file	Sites.FullControl.All, Sites.Selected+FullControl, Sites.Selected+Owner, Lists.SelectedOperations.Selected+FullControl, Lists.SelectedOperations.Selected+Owner

Comment l’accès est calculé

Il existe deux types de jetons : application uniquement et délégué. Les scénarios d’application uniquement n’ont aucun utilisateur présent et sont considérés comme à risque plus élevé. Avec délégué, l’application ne peut jamais dépasser les autorisations existantes de l’utilisateur actuel et peut être considérée comme à moindre risque dans de nombreux scénarios. Délégué est préférable lorsque cela est possible, mais les deux modes sont disponibles pour répondre à vos besoins.

Un tuple d’ID d’application, d’ID de ressource et de rôle est stocké. Par conséquent, [l’application] a [rôle] accès à la [ressource]. Vous spécifiez l’application et le rôle lorsqu’une autorisation est créée via l’API, et que le chemin d’accès résolu vous donne la ressource. Par exemple, l’application Z dispose d’un accès en lecture à la liste à l’adresse /sites/dev/lists/list1.

Pour calculer l’accès, utilisez les valeurs fournies dans le jeton pour suivre à peu près ce flux :

1. Passer en revue le type de jeton (application ou délégué).

2. Recherchez l’enregistrement d’application pour l’ID d’application fourni sur la ressource ou un parent hiérarchique sécurisable (héritage).

3. L’une des opérations suivantes se produit :

   • Pour l’accès à l’application, si un enregistrement est trouvé pour l’application et que le rôle autorise l’opération demandée (lire un élément, mettre à jour une liste), l’accès est accordé.
   • Dans le scénario délégué, les autorisations d’application et d’utilisateur sont calculées, puis croisées, ce qui signifie que l’application ne peut jamais dépasser les autorisations de l’utilisateur et que l’utilisateur ne peut jamais dépasser (via l’application) les autorisations d’application autorisées.

Remarques sur le comportement du consentement

Les remarques suivantes s’appliquent au comportement de consentement :

• Les applications peuvent avoir plusieurs consentements sélectionnés et ces consentements peuvent s’appliquer à différents niveaux dans le locataire.
• L’accès à l’application est perdu dès qu’une étendue est révoquée. Si une application possède Lists.* et Sites.* et qu’elle reçoit l’accès à une collection de sites et à une liste spécifique dans cette collection de sites, puis que le consentement Sites.* est révoqué, l’application conserve l’accès à la liste à laquelle elle a reçu un accès spécifique via le consentement Lists.* et l’appel précédent à list/permissions.
• Si une application dispose d’autorisations sur une liste via un appel à list/permissionset que l’accès est supprimé via un appel à DELETE lists/permissions/id, elle perd l’accès à cette liste et à tous les éléments de cette liste, indépendamment des autorisations explicites définies sur ces éléments de liste. Vous pouvez ultérieurement supprimer des autorisations d’élément spécifiques si nécessaire.
• Les étendues de niveau supérieur telles que Sites.* peuvent être utilisées pour accorder des autorisations spécifiques aux fichiers, mais les étendues inférieures ne peuvent jamais fournir l’accès à des ressources de niveau supérieur. Cela permet aux applications d’avoir accès à un niveau spécifique.
• Le consentement est un concept externe, utilisé par OneDrive et SharePoint via le jeton fourni, et toutes les étendues présentées dans le jeton sont respectées.