Descrição geral das Permissões selecionadas no OneDrive e no SharePoint

O SharePoint e o OneDrive têm um modelo de permissões há muito estabelecido que não se enquadra exatamente no modelo de âmbitos. Por exemplo, não existe um âmbito global que forneça acesso ReadWrite a uma única lista no seu inquilino. Em vez disso, os Âmbitos selecionados suportam estes cenários. Inicialmente, Sites.Selected existia para restringir o acesso de uma aplicação a uma única coleção de sites. Agora, as listas, itens de lista, pastas e ficheiros também são suportados e todos os Âmbitos selecionados suportam agora modos delegados e de aplicação.

Scopes

A tabela seguinte lista os âmbitos de permissão Selecionados.

Como funcionam os Âmbitos selecionados com as permissões do SharePoint e do OneDrive

Quando um administrador consente os Âmbitos selecionados de uma aplicação, está a delegar a gestão de permissões de recursos aos proprietários desse recurso na carga de trabalho. Para outros âmbitos, como Files.Read.All, assim que o âmbito for consentido, a aplicação pode aceder aos recursos que representa. Os âmbitos selecionados requerem uma ação de atribuição explícita; uma aplicação consentida para Listas. SelectedOperations.Selected inicialmente não teria acesso.

Os âmbitos selecionados requerem uma série de passos para funcionar, o que fornece vários meios de controlo para os administradores. O exemplo seguinte utiliza o Lists.SelectedOperations.Selected âmbito, mas os passos aplicam-se a todos *. Âmbitos selecionados.

1. A aplicação tem de ser consentida no Entra ID para ter a aplicação ou o âmbito delegadoLists.SelectedOperations.Selected.
2. A aplicação tem de ter permissões para uma lista através de uma chamada para POST /sites/{siteid}/lists/{listid}/permissions com uma função específica.
3. A aplicação tem de adquirir um token válido que contenha o Lists.SelectedOperations.Selected âmbito das chamadas para a lista de permissões.

Se algum dos três passos não for apresentado, a aplicação não tem acesso. Administradores com dois pontos de controlo:

• Remova as permissões numa lista específica através de uma chamada para DELETE /sites/{siteid}/lists/{listid}/permissions/{id}, que remove o acesso à lista dessa aplicação.
• Revogar o consentimento do Lists.SelectedOperations.Selected âmbito no Entra ID, o que bloqueia o acesso da aplicação a qualquer lista à qual lhe foram concedidas permissões anteriormente.

Com base nisto, pode dar consentimento a uma aplicação Lists.SelectedOperations.Selected no âmbito no Entra ID, mas não conceder permissões a nenhuma lista, o que significa que a aplicação não tem acesso. Da mesma forma, pode chamar POST /sites/{siteid}/lists/{listid}/permissions qualquer aplicação, mas sem os âmbitos adequados aparecerem no token, a aplicação não tem acesso. Os três passos têm de ser concluídos para garantir o acesso esperado. Isto também se aplica ao outro *. Âmbitos selecionados e respetivos níveis.

É apresentado um exemplo de definição de permissões para sites; a lógica é semelhante para listas, itens de lista, ficheiros ou pastas.

Qual é a diferença entre os ficheiros e os âmbitos listItems?

No SharePoint, todos os ficheiros são itens de lista, mas todos os itens de lista não são ficheiros. Como resultado, as aplicações com o ListItems.SelectedOperations.Selected âmbito podem aceder e operar em todos os itens de lista e ficheiros até à respetiva função permitida. As aplicações com Files.SelectedOperations.Selected só podem operar em ficheiros (itens de lista) em bibliotecas de documentos ou noutras listas marcadas como contendo documentos. Isto imita o comportamento Files.Read.All e Files.ReadWrite.All que existe atualmente, mas isolado num único ficheiro. Este comportamento não é alterado com base no caminho do Microsoft Graph utilizado, como com /drives/{driveid}/items/{itemid} e /sites/{siteid}/lists/{listid}/items/{itemid}; em vez disso, o destino a ser acedido controla o comportamento.

Funções

A tabela seguinte lista as quatro funções que podem ser atribuídas a uma aplicação para um determinado recurso.

Solicitação

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

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

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

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

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

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

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

Import-Module Microsoft.Graph.Sites

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

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 = IdentitySet(
		application = Identity(
			id = "89ea5c94-7736-4e25-95ad-3fa95f62b66e",
		),
	),
)

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 gerir permissões, veja os tópicos da /permissions API para site, lista, listItem e driveItem.

De que permissões preciso para gerir as permissões?

Os requisitos de permissão variam consoante o nível. Em todos os casos delegados, o utilizador atual também precisa de permissões suficientes para gerir o acesso ao chamar a API. A tabela seguinte inclui âmbitos e âmbitos + funções atribuídas ao recurso principal. Por exemplo, se tiver a função Sites.Selected scope AND FullControl (Sites.Selected+FullControl), pode gerir recursos nessa coleção de sites.

Como o acesso é calculado

Existem dois tipos de tokens: apenas aplicação e delegados. Os cenários apenas da aplicação não têm nenhum utilizador presente e são considerados de maior risco. Com a delegação, a aplicação nunca pode exceder as permissões existentes do utilizador atual e pode ser considerada de menor risco para muitos cenários. A opção Delegada é preferencial sempre que possível, mas ambos os modos estão disponíveis para satisfazer as suas necessidades.

É armazenada uma cadeia de identificação do ID da aplicação, do ID do recurso e da função. Como tal, a [aplicação] tem acesso [de função] ao [recurso]. Especifica a aplicação e a função quando é criada uma permissão através da API e o caminho resolvido dá-lhe o recurso. Por exemplo, a aplicação Z tem acesso de leitura à lista em /sites/dev/lists/list1.

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

1. Reveja o tipo de token (aplicação ou delegado).

2. Localize o registo da aplicação para o ID da aplicação fornecido no recurso ou um elemento principal hierárquico com segurança (herança).

3. Ocorre uma das seguintes situações:

   • Para o acesso à aplicação, se for encontrado um registo para a aplicação e a função permitir a operação pedida (ler um item, atualizar uma lista), é concedido acesso.
   • No cenário delegado, as permissões da aplicação e do utilizador são calculadas e, em seguida, interseccionadas, o que significa que a aplicação nunca pode exceder as permissões do utilizador e o utilizador nunca pode exceder (através da aplicação) as permissões de aplicação consentidas.

Notas de comportamento de consentimento

As notas seguintes aplicam-se ao comportamento de consentimento:

• As aplicações podem ter vários Consentimentos selecionados e esses consentimentos podem ser aplicados a vários níveis em todo o inquilino.
• O acesso à aplicação é perdido assim que um âmbito é revogado. Se uma aplicação tiver Listas.* e Sites.* e tiver acesso a uma coleção de sites e a uma lista específica nessa coleção de sites e, em seguida, o consentimento sites.* for revogado, a aplicação mantém o acesso à lista à qual lhe foi concedido acesso específico através do consentimento Listas.* e da chamada anterior para list/permissions.
• Se uma aplicação tiver permissões para uma lista através de uma chamada para list/permissionse o acesso for removido através de uma chamada para DELETE lists/permissions/id, perderá o acesso a essa lista e a todos os itens nessa lista, independentemente de quaisquer permissões explícitas definidas nesses itens de lista. Posteriormente, pode regrar permissões de itens específicas, se necessário.
• Os âmbitos de nível superior, como Sites.* podem ser utilizados para conceder permissões específicas de ficheiros, mas os âmbitos inferiores nunca podem fornecer acesso a recursos de nível superior. Isto permite que as aplicações tenham acesso a um nível específico.
• O consentimento é um conceito externo, consumido pelo OneDrive e pelo SharePoint através do token fornecido e todos os âmbitos apresentados no token são respeitados.