Descrição geral das permissões do Microsoft Graph

Antes de o plataforma de identidade da Microsoft poder autorizar a sua aplicação a aceder aos dados na cloud da Microsoft, a aplicação tem de ter os privilégios de que precisa. Da mesma forma, antes de o plataforma de identidade da Microsoft poder autorizar a sua aplicação a aceder aos dados através do Microsoft Graph, a aplicação tem de ter os privilégios necessários.

Uma forma de conceder a uma aplicação os privilégios de que precisa para aceder e trabalhar com os seus dados através do Microsoft Graph é atribuindo-lhe permissões do Microsoft Graph. Outra forma é através de sistemas de controlo de acesso baseado em funções (RBAC), como Microsoft Entra RBAC. Em alguns casos, o acesso aos dados através das APIs do Microsoft Graph pode exigir permissões do Microsoft Graph e permissões RBAC.

Este artigo apresenta as permissões do Microsoft Graph e fornece orientações para as utilizar. Para ver a lista completa de permissões que o Microsoft Graph expõe, veja a referência de permissões do Microsoft Graph.

Para saber mais sobre como funcionam as permissões, watch o seguinte vídeo.

Tipo de permissão

O Microsoft Graph suporta dois cenários de acesso, acesso delegado e acesso apenas à aplicação. No acesso delegado, a aplicação chama o Microsoft Graph em nome de um utilizador com sessão iniciada. No acesso apenas à aplicação, a aplicação chama o Microsoft Graph com a sua própria identidade, sem um utilizador com sessão iniciada.

Para suportar estes cenários de acesso, o Microsoft Graph expõe permissões delegadas e permissões de aplicação.

Permissões delegadas

As permissões delegadas, também denominadasâmbitos, são utilizadas no cenário de acesso delegado. São permissões que permitem que a aplicação atue em nome de um utilizador com sessão iniciada. No entanto, a aplicação não consegue aceder a nada ao qual o utilizador com sessão iniciada não tenha conseguido aceder.

Por exemplo, foi concedida a uma aplicação a permissão Files.Read.All delegated em nome do Tom, um utilizador. A aplicação só pode ler todos os ficheiros na organização aos quais o Tom já pode aceder. O Tom poderá aceder aos ficheiros porque tem permissões através de uma das seguintes formas:

• O Tom criou ou é o proprietário dos ficheiros.
• Os ficheiros foram partilhados diretamente com o Tom ou partilhados indiretamente através de uma associação de equipa ou grupo.
• O Tom recebeu permissões através de um sistema RBAC suportado.

Por conseguinte, num cenário delegado, os privilégios que uma aplicação tem de agir em nome de um utilizador são determinados pelas permissões do Microsoft Graph que a aplicação foi concedida e pelas próprias permissões do utilizador.

Num cenário de acesso delegado, uma aplicação pode permitir que os utilizadores iniciem sessão com as respetivas contas Microsoft pessoais, como Outlook.com, contas escolares ou profissionais ou permitir ambos os tipos de conta. Todas as permissões delegadas são válidas para contas escolares ou profissionais, mas nem todas são válidas para contas Microsoft pessoais. Utilize a referência de permissões do Microsoft Graph para identificar permissões delegadas válidas para contas Microsoft pessoais.

Quando um utilizador inicia sessão numa aplicação, ou, em alguns casos, um administrador, tem a oportunidade de consentir as permissões delegadas. Se concederem consentimento, a aplicação pode aceder a recursos e APIs dentro dos limites das permissões do utilizador.

Permissões de aplicativos

As permissões de aplicação, também denominadas funções de aplicação, são utilizadas no cenário de acesso apenas à aplicação, sem um utilizador com sessão iniciada presente. A aplicação consegue aceder a quaisquer dados aos quais a permissão esteja associada. Por exemplo, uma aplicação que concedeu a permissão Files.Read.All application pode ler qualquer ficheiro na organização.

Para aplicações que acedem a recursos e APIs sem um utilizador com sessão iniciada, um administrador consente as permissões da aplicação quando a aplicação é instalada no inquilino ou através do centro de administração do Microsoft Entra. Apenas o Administrador de Funções Privilegiadas e o Administrador Global podem dar consentimento às permissões da aplicação.

Para além de terem sido atribuídas permissões de aplicação do Microsoft Graph, também pode ser concedido a uma aplicação os privilégios de que precisa através de uma das seguintes condições:

• Quando é atribuída à aplicação a propriedade do recurso que pretende gerir.
• Quando a aplicação é atribuída permissões através de um sistema RBAC ou funções administrativas personalizadas.

Comparação de permissões delegadas e de aplicativo

A imagem seguinte ilustra os privilégios de uma aplicação em cenários de acesso delegado vs. apenas aplicações.

Padrão de nomenclatura de permissões

O Microsoft Graph expõe permissões granulares que o ajudam a controlar o acesso que as aplicações têm aos recursos do Microsoft Graph, como utilizadores, grupos e correio. Estas permissões têm o nome no seguinte padrão:

{resource}. {operation}. {constraint}

Exemplos:

• User.Read - Permite que a aplicação leia informações sobre o utilizador com sessão iniciada.
• Application.ReadWrite.All - Permite que a aplicação faça a gestão de todas as aplicações no inquilino.
• Application.ReadWrite.OwnedBy – permite que a aplicação faça a gestão apenas das aplicações que cria ou possui.
• Group.Create – permite que a aplicação crie novos grupos, mas não os modifique ou elimine.
• Member.Read.Hidden - Permite que a aplicação leia associações ocultas

Para obter a lista completa de permissões expostas pelo Microsoft Graph, veja a referência de permissões do Microsoft Graph.

Permissões de consentimento específico do recurso (RSC)

O RSC é uma arquitetura de autorização que permite conceder acesso limitado aos dados expostos por um recurso. Através do RSC, um utilizador autorizado pode conceder a uma aplicação acesso aos dados de uma instância específica de um tipo de recurso. Não precisam de conceder acesso à aplicação a todas as instâncias do tipo de recurso em todo o inquilino.

As permissões RSC também estão disponíveis para consentimento e são suportadas apenas por um subconjunto de funcionalidades disponíveis através do Microsoft Graph, como o Teams, conversas e mensagens. Saiba mais sobre as permissões RSC ou descubra a lista completa de permissões RSC disponíveis.

Informações limitadas retornadas para objetos membro inacessíveis

Objetos de contêiner, como grupos, oferecem suporte a membros de vários tipos; por exemplo, usuários e dispositivos. Quando uma aplicação com os privilégios certos consulta a associação de um objeto de contentor, recebe uma 200 OK resposta e uma coleção de objetos. No entanto, se a aplicação não tiver permissões para ler um determinado tipo de objeto no contentor, os objetos desse tipo são devolvidos, mas com informações limitadas, por exemplo, apenas o tipo de objeto e o ID podem ser devolvidos e outras propriedades são indicadas como null. São devolvidas informações completas para os tipos de objetos que a aplicação tem permissões para ler.

Este princípio é aplicado a todas as relações do tipo directoryObject . Os exemplos incluem /groups/{id}/members, /users/{id}/memberOfe me/ownedObjects.

Por exemplo, um grupo pode ter utilizadores, grupos, aplicações, principais de serviço, dispositivos e contactos como membros. É concedida a uma aplicação a permissão GroupMember.Read.All least privileged para Membros do grupo de lista. No objeto de resposta, apenas as propriedades ID e @odata.type são preenchidas para todos os membros que são devolvidos. As outras propriedades são indicadas como null. Para esta API:

• Para ler as propriedades básicas dos membros de um grupo que são utilizadores, a aplicação precisa, pelo menos, da permissão User.ReadBasic.All .
• Para ler as propriedades básicas dos membros de um grupo que são grupos, a aplicação precisa, pelo menos, da permissão GroupMember.Read.All .
• Para ler as propriedades básicas dos membros de um grupo que são dispositivos, a aplicação precisa, pelo menos, da permissão Device.Read.All , etc.
• No entanto, como alternativa às permissões individuais ao nível do recurso, a aplicação pode ser atribuída, pelo menos, a permissão Directory.Read.All para ler todas as propriedades de todos os tipos de membros.

Exemplo

Solicitação

GET https://graph.microsoft.com/v1.0/groups/{id}/members

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

// To initialize your graphClient, see https://video2.skills-academy.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups["{group-id}"].Members.GetAsync();

mgc groups members list --group-id {group-id}

// 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"
	  //other-imports
)


// To initialize your graphClient, see https://video2.skills-academy.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
members, err := graphClient.Groups().ByGroupId("group-id").Members().Get(context.Background(), nil)

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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

DirectoryObjectCollectionResponse result = graphClient.groups().byGroupId("{group-id}").members().get();

const options = {
	authProvider,
};

const client = Client.init(options);

let members = await client.api('/groups/{id}/members')
	.get();

<?php
use Microsoft\Graph\GraphServiceClient;


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


$result = $graphServiceClient->groups()->byGroupId('group-id')->members()->get()->wait();

Import-Module Microsoft.Graph.Groups

Get-MgGroupMember -GroupId $groupId

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://video2.skills-academy.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

result = await graph_client.groups.by_group_id('group-id').members.get()

Resposta

O objeto seguinte é um exemplo da resposta:

{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#directoryObjects",
    "value":[
        {
            "@odata.type":"#microsoft.graph.user",
            "id":"69d035a3-29c9-469f-809d-d21a4ae69e65",
            "displayName":"Adele Vance",
            "createdDateTime":"2019-09-18T09:06:51Z",
        },
        {
            "@odata.type":"#microsoft.graph.group",
            "id":"c43a7cc9-2d95-44b6-bf6a-6392e41949b4",
            "displayName":"All Company",
            "description":null,
            "createdDateTime":"2019-10-24T01:34:35Z"
        },
        {
            "@odata.type":"#microsoft.graph.device",
            "id": "d282309e-f91d-43b6-badb-9e68aa4b4fc8",
            "accountEnabled":null,
            "deviceId":null,
            "displayName":null,
            "operatingSystem":null,
            "operatingSystemVersion":null
        }
    ]
}

Melhores práticas para utilizar permissões do Microsoft Graph

O Microsoft Graph expõe permissões granulares que permitem que uma aplicação solicite apenas as permissões necessárias para funcionar. As permissões granulares permitem-lhe aplicar o princípio de menor privilégio ao atribuir e conceder permissões a uma aplicação, ao conceder à aplicação a permissão mínima necessária para a operação.

Considere os seguintes exemplos:

• Uma aplicação só precisa de ler as informações de perfil do utilizador com sessão iniciada. A aplicação requer apenas a permissão User.Read , que é a permissão com menos privilégios para aceder às informações do utilizador com sessão iniciada. Conceder a permissão User.ReadWrite à aplicação torna-a sobre-privilegiada porque a aplicação não precisa de atualizar o perfil do utilizador.
• Uma aplicação tem de ler os grupos no inquilino sem um utilizador com sessão iniciada. A aplicação requer apenas a permissão de aplicação GroupMember.Read.All , que é a permissão com menos privilégios para ler grupos no inquilino sem um utilizador com sessão iniciada.
• Uma aplicação tem de ler ou escrever num calendário do utilizador com sessão iniciada. A aplicação gere tarefas dinâmicas e sincroniza a partir do calendário do Outlook do utilizador para manter a aplicação atualizada para agendar tarefas para o utilizador. Embora a obtenção dos dados do calendário do utilizador necessite de Calendários.Ler, atualizar o calendário com tarefas agendadas requer uma permissão com privilégios superior, Calendars.ReadWrite. Neste caso, a aplicação deve pedir Calendars.ReadWrite.

Conceder mais privilégios a uma aplicação do que precisa é uma má prática de segurança que aumenta a superfície de ataque da aplicação e a expõe a um acesso não autorizado e não intencional a dados ou operações. Além disso, pedir mais permissões do que o necessário pode fazer com que os utilizadores se abstenham de consentir com uma aplicação, afetando a adoção e a utilização de uma aplicação.

Aplique o princípio de menor privilégio ao atribuir e conceder permissões do Microsoft Graph a uma aplicação. Para obter mais informações, veja Melhorar a segurança com o princípio de menor privilégio e Criar aplicações que protegem a identidade através de permissões e consentimento.

Permissões a utilizar com cuidado

Algumas permissões do Microsoft Graph concedem acesso a um leque mais vasto de dados ou operações do que outras. Utilize estas permissões com cuidado. Por exemplo, a permissão Directory.AccessAsUser.All é a permissão delegada com privilégios mais elevado que concede acesso a quase todas as operações de API em Microsoft Entra ID. A permissão Directory.ReadWrite.All é a segunda na classificação de privilégios. Directory.Read.All é a permissão só de leitura com privilégios mais elevados para recursos Microsoft Entra ID. Estas permissões devem ser utilizadas com cuidado e apenas quando necessário. Utilize sempre permissões de opções com privilégios inferiores.

Na documentação de referência da API relativa a recursos Microsoft Entra ID, algumas destas permissões com privilégios superiores podem ser intencionalmente excluídas do índice de permissões suportado para aceder à API.

Além disso, a função de Administrador Global é a função incorporada com privilégios mais elevados no Microsoft Entra ID. Na documentação de referência da API, esta função é intencionalmente excluída da lista de funções suportadas para aceder à API a favor de funções com privilégios menores.

Limites de permissões solicitadas por aplicativo

Microsoft Entra ID limita o número de permissões que podem ser pedidas e consentidas por uma aplicação cliente. Estes limites dependem do signInAudience valor de uma aplicação, mostrado no manifesto da aplicação.

Obter IDs de permissão através do Microsoft Graph

Para definir permissões com a CLI do Azure, o PowerShell ou a infraestrutura como estruturas de código, poderá precisar do identificador para a permissão que pretende utilizar em vez do nome. A referência de permissões lista os IDs de todas as permissões do Microsoft Graph. Em alternativa, pode ler informações sobre todas as permissões do Microsoft Graph programaticamente através da API Get servicePrincipal no Microsoft Graph. O exemplo a seguir mostra uma solicitação.

GET https://graph.microsoft.com/v1.0/servicePrincipals(appId='00000003-0000-0000-c000-000000000000')?$select=id,appId,displayName,appRoles,oauth2PermissionScopes,resourceSpecificApplicationPermissions

Os objetos appRoles, oauth2PermissionScopes e resourceSpecificApplicationPermissions armazenam as permissões de consentimento da aplicação, delegadas e específicas do recurso, respetivamente.

Conteúdo relacionado

• Referência de permissões do Microsoft Graph.
• Descrição geral do controlo de acesso baseado em funções no Microsoft Entra ID.
• Compreender o acesso delegado