Escopos de permissão | Conceitos da API do Graph
Aplica-se a: API do Graph | Azure AD (Active Directory)
A API do Graph expõe os escopos de permissões OAuth 2.0 que são usados para controlar o acesso que um aplicativo tem aos dados do diretório de clientes. Como desenvolvedor, você configura seu aplicativo com os escopos de permissão adequados ao acesso que eles precisam ter. Normalmente, isso é feito por meio do portal do Azure. Ao entrar, os usuários ou administradores têm a oportunidade de permitir que o aplicativo acesse seus dados de diretório com os escopos de permissão que você tiver configurado. Por esse motivo, você deve escolher escopos de permissão que forneçam o menor nível de privilégio necessário para seu aplicativo. Para obter mais detalhes sobre como configurar permissões para seu aplicativo e sobre o processo de consentimento, consulte Integrating Applications with Azure Active Directory (Integrando aplicativos ao Azure Active Directory).
Importante
Recomendamos que você use o Microsoft Graph em vez da API do Azure AD Graph para acessar os recursos do Azure Active Directory. Nossos esforços de implantação agora estão concentrados no Microsoft Graph e não há planos de novos aprimoramento para a API do Azure AD Graph. Há um número muito limitado de cenários para os quais a API do Azure AD Graph ainda pode ser adequada. Para saber mais, confira a postagem do blog sobre Microsoft Graph ou Azure AD Graph no Centro de Desenvolvimento do Office.
Conceitos do escopo de permissão
Escopos somente de aplicativo versus escopos delegados
Os escopos de permissão podem ser somente de aplicativo ou delegados. Escopos somente de aplicativo (também conhecidos como funções de aplicativo) concedem ao aplicativo o conjunto completo de privilégios oferecido pelo escopo. Escopos somente de aplicativo normalmente são usados por aplicativos que são executados como serviço, sem que haja um usuário conectado. Escopos de permissão delegados são destinados a aplicativos a que o usuário se conecta. Esses escopos delegam os privilégios do usuário conectado ao aplicativo, permitindo que o aplicativo atue como o usuário conectado. Os privilégios reais concedidos ao aplicativo serão a combinação (a interseção) menos privilegiada entre os privilégios concedidos pelo escopo e os privilégios que o usuário conectado tem. Por exemplo, se o escopo de permissão conceder privilégios delegados para gravar todos os objetos do diretório, mas o usuário conectado tiver privilégios apenas para atualizar seu próprio perfil de usuário, o aplicativo só será capaz de gravar o perfil do usuário conectado e nenhum outro objeto.
Perfis completos e básicos para usuários e grupos
O perfil completo (ou perfil) de um Usuário ou Grupo inclui todas as propriedades declaradas da entidade. Como o perfil pode conter informações confidenciais do diretório ou PII (informações de identificação pessoal), vários escopos restringem o acesso do aplicativo a um conjunto limitado de propriedades, conhecido como perfil básico. Para os usuários, o perfil básico inclui apenas as seguintes propriedades: nome de exibição, nome e sobrenome, foto e endereço de email. Para grupos, o perfil básico contém apenas o nome de exibição.
Detalhes do escopo de permissão
A tabela a seguir lista os escopos de permissão da API do Graph e explica o acesso concedido por cada um deles.
- A coluna Escopo lista o nome do escopo. Os nomes dos escopos assumem a forma recurso.operação.restrição; por exemplo, Group.ReadWrite.All. Se a restrição for "All", o escopo concederá ao aplicativo a capacidade de executar a operação (ReadWrite) em todos os recursos especificados (Group) no diretório. Caso contrário, o escopo só permite a operação no perfil do usuário conectado. Os escopos podem conceder privilégios limitados à operação especificada. Consulte a coluna Descrição para obter detalhes.
- A coluna Permissão mostra como o escopo é exibido no portal do Azure.
- A coluna Descrição descreve o conjunto completo de privilégios concedidos pelo escopo. Para escopos delegados, o acesso real concedido ao aplicativo será a combinação (a interseção) menos privilegiada entre os acessos concedidos pelo escopo e os privilégios do usuário conectado.
| Escopo | Permissão | Descrição | Tipo de escopo | Requer o consentimento do administrador |
|---|---|---|---|---|
| User.Read | Habilitar entrada e ler perfil do usuário | Permite que os usuários entrem no aplicativo e que o aplicativo leia o perfil completo do usuário conectado. O perfil completo inclui todas as propriedades declaradas da entidade User. User.Read permite que o aplicativo leia as seguintes informações básicas da empresa do usuário conectado (por meio do objeto TenantDetail): ID de locatário, nome de exibição do locatário e domínios verificados. O aplicativo não pode ler propriedades de navegação, como de gerentes ou subordinados diretos. O aplicativo não pode ler a senha do usuário. | delegado | Não |
| User.ReadBasic.All | Ler os perfis básicos de todos os usuários | Permite que o aplicativo leia o perfil básico de todos os usuários da organização em nome do usuário conectado. O perfil básico do usuário é composto pelas seguintes propriedades: nome de exibição, nome e sobrenome, foto e endereço de email. Para ler os grupos de que um usuário é membro, o aplicativo também exigirá Group.Read.All ou Group.ReadWrite.All. | delegado | Não |
| User.Read.All | Ler os perfis completos de todos os usuários | Igual a User.ReadBasic.All, exceto por permitir que o aplicativo leia o perfil completo de todos os usuários da organização e por ler propriedades de navegação, como de gerentes e subordinados diretos. O perfil completo inclui todas as propriedades declaradas da entidade User. Para ler os grupos de que um usuário é membro, o aplicativo também exigirá Group.Read.All ou Group.ReadWrite.All. O aplicativo não pode ler senhas de usuários. | delegado | Sim |
| Group.Read.All | Ler todos os grupos (visualização) | Permite que o aplicativo leia o perfil básico de todos os grupos da organização em nome do usuário conectado. O aplicativo também pode ler o perfil básico dos grupos de que um grupo é membro. O perfil básico de um grupo inclui apenas o nome de exibição do grupo. Para ler as informações de perfil de membros do grupo, o aplicativo também exigirá User.ReadBasic ou User.Read.All. | delegado | Sim |
| Group.ReadWrite.All | Ler e gravar todos os grupos (visualização) | Permite que o aplicativo leia o perfil completo de todos os grupos da organização e crie e atualize grupos em nome do usuário conectado. O aplicativo também pode ler o perfil completo dos grupos de que um grupo é membro. O perfil completo inclui todas as propriedades declaradas da entidade Group. Para ler as informações de perfil de membros do grupo ou atualizá-las, o aplicativo também exigirá User.ReadBasic ou User.Read.All. | delegado | Sim |
| Device.ReadWrite.All | Ler e gravar em todos os dispositivos | Permite que o aplicativo leia e grave todas as propriedades do dispositivo sem que haja um usuário conectado. Não permite criar ou excluir dispositivos ou atualizar os identificadores de segurança alternativos dos dispositivos. | somente de aplicativo | Sim |
| Directory.Read.All | Ler dados do diretório | Permite que o aplicativo leia todos os dados no diretório da organização, como usuários, grupos e aplicativos, bem como suas propriedades de navegação associadas. Observação: os usuários poderão dar consentimento para aplicativos que exigem essa permissão se o aplicativo estiver registrado no locatário da própria organização. | somente de aplicativo, delegado | Sim |
| Directory.ReadWrite.All | Ler e gravar dados do diretório | Permite que o aplicativo leia todos os dados no diretório da organização. Também permite que o aplicativo crie e atualize usuários e grupos e atualize suas propriedades de navegação, mas impede a exclusão de usuários ou grupos. Permite ainda que o aplicativo defina extensões de esquema em aplicativos. Para obter uma lista detalhada dos privilégios, consulte Detalhes dos privilégios de Directory.ReadWrite.All abaixo. | somente de aplicativo, delegado | Sim |
| Directory.AccessAsUser.All | Acessar diretório como o usuário conectado | Permite ao aplicativo o mesmo acesso aos dados no diretório da organização como o usuário conectado. Observação: um aplicativo cliente nativo pode solicitar que o usuário conceda essa permissão. No entanto, um aplicativo Web requer o consentimento do administrador. | delegado | Sim |
Observação: por padrão, quando você cria um aplicativo usando o portal do Azure, o Azure AD atribui a ele o escopo de permissão delegado User.Read.
Directory.ReadWrite.All privileges detail
O escopo de permissão Directory.ReadWrite.All concede os seguintes privilégios:
- Leitura completa de todos os objetos de diretório (propriedades declaradas e propriedades de navegação)
- Criar e atualizar usuários
- Desabilitar e habilitar usuários (mas não o administrador da empresa)
- Definir ID de segurança alternativa do usuário (mas não administradores)
- Criar e atualizar grupos
- Gerenciar associações do grupo
- Atualizar proprietário do grupo
- Gerenciar atribuições de licença
- Definir extensões de esquema em aplicativos
- Permite que a senha seja definida ao criar um usuário.
- Observação: não é concedido o direito de redefinir senhas de usuários
- Observação: não é concedido o direito de ler senhas de usuários
- Observação: não é concedido o direito de excluir entidades (incluindo usuários ou grupos)
- Observação: exclui especificamente a criação ou atualização de entidades não listadas acima. Isso inclui: Application, Oauth2PermissionGrant, AppRoleAssignment, Device, ServicePrincipal, TenantDetail, domínios etc.
Cenários do escopo de permissão
A tabela a seguir mostra os escopos de permissão necessários para que um aplicativo seja capaz de executar operações específicas. Observe que, em alguns casos, a capacidade do aplicativo executar algumas operações depende de o escopo de permissão ser delegado ou somente de aplicativo e, no caso de escopos de permissão delegados, dos privilégios do usuário conectado.
| Cenário | Acesso necessário | Escopo de permissão necessário |
|---|---|---|
| Entrar e mostrar um bloco com o nome e a foto em miniatura do usuário. | Ler o perfil completo do usuário conectado. Ler informações básicas da empresa. |
User.Read |
| Seletor de pessoas básico. | Ler o perfil básico de todos os usuários em nome do usuário conectado. | User.ReadBasic.All |
| Seletor de pessoas com perfil completo. | O mesmo que acima, mas com acesso ao perfil completo dos usuários em nome do usuário conectado. | User.Read.All |
| Navegador de organograma. | Ler o perfil completo de todos os usuários, seus gerentes e subordinados diretos em nome do usuário conectado. | User.Read.All |
| Seletor de pessoas que inclui grupos para controle de acesso ao seu aplicativo. Visualizador de grupo e associação. |
Ler o perfil básico de todos os grupos e usuários em nome do usuário conectado. Ler os perfis de usuário básicos dos gerentes e dos subordinados diretos dos usuários. Ler o perfil básico das associações de grupo dos usuários. Ler o perfil básico das associações de grupo dos grupos. Ler o perfil básico dos membros dos grupos |
User.ReadBasic.All e Group.Read.All |
| Mostrar o perfil do usuário conectado e do gerente, subordinados diretos e associações de grupo do usuário. | Use operações me para ler: O perfil completo do usuário conectado. O perfil completo do gerente e dos subordinados diretos do usuário conectado. O perfil básico dos grupos de que o usuário conectado é membro. Observação: a combinação dos dois escopos concede mais acesso do que é mencionado aqui para operações me. |
User.Read.All e Group.Read.All |
| Serviço de gerenciamento de grupos que permite que os usuários criem e gerenciem grupos. | Ler o perfil completo de todos os grupos e usuários em nome do usuário conectado. Ler os perfis completos dos gerentes e dos subordinados diretos dos usuários. Ler o perfil completo das associações de grupo dos usuários. Ler o perfil completo das associações de grupo dos grupos. Ler o perfil completo das associações dos grupos. Criar e atualizar grupos e suas propriedades de navegação (membros). |
User.Read.All e Group.ReadWrite.All |
| Ler todos os objetos do diretório (incluindo propriedades de navegação). | Directory.Read.All | |
| Ler todos os objetos do diretório (incluindo propriedades de navegação). Criar e atualizar objetos de usuário e grupo. Não é permitido excluir usuários ou grupos. Observação: nem todos os privilégios concedidos estão listados aqui. |
Directory.ReadWrite.All | |
| Atuar como o usuário conectado. | Ler e gravar objetos de diretório (incluindo propriedades de navegação) em nome do usuário conectado. | Directory.AccessAsUser.All |
Acesso padrão para administradores, usuários e usuários convidados
A tabela a seguir lista o acesso padrão de administradores (globais), usuários e usuários convidados no diretório. O acesso padrão pode ser mais ampliado ou restrito com base nas configurações do diretório e/ou da associação de um usuário em uma ou mais funções de diretório. Para obter mais informações sobre como configurar o acesso de usuários e usuários convidados aos dados do diretório, consulte Create or edit users in Azure AD (Criar ou editar usuários no Azure AD). Para obter mais informações sobre o acesso associado a diferentes funções do diretório, consulte Assigning administrator roles in Azure AD (Atribuindo funções de administrador no Azure AD).
| Tipo de usuário | Acessar |
|---|---|
| Administrador Global | Ler todos os objetos do diretório. Criar, atualizar e excluir todos os objetos do diretório |
| Usuário | Ler todos os objetos do diretório. Criar aplicativos e entidades de serviço associadas. Atualizar seu perfil. Atualizar grupos que possuem (e a propriedade de membros). Atualizar aplicativos e entidades de serviço que possuem. Excluir aplicativos e entidades de serviço que possuem. |
| Usuário convidado | Ler seu perfil completo. Ler os perfis básicos de todos os outros usuários Ler o perfil básico de todos os grupos. Ler aplicativos. Atualizar algumas propriedades de seu perfil. Nenhuma pesquisa de usuário ou grupo (consulte User and group search limitations for guest users (Limitações de pesquisa de usuários e grupos para usuários convidados) abaixo). |
Limitações de pesquisa de usuários e grupos para usuários convidados
Funcionalidades de pesquisa de usuários e grupos permitem que o aplicativo pesquise por usuários ou grupos no diretório de clientes executando consultas no conjunto de recursos usuários ou grupos (por exemplo, https://graph.windows.net/myorganization/users?api-version=1.6). Administradores e usuários têm acesso a essa funcionalidade. Usuários convidados não têm. Se o usuário conectado for um usuário convidado, dependendo do escopo de permissão, um aplicativo poderá ler o perfil de um usuário ou grupo específico usando a ID do objeto ou o nome UPN para um usuário ou a ID de objeto para um grupo (por exemplo, https://graph.windows.net/myorganization/users/241f22af-f634-44c0-9a15-c8cd2cea5531?api-version=1.6). No entanto, ele não pode executar consultas no conjunto de recursos usuários ou grupos, que poderia solicitar mais de uma entidade. Por exemplo, dependendo do escopo de permissão, o aplicativo pode ler os perfis de usuários ou grupos que ele obtém seguindo os links nas propriedades de navegação, mas não pode emitir uma consulta para retornar todos os usuários ou grupos no diretório.