Visão geral das permissões selecionadas no OneDrive e no SharePoint

O SharePoint e o OneDrive têm um modelo de permissões estabelecido há muito tempo que não se encaixa exatamente no modelo de escopos. Por exemplo, não existe um escopo global que fornece acesso ReadWrite a uma única lista em seu locatário. Em vez disso, os escopos selecionados dão suporte a esses cenários. Inicialmente, Sites.Selected existia para restringir o acesso de um aplicativo a um único conjunto de sites. Agora, listas, itens de lista, pastas e arquivos também têm suporte, e todos os escopos selecionados agora dão suporte aos modos delegado e de aplicativo.

Scopes

A tabela a seguir lista os escopos de permissão selecionados.

Como os escopos selecionados funcionam com permissões do SharePoint e do OneDrive

Quando um administrador consente com escopos selecionados para um aplicativo, ele delega o gerenciamento de permissões de recurso aos proprietários desse recurso dentro da carga de trabalho. Para outros escopos, como Files. Read.All, assim que o escopo for consentido, o aplicativo poderá acessar os recursos que ele representa. Os escopos selecionados exigem uma ação de atribuição explícita; um aplicativo consentido para Lists.SelectedOperations.Selected inicialmente não teria acesso.

Escopos selecionados exigem uma série de etapas para funcionar, o que fornece vários meios de controle para os administradores. O exemplo a seguir usa o Lists.SelectedOperations.Selected escopo, mas as etapas se aplicam a todos *. Escopos selecionados.

1. O aplicativo deve ser consentido na ID de Entra para ter o escopo do aplicativo ou delegadoLists.SelectedOperations.Selected.
2. O aplicativo deve receber permissões para uma lista por meio de uma chamada para POST /sites/{siteid}/lists/{listid}/permissions com uma função específica.
3. O aplicativo deve adquirir um token válido que contenha o Lists.SelectedOperations.Selected escopo para chamadas para a lista de permissões.

Se alguma das três etapas for perdida, o aplicativo não terá acesso. Administradores: dois pontos de controle:

• Remova as permissões em uma lista específica por meio de uma chamada para , o DELETE /sites/{siteid}/lists/{listid}/permissions/{id}que remove o acesso à lista para esse aplicativo.
• Revogue o Lists.SelectedOperations.Selected consentimento do escopo no ID de Entra, o que impede o acesso do aplicativo a qualquer lista para a qual ele tenha recebido permissões anteriormente.

Com base nisso, você pode consentir um aplicativo com o Lists.SelectedOperations.Selected escopo no Entra ID, mas não conceder permissões a nenhuma lista - o que significa que o aplicativo não tem acesso. Da mesma forma, você pode chamar POST /sites/{siteid}/lists/{listid}/permissions qualquer aplicativo, mas sem os escopos adequados aparecendo no token, o aplicativo não tem acesso. Todas as três etapas devem ser concluídas para garantir o acesso esperado. Isso também se aplica ao outro *. Escopos selecionados e seus respectivos níveis.

Um exemplo de definição de permissões é mostrado para sites; A lógica é semelhante para listas, itens de lista, arquivos ou pastas.

Qual é a diferença entre os escopos de arquivos e listItems?

No SharePoint, todos os arquivos são itens de lista, mas nem todos os itens de lista são arquivos. Como resultado, os aplicativos que carregam o ListItems.SelectedOperations.Selected escopo podem acessar e operar em todos os itens de lista e arquivos até sua função permitida. Aplicativos com Files.SelectedOperations.Selected só podem operar em arquivos (itens de lista) dentro de bibliotecas de documentos ou outras listas marcadas como contendo documentos. Isso imita o Files. Read.All e Files. ReadWrite.All que existe hoje, mas isolado em um único arquivo. Esse comportamento não muda com base no caminho do Microsoft Graph usado, como com /drives/{driveid}/items/{itemid} e /sites/{siteid}/lists/{listid}/items/{itemid}; em vez disso, o destino a ser acessado controla o comportamento.

Funções

A tabela a seguir lista as quatro funções que podem ser atribuídas a um aplicativo para um determinado recurso.

Solicitação

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

{
  "roles": ["write"],
  "grantedToIdentities": [{
    "application": {
      "id": "89ea5c94-7736-4e25-95ad-3fa95f62b66e",
      "displayName": "Contoso Time Manager App"
    }
  }]
}

// 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",
	},
	GrantedToIdentities = new List<IdentitySet>
	{
		new IdentitySet
		{
			Application = new Identity
			{
				Id = "89ea5c94-7736-4e25-95ad-3fa95f62b66e",
				DisplayName = "Contoso Time Manager App",
			},
		},
	},
};

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

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


identitySet := graphmodels.NewIdentitySet()
application := graphmodels.NewIdentity()
id := "89ea5c94-7736-4e25-95ad-3fa95f62b66e"
application.SetId(&id) 
displayName := "Contoso Time Manager App"
application.SetDisplayName(&displayName) 
identitySet.SetApplication(application)

grantedToIdentities := []graphmodels.IdentitySetable {
	identitySet,
}
requestBody.SetGrantedToIdentities(grantedToIdentities)

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

// 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);
LinkedList<IdentitySet> grantedToIdentities = new LinkedList<IdentitySet>();
IdentitySet identitySet = new IdentitySet();
Identity application = new Identity();
application.setId("89ea5c94-7736-4e25-95ad-3fa95f62b66e");
application.setDisplayName("Contoso Time Manager App");
identitySet.setApplication(application);
grantedToIdentities.add(identitySet);
permission.setGrantedToIdentities(grantedToIdentities);
Permission result = graphClient.sites().bySiteId("{site-id}").permissions().post(permission);

const options = {
	authProvider,
};

const client = Client.init(options);

const permission = {
  roles: ['write'],
  grantedToIdentities: [{
    application: {
      id: '89ea5c94-7736-4e25-95ad-3fa95f62b66e',
      displayName: 'Contoso Time Manager App'
    }
  }]
};

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

<?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', 	]);
$grantedToIdentitiesIdentitySet1 = new IdentitySet();
$grantedToIdentitiesIdentitySet1Application = new Identity();
$grantedToIdentitiesIdentitySet1Application->setId('89ea5c94-7736-4e25-95ad-3fa95f62b66e');
$grantedToIdentitiesIdentitySet1Application->setDisplayName('Contoso Time Manager App');
$grantedToIdentitiesIdentitySet1->setApplication($grantedToIdentitiesIdentitySet1Application);
$grantedToIdentitiesArray []= $grantedToIdentitiesIdentitySet1;
$requestBody->setGrantedToIdentities($grantedToIdentitiesArray);


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

Import-Module Microsoft.Graph.Sites

$params = @{
	roles = @(
	"write"
)
grantedToIdentities = @(
	@{
		application = @{
			id = "89ea5c94-7736-4e25-95ad-3fa95f62b66e"
			displayName = "Contoso Time Manager App"
		}
	}
)
}

New-MgSitePermission -SiteId $siteId -BodyParameter $params

# 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_identities = [
		IdentitySet(
			application = Identity(
				id = "89ea5c94-7736-4e25-95ad-3fa95f62b66e",
				display_name = "Contoso Time Manager App",
			),
		),
	],
)

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

Cabeçalhos de solicitação

Resposta

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 obter exemplos que mostram como gerenciar permissões, consulte os tópicos da /permissions API para site, list, listItem e driveItem.

Quais permissões preciso para gerenciar permissões?

Os requisitos de permissão variam de acordo com o nível. Em todos os casos delegados, o usuário atual também precisa de permissões suficientes para gerenciar o acesso chamando a API. A tabela a seguir inclui escopos e escopos + funções atribuídas ao recurso pai. Por exemplo, se você tiver o escopo Sites.Selected E a função FullControl (Sites.Selected+FullControl), poderá gerenciar recursos nesse conjunto de sites.

Como o acesso é calculado

Há dois tipos de tokens: somente aplicativo e delegado. Os cenários somente de aplicativo não têm usuário presente e são considerados de maior risco. Com delegado, o aplicativo nunca pode exceder as permissões existentes do usuário atual e pode ser considerado de menor risco para muitos cenários. Delegado é preferencial quando possível, mas ambos os modos estão disponíveis para atender às suas necessidades.

Uma tupla de ID do aplicativo, ID do recurso e função é armazenada. Como tal, o [aplicativo] tem acesso [função] ao [recurso]. Você especifica o aplicativo e a função quando uma permissão é criada por meio da API, e o caminho resolvido fornece o recurso. Por exemplo, o aplicativo Z tem acesso de leitura à lista em /sites/dev/lists/list1.

Para calcular o acesso, use os valores fornecidos no token para seguir aproximadamente este fluxo:

1. Examinar tipo de token (aplicativo ou delegado).

2. Localize o registro do aplicativo para a ID do aplicativo fornecido no recurso ou em um pai hierárquico protegível (herança).

3. Ocorre uma das seguintes situações:

   • Para acesso ao aplicativo, se um registro for encontrado para o aplicativo e a função permitir a operação solicitada (ler um item, atualizar uma lista), o acesso será concedido.
   • No cenário delegado, as permissões do aplicativo e do usuário são calculadas e, em seguida, cruzadas, o que significa que o aplicativo nunca pode exceder as permissões do usuário e o usuário nunca pode exceder (por meio do aplicativo) as permissões de aplicativo consentidas.

Anotações de comportamento de consentimento

As observações a seguir se aplicam ao comportamento de consentimento:

• Os aplicativos podem ter vários consentimentos selecionados e esses consentimentos podem ser aplicados em vários níveis no locatário.
• O acesso ao aplicativo é perdido assim que um escopo é revogado. Se um aplicativo tiver Listas.* e Sites.* e receber acesso a um conjunto de sites e a uma lista específica nesse conjunto de sites e, em seguida, o consentimento Sites.* for revogado, o aplicativo manterá o acesso à lista à qual recebeu acesso específico por meio do consentimento Listas.* e a chamada anterior para list/permissions.
• Se um aplicativo tiver permissões para uma lista por meio de uma chamada para list/permissions, e o acesso for removido por meio de uma chamada para DELETE lists/permissions/id, ele perderá o acesso a essa lista e a todos os itens dessa lista, independentemente de quaisquer permissões explícitas definidas nesses itens da lista. Posteriormente, você poderá conceder novamente permissões de itens específicos, se necessário.
• Escopos de nível superior, como Sites.*, podem ser usados para conceder permissões específicas de arquivos, mas escopos mais baixos nunca podem fornecer acesso a recursos de nível superior. Isso permite que os aplicativos tenham acesso em um nível específico.
• O consentimento é um conceito externo, consumido pelo OneDrive e pelo SharePoint por meio do token fornecido, e todos os escopos apresentados no token são respeitados.