Visão geral das permissões do Microsoft Graph

Antes que o plataforma de identidade da Microsoft possa autorizar seu aplicativo a acessar dados na nuvem da Microsoft, o aplicativo deve receber os privilégios necessários. Da mesma forma, antes que o plataforma de identidade da Microsoft possa autorizar seu aplicativo a acessar dados por meio do Microsoft Graph, o aplicativo deve receber os privilégios necessários.

Uma maneira de conceder a um aplicativo os privilégios necessários para acessar e trabalhar com seus dados por meio do Microsoft Graph é atribuindo-lhe permissões do Microsoft Graph.

Este artigo apresenta permissões do Microsoft Graph e fornece diretrizes para usá-las. Para ver a lista completa de permissões que o Microsoft Graph expõe, consulte a referência de permissões do Microsoft Graph.

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

Tipo de permissão

O Microsoft Graph dá suporte a dois cenários de acesso, acesso delegado e acesso somente a aplicativos. No acesso delegado, o aplicativo chama o Microsoft Graph em nome de um usuário conectado. No acesso somente aplicativo, o aplicativo chama o Microsoft Graph com sua própria identidade, sem um usuário conectado.

Para dar suporte a esses cenários de acesso, o Microsoft Graph expõe permissões delegadas e permissões de aplicativo.

Permissões delegadas

As permissões delegadas, também chamadas de escopos, são usadas no cenário de acesso delegado. São permissões que permitem que o aplicativo atue em nome de um usuário conectado. No entanto, o aplicativo nunca poderá acessar nada que o usuário conectado não pôde acessar.

Por exemplo, um aplicativo recebeu a permissão delegado Files.Read.All em nome de Tom, um usuário. O aplicativo só poderá ler todos os arquivos na organização que Tom já pode acessar. Tom pode ser capaz de acessar os arquivos porque ele tem permissões através de uma das seguintes maneiras:

• Tom criou ou é dono dos arquivos.
• Os arquivos foram compartilhados diretamente com Tom ou compartilhados indiretamente com ele por meio de uma equipe ou associação de grupo.
• Tom recebeu permissões por meio de um sistema RBAC (controle de acesso baseado em função), como Microsoft Entra RBAC.

Portanto, em um cenário delegado, os privilégios que um aplicativo precisa agir em nome de um usuário são determinados pelas permissões do Microsoft Graph que o aplicativo recebeu e pelas próprias permissões do usuário.

Em um cenário de acesso delegado, um aplicativo pode permitir que os usuários entrem com suas contas pessoais da Microsoft, como Outlook.com, contas corporativas ou escolares ou permitir ambos os tipos de conta. Todas as permissões delegadas são válidas para contas corporativas ou escolares, mas nem todas são válidas para contas pessoais da Microsoft. Use a referência de permissões do Microsoft Graph para identificar permissões delegadas válidas para contas pessoais da Microsoft.

Quando um usuário entra em um aplicativo, ele ou, em alguns casos, um administrador tem a chance de consentir com as permissões delegadas. Se eles concederem o consentimento, o aplicativo poderá acessar recursos e APIs dentro dos limites das permissões do usuário.

Observação

As permissões concedidas por meio de Microsoft Entra funções internas não limitam o aplicativo a chamar somente APIs do Microsoft Graph.

Permissões de aplicativos

As permissões de aplicativo, também chamadas de funções de aplicativo, são usadas no cenário de acesso somente aplicativo, sem um usuário conectado presente. O aplicativo poderá acessar todos os dados aos quais a permissão está associada. Por exemplo, um aplicativo que concedeu a permissão de aplicativo Files.Read.All poderá ler qualquer arquivo na organização.

Para aplicativos que acessam recursos e APIs sem um usuário conectado, as permissões de aplicativo podem ser consentidas por um administrador quando o aplicativo é instalado no locatário ou por meio do centro de administração do Microsoft Entra. Somente um administrador pode consentir com permissões de aplicativo.

Além de receber permissões de aplicativo do Microsoft Graph, um aplicativo também pode receber os privilégios necessários por meio de uma das seguintes condições:

• Quando o aplicativo é atribuído a propriedade do recurso que ele pretende gerenciar.
• Quando o aplicativo recebe uma Microsoft Entra funções administrativas internas ou personalizadas.

Observação

As permissões concedidas por meio de Microsoft Entra funções internas não limitam o aplicativo a chamar somente APIs do Microsoft Graph.

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

Categoria	Permissões delegadas	Permissões de aplicativos
Tipos de aplicativos	Aplicativo Web / Aplicativo móvel / aplicativo de página única (SPA)	Web / Daemon
Contexto de acesso	Obter acesso em nome de um usuário	Obter acesso sem um usuário
Quem pode consentir?	Os usuários podem consentir com seus dados Os administradores podem consentir com todos os usuários	Apenas o administrador pode consentir
Outros nomes	Scopes Permissões OAuth2	Funções de aplicativo Permissões somente de aplicativo Permissões de acesso direto
Resultado do consentimento	oAuth2PermissionGrant	appRoleAssignment
Tipos de signInAudience com suporte	AzureADMyOrg AzureADMultipleOrgs AzureADandPersonalMicrosoftAccount PersonalMicrosoftAccount	AzureADMyOrg AzureADMultipleOrgs AzureADandPersonalMicrosoftAccount

A imagem a seguir ilustra os privilégios de um aplicativo em cenários de acesso delegados versus somente aplicativos.

Padrão de nomenclatura de permissões

O Microsoft Graph expõe permissões granulares que ajudam você a controlar o acesso que os aplicativos têm aos recursos do Microsoft Graph, como usuários, grupos e emails. Essas permissões são nomeadas no seguinte padrão:

{resource}. {operation}. {constraint}

Valor	Descrição	Exemplos
{resource}	Refere-se a um recurso do Microsoft Graph ao qual a permissão permite acesso. Por exemplo, o user recurso.	User, Application ou Group
{operation}	Refere-se às operações do Microsoft API do Graph permitidas nos dados expostos pelo recurso. Por exemplo, Read somente para operações de leitura ou ReadWrite para operações de leitura, criar, atualizar e excluir.	Read, ReadBasic, ReadWrite, Create, Manageou Migrate
{constraint}	Determina a extensão potencial de acesso que um aplicativo terá no diretório. Esse valor pode não ser declarado explicitamente. Quando não declarada, a restrição padrão é limitada a dados pertencentes ao usuário conectado.	All, AppFolder, OwnedBy, Selected, Shared, Hidden

Exemplos:

• User.Read – permite que o aplicativo leia informações sobre o usuário conectado.
• Application.ReadWrite.All – Permite que o aplicativo gerencie todos os aplicativos no locatário.
• Application.ReadWrite.OwnedBy – permite que o aplicativo gerencie apenas os aplicativos que ele cria ou possui.
• Group.Create – permite que o aplicativo crie novos grupos, mas não modifique ou exclua-os.
• Member.Read.Hidden – permite que o aplicativo leia associações ocultas

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

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 um aplicativo com privilégios certos consulta a associação de um objeto de contêiner, ele recebe uma 200 OK resposta e uma coleção de objetos. No entanto, se o aplicativo não tiver permissões para ler um determinado tipo de objeto no contêiner, objetos desse tipo serão retornados, mas com informações limitadas, por exemplo, apenas o tipo de objeto e a ID poderão ser retornados e outras propriedades forem indicadas como null. Informações completas são retornadas para os tipos de objeto que o aplicativo tem permissões para ler.

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

Cenário de exemplo

Os membros de um grupo são usuários, grupos e dispositivos. Um aplicativo recebeu as permissões User.Read.All e Group.Read.All do Microsoft Graph. O aplicativo chama a API de membros do grupo de lista para recuperar os membros do grupo.

Para ler as propriedades básicas dos membros de um grupo que são usuários, o aplicativo precisa pelo menos da permissão User.Read.All . Para ler as propriedades básicas dos membros de um grupo que são grupos, o aplicativo precisa pelo menos da permissão Group.Read.All . Para ler as propriedades básicas dos membros de um grupo que são dispositivos, o aplicativo precisa pelo menos da permissão Device.Read.All .

Como o aplicativo tem permissões para acessar apenas objetos de usuário e grupo no grupo, mas não objetos de dispositivo, na resposta:

• Todas as propriedades básicas dos objetos membros do usuário e do grupo são retornadas.
• Para os objetos membro do dispositivo, apenas o tipo de objeto e a ID do objeto são retornados, mas todas as outras propriedades têm o valor nulo.

Exemplo

Solicitação

HTTP

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

C#

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

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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc groups members list --group-id {group-id}

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

Ir

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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



members, err := graphClient.Groups().ByGroupId("group-id").Members().Get(context.Background(), nil)

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

Java

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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

PHP

<?php
use Microsoft\Graph\GraphServiceClient;


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


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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

PowerShell

Import-Module Microsoft.Graph.Groups

Get-MgGroupMember -GroupId $groupId

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

Python

from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

Resposta

O seguinte objeto é 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
        }
    ]
}

Práticas recomendadas para usar permissões do Microsoft Graph

O Microsoft Graph expõe permissões granulares que permitem que um aplicativo solicite apenas as permissões necessárias para funcionar. As permissões granulares permitem que você aplique o princípio de privilégio mínimo ao atribuir e conceder permissões a um aplicativo, concedendo ao aplicativo a permissão mínima necessária para a operação.

Considere os seguintes exemplos:

• Um aplicativo precisa ler apenas as informações de perfil do usuário conectado. O aplicativo requer apenas a permissão User.Read , que é a permissão menos privilegiada para acessar as informações do usuário conectado. Conceder ao aplicativo a permissão User.ReadWrite torna-o com privilégio excessivo porque o aplicativo não precisa atualizar o perfil do usuário.
• Um aplicativo precisa ler os grupos no locatário sem um usuário conectado. O aplicativo requer apenas a permissão de aplicativo Group.Read.All , que é a permissão menos privilegiada para ler grupos no locatário sem um usuário conectado.
• Um aplicativo precisa ler ou gravar em um calendário do usuário conectado. O aplicativo gerencia trabalhos dinâmicos e sincroniza com o calendário do Outlook do usuário para manter o aplicativo atualizado para agendar trabalhos para o usuário. Embora obter os dados do calendário do usuário exija Calendars.Read, atualizar o calendário com trabalhos agendados requer uma permissão privilegiada maior, Calendars.ReadWrite. Nesse caso, o aplicativo deve solicitar Calendars.ReadWrite.

Conceder a um aplicativo mais privilégios do que precisa é uma prática de segurança ruim que expõe um aplicativo a acesso não autorizado e não intencional a dados ou operações. Além disso, solicitar mais permissões do que o necessário pode fazer com que os usuários se abstenham de consentir com um aplicativo, afetando a adoção e o uso de um aplicativo.

Aplique o princípio de menor privilégio ao atribuir e conceder permissões do Microsoft Graph a um aplicativo. Para obter mais informações, confira Aprimorar a segurança com o princípio de menor privilégio e Criar aplicativos que protegem a identidade por meio de permissões e consentimento.

Limites de permissões solicitadas por aplicativo

Microsoft Entra ID limita o número de permissões que podem ser solicitadas e consentidas por um aplicativo cliente. Esses limites dependem do signInAudience valor de um aplicativo, mostrado no manifesto do aplicativo.

signInAudience	Usuários permitidos	Máximo de permissões que o aplicativo pode solicitar	Máximo de permissões do Microsoft Graph que o aplicativo pode solicitar	Máximo de permissões que podem ser consentidas em uma única solicitação
AzureADMyOrg	Usuários da organização em que o aplicativo está registrado	400	400	Cerca de 155 permissões delegadas e cerca de 300 permissões de aplicativo
AzureADMultipleOrgs	Usuários de qualquer organização Microsoft Entra	400	400	Cerca de 155 permissões delegadas e cerca de 300 permissões de aplicativo
PersonalMicrosoftAccount	Usuários consumidores (como contas do Outlook.com ou Live.com)	30	30	30
AzureADandPersonalMicrosoftAccount	Usuários e usuários consumidores de qualquer organização Microsoft Entra	30	30	30

Recuperar IDs de permissão por meio do Microsoft Graph

Para definir permissões usando a CLI do Azure, o PowerShell ou a infraestrutura como estruturas de código, você pode precisar do identificador para a permissão que deseja usar em vez do nome. A referência de permissões lista IDs para todas as permissões do Microsoft Graph. Como alternativa, você pode ler informações sobre todas as permissões do Microsoft Graph programaticamente por meio 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 do aplicativo, delegadas e específicas do recurso, respectivamente.

Conteúdo relacionado

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