Compartilhar via


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.

    Ilustração de privilégios de 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.
    • Grupo. 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.

    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.

    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 menos privilegiada 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 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 e assim por diante. No entanto, como alternativa às permissões individuais no nível do recurso, o aplicativo pode receber pelo menos a permissão Directory.Read.All para ler todas as propriedades para todos os tipos de membro.

    Exemplo

    Solicitação

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

    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.