Visão geral das permissões do Microsoft Graph

Antes que a plataforma de identidade da Microsoft possa autorizar seu aplicativo a acessar dados na nuvem da Microsoft, você deve conceder ao aplicativo os privilégios necessários. Da mesma forma, antes que a plataforma de identidade da Microsoft possa autorizar seu aplicativo a acessar dados por meio do Microsoft Graph, você deve conceder ao aplicativo 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 é atribuir a ele permissões do Microsoft Graph. Outra forma é por meio de sistemas RBAC (controle de acesso baseado em função), como o Microsoft Entra RBAC. Em alguns casos, o acesso aos dados por meio 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 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 funcionam as permissões, assista ao vídeo a seguir.

Tipo de permissão

O Microsoft Graph dá suporte a dois cenários de acesso, acesso delegado e acesso somente ao aplicativo. 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, funcionam no cenário de acesso delegado. Essas permissões permitem que o aplicativo atue em nome de um usuário conectado. No entanto, o aplicativo não pode acessar nada que o usuário conectado não tenha conseguido acessar.

Por exemplo, um aplicativo obtém os Files. Read.All delegou em nome de Tom, um usuário. O aplicativo só pode ler todos os arquivos na organização que Tom já pode acessar. Tom pode conseguir acessar os arquivos porque ele tem permissões por meio de uma das seguintes maneiras:

• Tom criou ou é o proprietário dos arquivos.
• Os arquivos foram compartilhados diretamente com Tom ou indiretamente por meio de uma equipe ou associação de grupo.
• Tom recebeu permissões por meio de um sistema RBAC compatível.

Portanto, em um cenário delegado, os privilégios que um aplicativo tem para 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 contas Outlook.com, corporativas ou de estudante ou ambos os tipos de conta. Todas as permissões delegadas são válidas para contas corporativas ou de estudante, 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 oportunidade de consentir com as permissões delegadas. Se eles derem consentimento, o aplicativo poderá acessar recursos e APIs dentro dos limites das permissões do usuário.

Permissões de aplicativos

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

Para aplicativos que acessam recursos e APIs sem um usuário conectado, um administrador consente com as permissões do aplicativo quando o aplicativo é instalado no locatário ou por meio do centro de administração do Microsoft Entra. Somente o Administrador de Função com Privilégios e o Administrador Global podem consentir com as permissões do 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 recebe a propriedade do recurso que pretende gerenciar.
• Quando o aplicativo recebe permissões por meio de um sistema RBAC ou funções administrativas personalizadas.

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

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

Práticas recomendadas para selecionar tipos de permissão para registro do agente do conector

Os agentes do conector do Microsoft Graph são executados como serviços em segundo plano e exigem permissões de aplicativo do Microsoft Graph.

As permissões delegadas não têm suporte para o registro do agente do conector e causam falhas de registro, mesmo quando as permissões aparecem configuradas corretamente.

Solicite as permissões de aplicativo com privilégios mínimos necessárias para o seu cenário do conector e verifique se o consentimento do administrador em todo o locatário foi concedido.

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 email. Essas permissões seguem o padrão de nomenclatura:

{recurso}. {operação}. {restrição}

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 os modifique ou exclua.
• 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.

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

RSC é uma estrutura de autorização que concede acesso com escopo aos dados expostos por um recurso. Por meio do RSC, um usuário autorizado pode conceder a um aplicativo acesso aos dados de uma instância específica de um tipo de recurso. Eles não precisam dar acesso ao aplicativo a todas as instâncias do tipo de recurso em todo o locatário.

As permissões RSC também estão disponíveis para consentimento e são suportadas apenas por um subconjunto de recursos disponíveis por meio do Microsoft Graph, como equipes, chats e mensagens. Para obter mais informações, consulte Permissões RSC e 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 um aplicativo com os privilégios certos consulta a associação de um objeto contêiner, ele recebe uma 200 OK resposta e uma coleção de objetos. No entanto, se o aplicativo não tiver as permissões para ler um determinado tipo de objeto no contêiner, o aplicativo receberá objetos desse tipo, mas com informações limitadas. Por exemplo, somente o tipo de objeto e a ID podem ser retornados e outras propriedades são indicadas como null. O aplicativo recebe informações completas sobre os tipos de objeto que ele tem permissão para ler.

Esse princípio se aplica a todas as relações do tipo directoryObject . Exemplos incluem /groups/{id}/members, /users/{id}/memberOf, e me/ownedObjects.

Por exemplo, um grupo pode ter usuários, grupos, aplicativos, entidades de serviço, dispositivos e contatos como membros. Um aplicativo recebe a permissão GroupMember.Read.All com privilégios mínimos para listar membros do grupo. No objeto de resposta, somente as propriedades id e @odata.type são preenchidas para todos os membros retornados. As outras propriedades são indicadas como null. Para essa API e para retornar mais informações para os membros do grupo, o aplicativo precisa das seguintes permissões adicionais:

• Para ler as propriedades básicas dos membros de um grupo que são usuários, User.ReadBasic.All é a permissão com privilégios mínimos.
• Para ler as propriedades básicas dos membros de um grupo que são grupos, GroupMember.Read.All é a permissão menos privilegiada.
• Para ler as propriedades básicas dos membros de um grupo que são dispositivos, Device.Read.All é a permissão menos privilegiada.
• Para ler as propriedades básicas dos membros de um grupo que são entidades de serviço, Application.Read.All é a permissão menos privilegiada.
• De acordo com o princípio do privilégio mínimo, use as permissões anteriores conforme apropriado para seu aplicativo; no entanto, como alternativa às permissões individuais no nível do recurso, atribua ao aplicativo a permissão Directory.Read.All para ler todas as propriedades de todos os tipos de membro.

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://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups["{group-id}"].Members.GetAsync();

// 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://learn.microsoft.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://learn.microsoft.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 a seguir é 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 aplicar o princípio de privilégios mínimos ao atribuir e conceder permissões a um aplicativo. Conceda ao aplicativo a permissão mínima necessária para a operação.

Considere os seguintes exemplos:

• Um aplicativo precisa ler 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 o torna superprivilegiado 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 GroupMember.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 a partir do 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 mais alta, Calendars.ReadWrite. Nesse caso, o aplicativo deve solicitar Calendars.ReadWrite.

Conceder a um aplicativo mais privilégios do que o necessário é uma prática de segurança ruim. Isso aumenta a exposição do aplicativo ao 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 privilégios mínimos ao atribuir e conceder permissões do Microsoft Graph a um aplicativo. Para obter mais informações, consulte Aprimorar a segurança com o princípio do privilégio mínimo e Criar aplicativos que protegem a identidade por meio de permissões e consentimento.

Permissões para usar com cautela

Algumas permissões do Microsoft Graph concedem acesso a um intervalo maior de dados ou operações do que outras. Use essas permissões com cuidado. Por exemplo, a permissão Directory.AccessAsUser.All é a permissão delegada com privilégios mais altos que concede acesso a quase todas as operações de API no Microsoft Entra ID. A permissão Directory.ReadWrite.All é a segunda no ranking de privilégios. Directory.Read.All é a permissão somente leitura com privilégios mais altos para recursos do Microsoft Entra ID. Use essas permissões com cuidado e somente quando necessário. Sempre use permissões de opções com menos privilégios.

Na documentação de referência da API relacionada aos recursos do Microsoft Entra ID, algumas dessas permissões com privilégios mais altos podem ser intencionalmente excluídas da tabela de permissões com suporte para acessar a API.

Além disso, a função de administrador global é a função interna com privilégios mais altos no Microsoft Entra ID. Na documentação de referência da API, essa função é intencionalmente excluída da lista de funções que dão suporte ao acesso à API em favor de funções com menos privilégios.

Limites de permissões solicitadas por aplicativo

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

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, talvez você precise do identificador para a permissão que deseja usar em vez do nome. A referência de permissões lista as IDs de 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 de 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.
• Noções básicas sobre acesso delegado