Table of contents

Escopos de permissão | Conceitos da API do GraphPermission scopes | Graph API concepts

Bryan Lamos|Última Atualização: 19/06/2018
|
2 Colaboradores

Aplica-se a: API do Graph | Azure AD (Active Directory)Applies to: Graph API | Azure Active Directory (AD)

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.The Graph API exposes OAuth 2.0 permission scopes that are used to control access that an app has to customer directory data.Como desenvolvedor, você configura seu aplicativo com os escopos de permissão adequados ao acesso que eles precisam ter.As a developer, you configure your app with the permission scopes appropriate to the access that it requires.Normalmente, isso é feito por meio do portal do Azure.Typically you do this through the Azure portal.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.During sign-in, users or administrators are given an opportunity to consent to allow your app access to their directory data with the permission scopes you configured.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.For this reason, you should choose permission scopes that provide the least level of privilege needed by your app.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).For more details on how to configure permissions for your app and on the consent process, see Integrating Applications with 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.We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources.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.Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API.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.There are a very limited number of scenarios for which Azure AD Graph API might still be appropriate; for more information, see the Microsoft Graph or the Azure AD Graph blog post in the Office Dev Center.

Conceitos do escopo de permissão Permission scope concepts

Escopos somente de aplicativo versus escopos delegadosApp-only vs. delegated scopes

Os escopos de permissão podem ser somente de aplicativo ou delegados.Permission scopes can be either app-only or delegated.Escopos somente de aplicativo (também conhecidos como funções de aplicativo) concedem ao aplicativo o conjunto completo de privilégios oferecido pelo escopo.App-only scopes (also known as app roles) grant the app the full set of privileges offered by the scope.Escopos somente de aplicativo normalmente são usados por aplicativos que são executados como serviço, sem que haja um usuário conectado.App-only scopes are typically used by apps that run as a service without a signed-in user being present.Escopos de permissão delegados são destinados a aplicativos a que o usuário se conecta.Delegated permission scopes are for apps that a user signs in to.Esses escopos delegam os privilégios do usuário conectado ao aplicativo, permitindo que o aplicativo atue como o usuário conectado.These scopes delegate the privileges of the signed-in user to the app, allowing the app to act as the signed in user.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.The actual privileges granted to the app will be the least privileged combination (the intersection) of the privileges granted by the scope and those possessed by the signed-in user.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.For example, if the permission scope grants delegated privileges to write all directory objects, but the signed-in user has privileges only to update their own user profile, the app will only be able to write the signed-in user's profile but no other objects.

Perfis completos e básicos para usuários e gruposFull and basic profiles for users and groups

O perfil completo (ou perfil) de um Usuário ou Grupo inclui todas as propriedades declaradas da entidade.The full profile (or profile) of a User or a Group includes all of the entity's declared properties.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.Because the profile may contain sensitive directory information or personally identifiable information (PII), several scopes constrain app access to a limited set of properties known as a basic profile.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.For users, the basic profile includes only the following properties: display name, first and last name, photo, and email address.Para grupos, o perfil básico contém apenas o nome de exibição.For groups, the basic profile contains only the display name.

Detalhes do escopo de permissão Permission scope details

A tabela a seguir lista os escopos de permissão da API do Graph e explica o acesso concedido por cada um deles.The following table lists the Graph API permission scopes and explains the access granted by each.

  • A coluna Escopo lista o nome do escopo.The Scope column lists the scope name.Os nomes dos escopos assumem a forma recurso.operação.restrição; por exemplo, Group.ReadWrite.All.Scope names take the form resource.operation.constraint; for example, 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.If the constraint is "All", the scope grants the app the ability to perform the operation (ReadWrite) on all of the specified resources (Group) in the directory; otherwise, the scope only permits the operation on the profile of the signed-in user.Os escopos podem conceder privilégios limitados à operação especificada. Consulte a coluna Descrição para obter detalhes.Scopes may grant limited privileges for the specified operation, see the Description column for details.
  • A coluna Permissão mostra como o escopo é exibido no portal do Azure.The Permission column shows how the scope is displayed on the Azure portal.
  • A coluna Descrição descreve o conjunto completo de privilégios concedidos pelo escopo.The Description column describes the full set of privileges granted by the scope.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.For delegated scopes, the actual access granted to the app will be the least privileged combination (intersection) of the access granted by the scope and the privileges of the signed-in user.
EscopoScopePermissãoPermissionDescriçãoDescriptionTipo de escopoScope TypeRequer o consentimento do administradorRequires Administrator Consent
User.ReadUser.ReadHabilitar entrada e ler perfil do usuárioEnable sign-in and read user profilePermite que os usuários entrem no aplicativo e que o aplicativo leia o perfil completo do usuário conectado.Allows users to sign in to the app and allows the app to read the full profile of the signed-in user.O perfil completo inclui todas as propriedades declaradas da entidade User.The full profile includes all of the declared properties of the User entity.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.User.Read allows the app to read the following basic company information of the signed-in user (through the TenantDetail object): tenant ID, tenant display name, and verified domains.O aplicativo não pode ler propriedades de navegação, como de gerentes ou subordinados diretos.The app cannot read navigation properties, such as manager or direct reports.O aplicativo não pode ler a senha do usuário.The app cannot read the user's password.delegadodelegatedNãoNo
User.ReadBasic.AllUser.ReadBasic.AllLer os perfis básicos de todos os usuáriosRead all users' basic profilesPermite que o aplicativo leia o perfil básico de todos os usuários da organização em nome do usuário conectado.Allows the app to read the basic profile of all users in the organization on behalf of the signed-in user.O perfil básico do usuário é composto pelas seguintes propriedades: nome de exibição, nome e sobrenome, foto e endereço de email.The following properties comprise a user’s basic profile: display name, first and last name, photo, and email address.Para ler os grupos de que um usuário é membro, o aplicativo também exigirá Group.Read.All ou Group.ReadWrite.All.To read the groups that a user is a member of, the app will also require Group.Read.All or Group.ReadWrite.All.delegadodelegatedNãoNo
User.Read.AllUser.Read.AllLer os perfis completos de todos os usuáriosRead all users' full profilesIgual 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.Same as User.ReadBasic.All, except that it allows the app to read the full profile of all users in the organization and when reading navigation properties like manager and direct reports.O perfil completo inclui todas as propriedades declaradas da entidade User.The full profile includes all of the declared properties of the User entity.Para ler os grupos de que um usuário é membro, o aplicativo também exigirá Group.Read.All ou Group.ReadWrite.All.To read the groups that a user is a member of, the app will also require either Group.Read.All or Group.ReadWrite.All.O aplicativo não pode ler senhas de usuários.The app cannot read users' passwords.delegadodelegatedSimYes
Group.Read.AllGroup.Read.AllLer todos os grupos (visualização)Read all groups (preview)Permite que o aplicativo leia o perfil básico de todos os grupos da organização em nome do usuário conectado.Allows the app to read the basic profile of all groups in the organization on behalf of the signed-in user.O aplicativo também pode ler o perfil básico dos grupos de que um grupo é membro.The app can also read the basic profile of the groups that a group is a member of.O perfil básico de um grupo inclui apenas o nome de exibição do grupo.The basic profile for a group includes only the group’s display name.Para ler as informações de perfil de membros do grupo, o aplicativo também exigirá User.ReadBasic ou User.Read.All.To read the profile information of a group’s members, the app will also require either User.ReadBasic or User.Read.All.delegadodelegatedSimYes
Group.ReadWrite.AllGroup.ReadWrite.AllLer e gravar todos os grupos (visualização)Read and write all groups (preview)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.Allows the app to read the full profile of all groups in the organization, as well as to create and update groups on behalf of the signed-in user.O aplicativo também pode ler o perfil completo dos grupos de que um grupo é membro.The app can also read the full profile of the groups that a group is a member of.O perfil completo inclui todas as propriedades declaradas da entidade Group.The full profile includes all of the declared properties of the Group entity.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.To read the profiles of or update a group’s members, the app will also require either User.ReadBasic or User.Read.All.delegadodelegatedSimYes
Device.ReadWrite.AllDevice.ReadWrite.AllLer e gravar em todos os dispositivosRead and write all devicesPermite que o aplicativo leia e grave todas as propriedades do dispositivo sem que haja um usuário conectado.Allows the app to read and write all device properties without a signed in user.Não permite criar ou excluir dispositivos ou atualizar os identificadores de segurança alternativos dos dispositivos.Does not allow device creation, device deletion, or update of device alternative security identifiers.somente de aplicativoapp-onlySimYes
Directory.Read.AllDirectory.Read.AllLer dados do diretórioRead directory dataPermite 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.Allows the app to read all of the data in the organization's directory, such as users, groups, and apps, and their associated navigation properties.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.Note: Users may consent to applications that require this permission if the application is registered in their own organization’s tenant.somente de aplicativo, delegadoapp-only, delegatedSimYes
Directory.ReadWrite.AllDirectory.ReadWrite.AllLer e gravar dados do diretórioRead and write directory dataPermite que o aplicativo leia todos os dados no diretório da organização.Allows the app to read all of the data in the organization's directory.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.Allows the app to create and update users and groups, and update their navigation properties, but prohibits user or group deletion.Permite ainda que o aplicativo defina extensões de esquema em aplicativos.Also allows the app to define schema extensions on applications.Para obter uma lista detalhada dos privilégios, consulte Detalhes dos privilégios de Directory.ReadWrite.All abaixo.For a detailed list of privileges, see Directory.ReadWrite.All privileges detail below.somente de aplicativo, delegadoapp-only, delegatedSimYes
Directory.AccessAsUser.AllDirectory.AccessAsUser.AllAcessar diretório como o usuário conectadoAccess directory as the signed-in userPermite ao aplicativo o mesmo acesso aos dados no diretório da organização como o usuário conectado.Allows the app the same access to data in the organization's directory as the signed-in user.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.Note: A native client app can have the user consent to this permission however, a web app requires administrator consent.delegadodelegatedSimYes

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.Note: By default, when you create an app using the Azure portal, Azure AD assigns it a delegated permission scope of User.Read.

Directory.ReadWrite.All privileges detailDirectory.ReadWrite.All privileges detail

O escopo de permissão Directory.ReadWrite.All concede os seguintes privilégios:The Directory.ReadWrite.All permission scope grants the following privileges:

  • Leitura completa de todos os objetos de diretório (propriedades declaradas e propriedades de navegação)Full read of all directory objects (both declared properties and navigation properties)
  • Criar e atualizar usuáriosCreate and update users
  • Desabilitar e habilitar usuários (mas não o administrador da empresa)Disable and enable users (but not company administrator)
  • Definir ID de segurança alternativa do usuário (mas não administradores)Set user alternative security id (but not administrators)
  • Criar e atualizar gruposCreate and update groups
  • Gerenciar associações do grupoManage group memberships
  • Atualizar proprietário do grupoUpdate group owner
  • Gerenciar atribuições de licençaManage license assignments
  • Definir extensões de esquema em aplicativosDefine schema extensions on applications
  • Permite que a senha seja definida ao criar um usuário.Allows password to be set when creating a user.
  • Observação: não é concedido o direito de redefinir senhas de usuáriosNote: No rights to reset user passwords
  • Observação: não é concedido o direito de ler senhas de usuáriosNote: No rights to read user passwords
  • Observação: não é concedido o direito de excluir entidades (incluindo usuários ou grupos)Note: No rights to delete entities (including users or groups)
  • Observação: exclui especificamente a criação ou atualização de entidades não listadas acima.Note: Specifically excludes create or update for entities not listed above.Isso inclui: Application, Oauth2PermissionGrant, AppRoleAssignment, Device, ServicePrincipal, TenantDetail, domínios etc.This includes: Application, Oauth2PermissionGrant, AppRoleAssignment, Device, ServicePrincipal, TenantDetail, domains, etc.

Cenários do escopo de permissão Permission scope scenarios

A tabela a seguir mostra os escopos de permissão necessários para que um aplicativo seja capaz de executar operações específicas.The following table shows the permission scopes needed for an app to be able to perform specific operations.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.Note that in some cases the ability of the app to perform some operations will depend on whether the permission scope is app-only or delegated, and, in the case of delegated permission scopes, on the privileges of the signed-in user.

CenárioScenarioAcesso necessárioAccess RequiredEscopo de permissão necessárioPermission Scope Needed
Entrar e mostrar um bloco com o nome e a foto em miniatura do usuário.Sign-in and show a tile with the user's name and thumbnail photo.Ler o perfil completo do usuário conectado.Read full profile of the signed-in user.
Ler informações básicas da empresa.Read basic company information.
User.ReadUser.Read
Seletor de pessoas básico.Basic people picker.Ler o perfil básico de todos os usuários em nome do usuário conectado.Read basic profile of all users on behalf of the signed-in user.User.ReadBasic.AllUser.ReadBasic.All
Seletor de pessoas com perfil completo.People picker with full profile.O mesmo que acima, mas com acesso ao perfil completo dos usuários em nome do usuário conectado.Same as above but access to full profile of users on behalf of the signed-in user.User.Read.AllUser.Read.All
Navegador de organograma.Org chart navigator.Ler o perfil completo de todos os usuários, seus gerentes e subordinados diretos em nome do usuário conectado.Read full profile of all users, their managers, and direct reports on behalf of the signed-in user.User.Read.AllUser.Read.All
Seletor de pessoas que inclui grupos para controle de acesso ao seu aplicativo.People picker that includes groups for access control to your app.

Visualizador de grupo e associação.Group and membership viewer.
Ler o perfil básico de todos os grupos e usuários em nome do usuário conectado.Read basic profile of all groups and users on behalf of the signed-in user.
Ler os perfis de usuário básicos dos gerentes e dos subordinados diretos dos usuários.Read basic user profiles for users' manager and direct reports.
Ler o perfil básico das associações de grupo dos usuários.Read basic profile of users' group memberships.
Ler o perfil básico das associações de grupo dos grupos.Read basic profile of groups' group memberships.
Ler o perfil básico dos membros dos gruposRead basic profile of groups' members
User.ReadBasic.All e Group.Read.AllUser.ReadBasic.All and Group.Read.All
Mostrar o perfil do usuário conectado e do gerente, subordinados diretos e associações de grupo do usuário.Show the profile of the signed-in user and the user's manager, direct reports, and group memberships.Use operações me para ler:Use me operations to read:
O perfil completo do usuário conectado.The full profile of the signed-in user.
O perfil completo do gerente e dos subordinados diretos do usuário conectado.The full profile of the signed-in user's manager and direct reports.
O perfil básico dos grupos de que o usuário conectado é membro.The basic profile of the groups that the signed-in user is a member of.

Observação: a combinação dos dois escopos concede mais acesso do que é mencionado aqui para operações me.Note: The combination of the two scopes grants more access than that noted here for me operations.
User.Read.All e Group.Read.AllUser.Read.All and Group.Read.All
Serviço de gerenciamento de grupos que permite que os usuários criem e gerenciem grupos.Group management service that allows users to create and manage groups.Ler o perfil completo de todos os grupos e usuários em nome do usuário conectado.Read full profile of all groups and users on behalf of the signed-in user.
Ler os perfis completos dos gerentes e dos subordinados diretos dos usuários.Read full profiles for users' manager and direct reports.
Ler o perfil completo das associações de grupo dos usuários.Read full profile of users' group memberships.
Ler o perfil completo das associações de grupo dos grupos.Read full profile of groups' group memberships.
Ler o perfil completo das associações dos grupos.Read full profile of groups' members.
Criar e atualizar grupos e suas propriedades de navegação (membros).Create and update groups and their navigation properties (members).
User.Read.All e Group.ReadWrite.AllUser.Read.All and Group.ReadWrite.All
Ler todos os objetos do diretório (incluindo propriedades de navegação).Read all directory objects (including navigation properties).Directory.Read.AllDirectory.Read.All
Ler todos os objetos do diretório (incluindo propriedades de navegação).Read all directory objects (including navigation properties).
Criar e atualizar objetos de usuário e grupo.Create and update user and group objects.
Não é permitido excluir usuários ou grupos.No user or group deletion.

Observação: nem todos os privilégios concedidos estão listados aqui.Note: Not all privileges granted are listed here.
Directory.ReadWrite.AllDirectory.ReadWrite.All
Atuar como o usuário conectado.Act as the signed-in user.Ler e gravar objetos de diretório (incluindo propriedades de navegação) em nome do usuário conectado.Read and write directory objects (including navigation properties) on behalf of the signed-in user.Directory.AccessAsUser.AllDirectory.AccessAsUser.All

Acesso padrão para administradores, usuários e usuários convidados Default access for administrators, users, and guest users

A tabela a seguir lista o acesso padrão de administradores (globais), usuários e usuários convidados no diretório.The following table lists the default access of (global) administrators, users, and guest users in the directory.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.The default access may be further augmented or restricted based on configuration settings for the directory and/or a user's membership in one or more directory roles.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).For more detailed information about configuring the access of users and guest users to directory data, see Create or edit users in 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).For more information about the access associated with various directory roles, see Assigning administrator roles in Azure AD.

Tipo de usuárioUser TypeAcessarAccess
Administrador GlobalGlobal AdministratorLer todos os objetos do diretório.Read all directory objects.
Criar, atualizar e excluir todos os objetos do diretórioCreate, Update, and Delete all directory objects
UsuárioUserLer todos os objetos do diretório.Read all directory objects.
Criar aplicativos e entidades de serviço associadas.Create applications and associated service principals.
Atualizar seu perfil.Update their profile.
Atualizar grupos que possuem (e a propriedade de membros).Update groups that they own (and the members property).
Atualizar aplicativos e entidades de serviço que possuem.Update applications and service principals that they own.
Excluir aplicativos e entidades de serviço que possuem.Delete applications and service principals that they own.
Usuário convidadoGuest UserLer seu perfil completo.Read their full profile.
Ler os perfis básicos de todos os outros usuáriosRead the basic profiles of all other users
Ler o perfil básico de todos os grupos.Read basic profile of all groups.
Ler aplicativos.Read applications.
Atualizar algumas propriedades de seu perfil.Update some properties of their profile.
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).No user or group search (see User and group search limitations for guest users below).

Limitações de pesquisa de usuários e grupos para usuários convidados User and group search limitations for guest users

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).User and group search capabilities allow the app to search for any user or group in the customer directory by performing queries against the users or groups resource set (for example, https://graph.windows.net/myorganization/users?api-version=1.6).Administradores e usuários têm acesso a essa funcionalidade.Both administrators and users have this capability.Usuários convidados não têm.Guest users do not.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.If the signed-in user is a guest user, depending on the permission scope, an app can read the profile of a specific user or group by using the object ID or user principal name (UPN) for a user or the object ID for a group (for example, https://graph.windows.net/myorganization/users/241f22af-f634-44c0-9a15-c8cd2cea5531?api-version=1.6); however, it cannot perform queries against the users or groups resource set that potentially request more than one entity.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.For example, depending on the permission scope, the app can read the profiles of users or groups that it obtains by following links in navigation properties, but it cannot issue a query to return all users or groups in the directory.

Recursos adicionais Additional resources

© 2018 Microsoft