Permissões e consentimento no ponto de extremidade v1.0 do Azure Active DirectoryPermissions and consent in the Azure Active Directory v1.0 endpoint

Aplica-se a:Applies to:
  • Ponto de extremidade do Azure AD v1.0Azure AD v1.0 endpoint

O Microsoft Azure Active Directory (Azure AD) faz uso extensivo de permissões para fluxos OAuth e OpenID Connect (OIDC).Azure Active Directory (Azure AD) makes extensive use of permissions for both OAuth and OpenID Connect (OIDC) flows. Quando seu aplicativo receber um token de acesso do Azure AD, o token de acesso incluirá declarações que descrevem as permissões que seu aplicativo tem em relação a um recurso específico.When your app receives an access token from Azure AD, the access token will include claims that describe the permissions that your app has in respect to a particular resource.

As permissões, também conhecidas como escopos, facilitam a autorização para o recurso porque o recurso só precisa verificar se o token contém a permissão apropriada para a API que está chamando o aplicativo.Permissions, also known as scopes, make authorization easy for the resource because the resource only needs to check that the token contains the appropriate permission for whatever API the app is calling.

Tipos de permissõesTypes of permissions

O Microsoft Active Directory do Azure define dois tipos de permissões:Azure AD defines two kinds of permissions:

  • Permissões delegadas - são usadas por aplicativos que têm um usuário conectado presente.Delegated permissions - Are used by apps that have a signed-in user present. Para esses aplicativos, o usuário ou administrador consente as permissões solicitadas pelo aplicativo e este recebe permissão para agir como o usuário conectado na hora de fazer chamadas à API.For these apps, either the user or an administrator consents to the permissions that the app requests and the app is delegated permission to act as the signed-in user when making calls to an API. Dependendo da API, o usuário talvez não consiga dar o consentimento diretamente; em vez disso, seria necessário um administrador para fornecer o "consentimento do administrador".Depending on the API, the user may not be able to consent to the API directly and would instead require an administrator to provide "admin consent".
  • Permissões de aplicativo - são usadas por aplicativos executados sem um usuário conectado presente; por exemplo, aplicativos executados como serviços em segundo plano ou daemons.Application permissions - Are used by apps that run without a signed-in user present; for example, apps that run as background services or daemons. As permissões de aplicativo só podem ser consentidas por um administrador porque eles são geralmente poderosos e permitem o acesso a dados entre limites de usuário, ou a dados que seriam restritos aos administradores.Application permissions can only be consented by an administrator because they are typically powerful and allow access to data across user-boundaries, or data that would otherwise be restricted to administrators.

Permissões efetivas são as permissões que seu aplicativo terá ao fazer solicitações para uma API.Effective permissions are the permissions that your app will have when making requests to an API.

  • Para obter permissões delegadas, as permissões efetivas do seu aplicativo será a interseção menos privilegiadas das permissões delegadas que tiver recebido o aplicativo (por meio de consentimento) e os privilégios do usuário conectado no momento.For delegated permissions, the effective permissions of your app will be the least privileged intersection of the delegated permissions the app has been granted (through consent) and the privileges of the currently signed-in user. Seu aplicativo não pode ter mais privilégios que o usuário conectado.Your app can never have more privileges than the signed-in user. Dentro das organizações, os privilégios do usuário conectado podem ser determinados pela política ou por associação em uma ou mais funções de administrador.Within organizations, the privileges of the signed-in user may be determined by policy or by membership in one or more administrator roles. Para saber quais funções de administrador podem consentir as permissões delegadas, consulte Permissões da função de administrador no Microsoft Azure Active Directory.To learn which administrator roles can consent to delegated permissions, see Administrator role permissions in Azure AD. Por exemplo, suponha que seu aplicativo tenha recebido a User.ReadWrite.All a permissão delegada no Microsoft Graph.For example, assume your app has been granted the User.ReadWrite.All delegated permission in Microsoft Graph. Essa permissão concede uma permissão ao seu aplicativo para ler e atualizar o perfil de todos os usuários em uma organização.This permission nominally grants your app permission to read and update the profile of every user in an organization. Se o usuário conectado for um administrador global, seu aplicativo poderá atualizar o perfil de todos os usuários na organização.If the signed-in user is a global administrator, your app will be able to update the profile of every user in the organization. No entanto, se o usuário conectado não estiver em uma função de administrador, seu aplicativo poderá atualizar apenas o perfil do usuário conectado.However, if the signed-in user is not in an administrator role, your app will be able to update only the profile of the signed-in user. Não poderá atualizar os perfis de outros usuários na organização porque o que ele tem permissão para agir em nome de usuário não tem os privilégios.It will not be able to update the profiles of other users in the organization because the user that it has permission to act on behalf of does not have those privileges.
  • Para permissões de aplicativo, as permissões efetivas do seu aplicativo são o nível completo de privilégios indicado pela permissão.For application permissions, the effective permissions of your app are the full level of privileges implied by the permission. Por exemplo, um aplicativo que tenha o User.ReadWrite.All permissão de aplicativo pode atualizar o perfil de todos os usuários na organização.For example, an app that has the User.ReadWrite.All application permission can update the profile of every user in the organization.

Atributos de permissãoPermission attributes

As permissões no AD do Azure têm um número de propriedades que ajudam, administradores ou desenvolvedores de aplicativo a tomarem decisões conscientes sobre o que a permissão concede acesso.Permissions in Azure AD have a number of properties that help users, administrators, or app developers make informed decisions about what the permission grants access to.

Observação

Você pode exibir as permissões de um aplicativo do Azure AD ou a Entidade de Serviço expõe usando o portal do Azure ou o PowerShell.You can view the permissions that an Azure AD Application or Service Principal exposes using the Azure portal, or PowerShell. Tente este script para exibir as permissões expostas pelo Microsoft Graph.Try this script to view the permissions exposed by Microsoft Graph.

Connect-AzureAD

# Get OAuth2 Permissions/delegated permissions
(Get-AzureADServicePrincipal -filter "DisplayName eq 'Microsoft Graph'").OAuth2Permissions

# Get App roles/application permissions
(Get-AzureADServicePrincipal -filter "DisplayName eq 'Microsoft Graph'").AppRoles
Nome da propriedadeProperty name DESCRIÇÃODescription ExemploExample
ID É um valor de GUID que identifica exclusivamente esta permissão.Is a GUID value that uniquely identifies this permission. 570282fd-fa5c-430d-a7fd-fc8dc98a9dca570282fd-fa5c-430d-a7fd-fc8dc98a9dca
IsEnabled Indica se essa permissão está disponível para uso.Indicates whether this permission is available for use. truetrue
Type Indica se essa permissão requer o consentimento do usuário ou consentimento do administrador.Indicates whether this permission requires user consent or admin consent. UsuárioUser
AdminConsentDescription É uma descrição que é exibida para os administradores durante as experiências de consentimento do administradorIs a description that's shown to administrators during the admin consent experiences Permite que o aplicativo leia emails nas caixas de entrada dos usuários.Allows the app to read email in user mailboxes.
AdminConsentDisplayName É um nome fácil exibido aos administradores durante as experiências de consentimento do administrador.Is the friendly name that's shown to administrators during the admin consent experience. Ler email de usuárioRead user mail
UserConsentDescription É uma descrição que é exibida aos usuários durante a experiência de consentimento do usuário.Is a description that's shown to users during a user consent experience. Permite que o aplicativo leia emails em sua caixa de email.Allows the app to read email in your mailbox.
UserConsentDisplayName É um nome fácil que é exibido aos usuários durante uma experiência de consentimento do usuário.Is the friendly name that's shown to users during a user consent experience. Leia seu emailRead your mail
Value É a cadeia de caracteres que é usada para identificar a permissão durante os fluxos de autorização OAuth 2.0.Is the string that's used to identify the permission during OAuth 2.0 authorize flows. Value também pode ser combinado com a cadeia de caracteres do URI da ID do aplicativo para formar um nome totalmente qualificado de permissão.Value may also be combined with the App ID URI string in order to form a fully qualified permission name. Mail.Read

Os aplicativos no Microsoft Azure Active Directory dependem de autorização para acessar os recursos necessários ou APIs.Applications in Azure AD rely on consent in order to gain access to necessary resources or APIs. Há um número de tipos de autorização que seu aplicativo precisa saber para ser bem-sucedido.There are a number of kinds of consent that your app may need to know about in order to be successful. Se você estiver definindo permissões, também precisará entender como seus usuários terá acesso ao seu aplicativo ou a API.If you are defining permissions, you will also need to understand how your users will gain access to your app or API.

  • Consentimento do usuário estático - ocorre automaticamente durante o OAuth 2.0 autorizar fluxo quando você especifica o recurso que deseja que seu aplicativo interaja.Static user consent - Occurs automatically during the OAuth 2.0 authorize flow when you specify the resource that your app wants to interact with. No cenário de consentimento do usuário estático, seu aplicativo deve ter já especificado todas as permissões necessárias na configuração do aplicativo no portal do Azure.In the static user consent scenario, your app must have already specified all the permissions it needs in the app's configuration in the Azure portal. Se o usuário (ou um administrador, conforme apropriado) não concedeu permissão para este aplicativo, em seguida, o Microsoft Active Directory solicitará ao usuário para fornecer consentimento neste momento.If the user (or administrator, as appropriate) has not granted consent for this app, then Azure AD will prompt the user to provide consent at this time.

    Saiba mais sobre como registrar um aplicativo do Microsoft Azure Active Directory que solicita acesso a um conjunto estático de APIs.Learn more about registering an Azure AD app that requests access to a static set of APIs.

  • Consentimento do usuário dinâmico - é um recurso do modelo de aplicativo do Microsoft Azure Active Directory e v2.Dynamic user consent - Is a feature of the v2 Azure AD app model. Nesse cenário, o aplicativo solicita um conjunto de permissões que precisa do fluxo de autorização OAuth 2.0 para aplicativos v2.In this scenario, your app requests a set of permissions that it needs in the OAuth 2.0 authorize flow for v2 apps. Se o usuário não aceitou, serão solicitados a consentir neste momento.If the user has not consented already, they will be prompted to consent at this time. Saiba mais sobre o consentimento dinâmico.Learn more about dynamic consent.

    Importante

    O consentimento dinâmico pode ser conveniente, mas apresenta um grande desafio para permissões que exigem o consentimento do administrador, desde que a experiência de consentimento do administrador não saiba sobre essas permissões no momento da autorização.Dynamic consent can be convenient, but presents a big challenge for permissions that require admin consent, since the admin consent experience doesn't know about those permissions at consent time. Se você precisar de permissões de administrador com privilégios ou se seu aplicativo usar o consentimento dinâmico, você deverá registrar todas as permissões no portal do Azure (não apenas o subconjunto de permissões que exigem o consentimento do administrador).If you require admin privileged permissions or if your app uses dynamic consent, you must register all of the permissions in the Azure portal (not just the subset of permissions that require admin consent). Isso permite que os administradores de locatários deem consentimento em nome de todos os seus usuários.This enables tenant admins to consent on behalf of all their users.

  • Consentimento do administrador - é necessário quando seu aplicativo precisa ter acesso a determinadas permissões com alto privilégio.Admin consent - Is required when your app needs access to certain high-privilege permissions. O consentimento do administrador faz com que os administradores tenham alguns controles adicionais antes de autorizar aplicativos ou usuários a acessar dados altamente privilegiados da organização.Admin consent ensures that administrators have some additional controls before authorizing apps or users to access highly privileged data from the organization. Saiba mais sobre como conceder consentimento do administrador.Learn more about how to grant admin consent.

Práticas recomendadasBest practices

Práticas recomendadas de clienteClient best practices

  • Solicite apenas permissões de que seu aplicativo precisa.Only request for permissions that your app needs. Aplicativos com um número excessivo de permissões estão em risco de exposição de dados de usuário se eles forem comprometidos.Apps with too many permissions are at risk of exposing user data if they are compromised.
  • Escolha entre permissões delegadas e permissões de aplicativo com base no cenário compatível com seu aplicativo.Choose between delegated permissions and application permissions based on the scenario that your app supports.
    • Use sempre permissões delegadas se a chamada estiver sendo feita em nome do usuário.Always use delegated permissions if the call is being made on behalf of a user.
    • Use somente permissões de aplicativo se o aplicativo for não interativo e não estiver fazendo chamadas em nome de um usuário específico.Only use application permissions if the app is non-interactive and not making calls on behalf of any specific user. As permissões de aplicativo são altamente privilegiadas e devem ser usadas apenas quando absolutamente necessário.Application permissions are highly privileged and should only be used when absolutely necessary.
  • Ao usar um aplicativo com base no ponto de extremidade v 2.0, defina sempre as permissões estáticas (as especificadas no registro de aplicativo) como o superconjunto das permissões dinâmicas solicitadas no tempo de execução (aquelas especificadas no código e enviados como parâmetros de consulta na solicitação de autorização) para que os cenários, como o administrador de consentimento, funcionem corretamente.When using an app based on the v2.0 endpoint, always set the static permissions (those specified in your application registration) to be the superset of the dynamic permissions you request at runtime (those specified in code and sent as query parameters in your authorize request) so that scenarios like admin consent works correctly.

Melhores práticas de API/recursoResource/API best practices

  • Recursos que expõem as APIs devem definir permissões que são específicas para os dados ou ações que estão protegendo.Resources that expose APIs should define permissions that are specific to the data or actions that they are protecting. Essa melhor prática ajuda a fazer com que os clientes não acabem tendo permissão para acessar os dados desnecessários e que os usuários sejam bem informados sobre os dados que estão aceitando.Following this best practice helps to ensure that clients do not end up with permission to access data that they do not need and that users are well informed about what data they are consenting to.
  • Recursos devem definir explicitamente Read e ReadWrite permissões separadamente.Resources should explicitly define Read and ReadWrite permissions separately.
  • Recursos deverão marcar quaisquer permissões que permitam o acesso a dados entre limites de usuário como Admin permissões.Resources should mark any permissions that allow access to data across user boundaries as Admin permissions.
  • Os recursos devem seguir o padrão de nomenclatura Subject.Permission[.Modifier], em que:Resources should follow the naming pattern Subject.Permission[.Modifier], where:
    • Subject corresponde ao tipo de dados disponívelSubject corresponds with the type of data that is available

    • Permission corresponde à ação que um usuário pode realizar em relação aos dadosPermission corresponds to the action that a user may take upon that data

    • Modifier é usado, opcionalmente, para descrever especializações de outra permissãoModifier is used optionally to describe specializations of another permission

      Por exemplo:For example:

    • Mail.Read - permite que os usuários leiam o email.Mail.Read - Allows users to read mail.

    • Mail.Read - permite que os usuários leiam o email.Mail.ReadWrite - Allows users to read or write mail.

    • Mail.ReadWrite.All - permite que um administrador ou usuário acesse todos os emails da organização.Mail.ReadWrite.All - Allows an administrator or user to access all mail in the organization.