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.
Observação
As permissões concedidas através de Microsoft Entra funções incorporadas não limitam a aplicação a chamar apenas APIs do Microsoft Graph.
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.
Observação
As permissões concedidas através de Microsoft Entra funções incorporadas não limitam a aplicação a chamar apenas APIs do Microsoft Graph.
Comparação de permissões delegadas e de aplicativo
| Categoria | Permissões delegadas | Permissões de aplicativos |
|---|---|---|
| Tipos de aplicações | Aplicação Web/Móvel/Aplicação 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? | Apenas o administrador pode consentir | |
| Outros nomes | ||
| Resultado do consentimento | Objeto oAuth2PermissionGrant | objeto appRoleAssignment |
| Tipos de signInAudience suportados | AzureADMyOrg AzureADMultipleOrgs AzureADandPersonalMicrosoftAccount PersonalMicrosoftAccount |
AzureADMyOrg AzureADMultipleOrgs AzureADandPersonalMicrosoftAccount |
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}
| Valor | Descrição | Exemplos |
|---|---|---|
{resource} |
Refere-se a um recurso do Microsoft Graph ao qual a permissão permite o acesso. Por exemplo, o user recurso. |
User, Application ou Group |
{operation} |
Refere-se às operações do Microsoft API do Graph permitidas nos dados que são expostos pelo recurso. Por exemplo, Read para operações de leitura apenas ou ReadWrite para operações de leitura, criação, atualização e eliminação. |
Read, , ReadBasicReadWrite, Create, ManageouMigrate |
{constraint} |
Determina a extensão potencial de acesso que uma aplicação tem no diretório. Este valor pode não ser explicitamente declarado. Quando não for declarada, a restrição predefinida é limitada aos dados que pertencem ao utilizador com sessão iniciada. |
All, AppFolder, OwnedBy, Selected, Shared, Hidden |
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
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.
| 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 | Utilizadores 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 | Utilizadores e utilizadores consumidores de qualquer organização Microsoft Entra | 30 | 30 | 30 |
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.