Permissões e consentimento no ponto de extremidade da plataforma Microsoft IdentityPermissions and consent in the Microsoft identity platform endpoint

Aplica-se a:Applies to:
  • ponto de extremidade da plataforma de identidade da MicrosoftMicrosoft identity platform endpoint

Os aplicativos que se integram à plataforma de identidade da Microsoft seguem um modelo de autorização que dá aos usuários e administradores controle sobre como os dados podem ser acessados.Applications that integrate with Microsoft identity platform follow an authorization model that gives users and administrators control over how data can be accessed. A implementação do modelo de autorização foi atualizada no ponto de extremidade da plataforma de identidade da Microsoft e altera como um aplicativo deve interagir com a plataforma de identidade da Microsoft.The implementation of the authorization model has been updated on the Microsoft identity platform endpoint, and it changes how an app must interact with the Microsoft identity platform. Este artigo aborda os conceitos básicos deste modelo de autorização, incluindo escopos, permissões e consentimento.This article covers the basic concepts of this authorization model, including scopes, permissions, and consent.

Observação

O ponto de extremidade da plataforma Microsoft Identity não oferece suporte a todos os cenários e recursos.The Microsoft identity platform endpoint does not support all scenarios and features. Para determinar se você deve usar o ponto de extremidade da plataforma de identidade da Microsoft, leia sobre as limitações da plataforma de identidade da Microsoft.To determine whether you should use the Microsoft identity platform endpoint, read about Microsoft identity platform limitations.

Permissões e escoposScopes and permissions

A plataforma de identidade da Microsoft implementa o protocolo de autorização OAuth 2.0.The Microsoft identity platform implements the OAuth 2.0 authorization protocol. O OAuth 2.0 é um método pelo qual um aplicativo de terceiros pode acessar recursos hospedados na Web em nome do usuário.OAuth 2.0 is a method through which a third-party app can access web-hosted resources on behalf of a user. Qualquer recurso hospedado na Web que se integre à plataforma de identidade da Microsoft tem um identificador de recurso ou URI de ID de Aplicativo.Any web-hosted resource that integrates with the Microsoft identity platform has a resource identifier, or Application ID URI. Por exemplo, alguns dos recursos hospedados na Web da Microsoft incluem:For example, some of Microsoft's web-hosted resources include:

  • Microsoft Graph: https://graph.microsoft.comMicrosoft Graph: https://graph.microsoft.com
  • API de Email do Office 365: https://outlook.office.comOffice 365 Mail API: https://outlook.office.com
  • Azure AD Graph: https://graph.windows.netAzure AD Graph: https://graph.windows.net

Observação

Recomendamos que você use o Microsoft Graph em vez do Azure AD Graph, API de Email do Office 365 e outros recursos.We strongly recommend that you use Microsoft Graph instead of Azure AD Graph, Office 365 Mail API, etc.

Isso se aplica a todos os recursos de terceiros que se integraram à plataforma de identidade da Microsoft.The same is true for any third-party resources that have integrated with the Microsoft identity platform. Qualquer um desses recursos também pode definir um conjunto de permissões que pode ser usado para dividir a funcionalidade desse recurso em partes menores.Any of these resources also can define a set of permissions that can be used to divide the functionality of that resource into smaller chunks. Por exemplo, o Microsoft Graph definiu permissões para realizar as seguintes tarefas, entre outras:As an example, Microsoft Graph has defined permissions to do the following tasks, among others:

  • Ler o calendário de um usuárioRead a user's calendar
  • Escrever no calendário de um usuárioWrite to a user's calendar
  • Enviar email como um usuárioSend mail as a user

Ao definir esses tipos de permissões, o recurso tem controle refinado sobre seus dados e como a funcionalidade de API é exposta.By defining these types of permissions, the resource has fine-grained control over its data and how API functionality is exposed. Um aplicativo de terceiros pode solicitar essas permissões de usuários e administradores que devem aprovar a solicitação antes que o aplicativo possa acessar dados ou agir em nome do usuário.A third-party app can request these permissions from users and administrators, who must approve the request before the app can access data or act on a user's behalf. Ao dividir a funcionalidade do recurso em conjuntos menores de permissão, os aplicativos de terceiros podem ser criados para solicitar apenas as permissões específicas que eles precisam para realizar suas funções.By chunking the resource's functionality into smaller permission sets, third-party apps can be built to request only the specific permissions that they need to perform their function. Os usuários e administradores podem saber exatamente quais dados o aplicativo tem acesso e podem ter mais certeza de que ele não está se comportando com más intenções.Users and administrators can know exactly what data the app has access to, and they can be more confident that it isn't behaving with malicious intent. Os desenvolvedores devem sempre obedecer o conceito de privilégios mínimos, solicitando apenas as permissões necessárias para que seus aplicativos funcionem.Developers should always abide by the concept of least privilege, asking for only the permissions they need for their applications to function.

No OAuth 2.0, esses tipos de permissão são chamados de escopos.In OAuth 2.0, these types of permissions are called scopes. Eles também são chamados de permissões.They are also often referred to as permissions. Uma permissão é representada na plataforma de identidade da Microsoft como um valor de cadeia de caracteres.A permission is represented in the Microsoft identity platform as a string value. Continuando com o exemplo do Microsoft Graph,o valor da cadeia de caracteres para cada permissão é:Continuing with the Microsoft Graph example, the string value for each permission is:

  • Ler o calendário de um usuário usando o Calendars.ReadRead a user's calendar by using Calendars.Read
  • Escrever no calendário de um usuário usando o Calendars.ReadWriteWrite to a user's calendar by using Calendars.ReadWrite
  • Enviar email como um usuário usando Mail.SendSend mail as a user using by Mail.Send

Um aplicativo geralmente solicita essas permissões especificando os escopos em solicitações para o ponto de extremidade de autorização da plataforma de identidade da Microsoft.An app most commonly requests these permissions by specifying the scopes in requests to the Microsoft identity platform authorize endpoint. No entanto, certas permissões de alto privilégio só podem ser concedidas por meio do consentimento do administrador e solicitadas/concedidas usando o ponto de extremidade de consentimentodoHowever, certain high privilege permissions can only be granted through administrator consent and requested/granted using the administrator consent endpoint. Continue lendo para saber mais.Read on to learn more.

Tipos de permissãoPermission types

A plataforma de identidade da Microsoft dá suporte a dois tipos de permissões: permissões delegadas e permissões de aplicativo.Microsoft identity platform supports two types of permissions: delegated permissions and application 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 um administrador consentirá com as permissões solicitadas pelo aplicativo e o aplicativo será delegado a permissão para atuar como o usuário conectado ao fazer chamadas para o recurso de destino.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 the target resource. Algumas permissões delegadas podem ser concedidas por usuários não administrativos, mas algumas permissões de privilégios mais altos exigem o consentimento do administrador.Some delegated permissions can be consented to by non-administrative users, but some higher-privileged permissions require administrator consent. 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.

  • 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 concedidas pelo administrador.Application permissions can only be consented by an administrator.

Permissões efetivas são as permissões que seu aplicativo terá ao fazer solicitações para o recurso de destino.Effective permissions are the permissions that your app will have when making requests to the target resource. É importante entender a diferença entre as permissões delegadas e de aplicativo que seu aplicativo recebe e suas permissões efetivas ao fazer chamadas para o recurso de destino.It's important to understand the difference between the delegated and application permissions that your app is granted and its effective permissions when making calls to the target resource.

  • Para obter permissões delegadas, as permissões efetivas do aplicativo serão a interseção menos privilegiada das permissões delegadas que tiverem 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 (via 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 permissão delegada User.ReadWrite.All.For example, assume your app has been granted the User.ReadWrite.All delegated permission. 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 somente o perfil do usuário conectado.However, if the signed-in user isn't 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 aplicativo serão o nível completo de privilégios indicado pela permissão.For application permissions, the effective permissions of your app will be the full level of privileges implied by the permission. Por exemplo, um aplicativo que tenha a permissão de aplicativo User.ReadWrite.All poderá 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.

Escopos do OpenID ConnectOpenID Connect scopes

A implementação da plataforma Microsoft Identity do OpenID Connect tem alguns escopos bem definidos que não se aplicam a um recurso específico openid: email profile,, e offline_access.The Microsoft identity platform implementation of OpenID Connect has a few well-defined scopes that do not apply to a specific resource: openid, email, profile, and offline_access. Os escopos address e phone do OpenID Connect não são compatíveis.The address and phone OpenID Connect scopes are not supported.

openidopenid

Se um aplicativo fizer conexão usando o OpenID Connect, ele deverá solicitar o escopo openid.If an app performs sign-in by using OpenID Connect, it must request the openid scope. O escopo openid aparecerá na página de consentimento da conta corporativa como a permissão "Conectar você" e na página de consentimento da conta pessoal da Microsoft como a permissão "Exibir seu perfil e se conectar a aplicativos e serviços usando sua conta da Microsoft".The openid scope shows on the work account consent page as the "Sign you in" permission, and on the personal Microsoft account consent page as the "View your profile and connect to apps and services using your Microsoft account" permission. Com essa permissão, um aplicativo pode receber um identificador exclusivo para o usuário na forma da declaração sub.With this permission, an app can receive a unique identifier for the user in the form of the sub claim. Ele também fornece ao aplicativo acesso ao ponto de extremidade UserInfo.It also gives the app access to the UserInfo endpoint. O openid escopo pode ser usado no ponto de extremidade de token da plataforma de identidade da Microsoft para adquirir tokens de ID, que podem ser usados pelo aplicativo para autenticação.The openid scope can be used at the Microsoft identity platform token endpoint to acquire ID tokens, which can be used by the app for authentication.

emailemail

O escopo do email pode ser usado com o escopo do openid e com muitos outros.The email scope can be used with the openid scope and any others. Ele concede ao aplicativo acesso ao endereço de email principal do usuário na forma da declaração email .It gives the app access to the user's primary email address in the form of the email claim. A email declaração será incluída em um token somente se um endereço de email estiver associado à conta de usuário, que nem sempre é o caso.The email claim is included in a token only if an email address is associated with the user account, which isn't always the case. Se estiver usando o escopo de email, seu aplicativo deverá estar preparado para lidar com casos em que a declaração email não existe no token.If it uses the email scope, your app should be prepared to handle a case in which the email claim does not exist in the token.

profileprofile

O escopo do profile pode ser usado com o escopo do openid e com muitos outros.The profile scope can be used with the openid scope and any others. Ele fornece o acesso de aplicativo a uma quantidade substancial de informações sobre o usuário.It gives the app access to a substantial amount of information about the user. As informações que ele pode acessar incluem, mas não se limitam a, o nome do usuário, o sobrenome, o nome de usuário preferencial e a ID de objeto.The information it can access includes, but isn't limited to, the user's given name, surname, preferred username, and object ID. Para obter uma lista completa de declarações de perfil disponíveis no parâmetro id_tokens para um usuário específico, confira a id_tokensreferência.For a complete list of the profile claims available in the id_tokens parameter for a specific user, see the id_tokens reference.

offline_accessoffline_access

O escopo do offline_access concede ao seu aplicativo acesso a recursos em nome do usuário por um longo período.The offline_access scope gives your app access to resources on behalf of the user for an extended time. Na página de consentimento, esse escopo aparece como a permissão "Manter o acesso aos dados para os quais recebeu acesso".On the consent page, this scope appears as the "Maintain access to data you have given it access to" permission. Quando um usuário aprova o offline_access escopo, seu aplicativo pode receber tokens de atualização do ponto de extremidade de token da plataforma de identidade da Microsoft.When a user approves the offline_access scope, your app can receive refresh tokens from the Microsoft identity platform token endpoint. Os tokens de atualização têm uma vida longa.Refresh tokens are long-lived. Seu aplicativo pode obter novos tokens de acesso quando os mais antigos expirarem.Your app can get new access tokens as older ones expire.

Se o aplicativo não solicitar explicitamente o escopo offline_access, ele não receberá tokens de atualização.If your app does not explicitly request the offline_access scope, it won't receive refresh tokens. Isso significa que, ao resgatar um código de autorização no fluxo de código de autorização do OAuth 2.0, você só receberá de volta um token de acesso do ponto de extremidade /token.This means that when you redeem an authorization code in the OAuth 2.0 authorization code flow, you'll receive only an access token from the /token endpoint. O token de acesso é válido por um curto período.The access token is valid for a short time. Geralmente, o token de acesso expira em uma hora.The access token usually expires in one hour. Nesse ponto, seu aplicativo precisa redirecionar o usuário novamente para o ponto de extremidade /authorize para obter um novo código de autorização.At that point, your app needs to redirect the user back to the /authorize endpoint to get a new authorization code. Durante esse redirecionamento, dependendo do tipo de aplicativo, o usuário poderá ou não precisar inserir suas credenciais novamente ou consentir de novo as permissões.During this redirect, depending on the type of app, the user might need to enter their credentials again or consent again to permissions. Embora o offline_access escopo seja solicitado automaticamente pelo servidor, o cliente ainda deve solicitá-lo para receber os tokens de atualização.While the offline_access scope is automatically requested by the server, your client must still request it in order to receive the refresh tokens.

Para obter mais informações sobre como obter e usar tokens de atualização, consulte a referência de protocolo de plataforma de identidade da Microsoft.For more information about how to get and use refresh tokens, see the Microsoft identity platform protocol reference.

Em uma solicitação de autorização do OpenID Connect ou OAuth 2.0, um aplicativo pode solicitar as permissões de que precisa usando o parâmetro de consulta scope.In an OpenID Connect or OAuth 2.0 authorization request, an app can request the permissions it needs by using the scope query parameter. Por exemplo, quando um usuário entra em um aplicativo, o aplicativo envia uma solicitação como o exemplo a seguir (com quebras de linha adicionadas para legibilidade):For example, when a user signs in to an app, the app sends a request like the following example (with line breaks added for legibility):

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=
https%3A%2F%2Fgraph.microsoft.com%2Fcalendars.read%20
https%3A%2F%2Fgraph.microsoft.com%2Fmail.send
&state=12345

O parâmetro scope é uma lista de permissões delegadas separadas por espaço que o aplicativo está solicitando.The scope parameter is a space-separated list of delegated permissions that the app is requesting. Cada permissão é indicada acrescentando o valor da permissão ao identificador do recurso (URI da ID de Aplicativo).Each permission is indicated by appending the permission value to the resource's identifier (the Application ID URI). No exemplo de solicitação, o aplicativo precisa de permissão para ler o calendário e enviar emails como o usuário.In the request example, the app needs permission to read the user's calendar and send mail as the user.

Depois que o usuário inserir suas credenciais, o ponto de extremidade da plataforma de identidade da Microsoft verificará se há um registro correspondente de consentimento do usuário.After the user enters their credentials, the Microsoft identity platform endpoint checks for a matching record of user consent. Se o usuário não consentiu em nenhuma das permissões solicitadas no passado, nem tem um administrador que consentiu essas permissões em nome de toda a organização, o ponto de extremidade da plataforma de identidade da Microsoft solicita que o usuário conceda as permissões solicitadas.If the user has not consented to any of the requested permissions in the past, nor has an administrator consented to these permissions on behalf of the entire organization, the Microsoft identity platform endpoint asks the user to grant the requested permissions.

Observação

Nesse momento, as permissões offline_access ("Manter o acesso aos dados para os quais recebeu acesso") e user.read ("Entrar e ler o seu perfil") são incluídas automaticamente no consentimento inicial para um aplicativo.At this time, the offline_access ("Maintain access to data you have given it access to") and user.read ("Sign you in and read your profile") permissions are automatically included in the initial consent to an application. Essas permissões geralmente são necessárias para a funcionalidade adequada do aplicativo: offline_access dá ao aplicativo acesso aos tokens de atualização, essenciais para aplicativos Web e nativos, enquanto user.read dá acesso à declaração sub, permitindo que o cliente ou aplicativo identifique corretamente o usuário ao longo do tempo e acesse informações básicas do usuário.These permissions are generally required for proper app functionality - offline_access gives the app access to refresh tokens, critical for native and web apps, while user.read gives access to the sub claim, allowing the client or app to correctly identify the user over time and access rudimentary user information.

Captura de tela de exemplo que mostra o consentimento da conta corporativa

Quando o usuário aprovar a solicitação de permissão, o consentimento será registrado para que o usuário não tenha que consentir novamente a cada entrada no aplicativo.When the user approves the permission request, consent is recorded and the user doesn't have to consent again on subsequent sign-ins to the application.

Muitas vezes, quando uma organização adquire uma licença ou assinatura para um aplicativo, a organização deseja configurar proativamente o aplicativo para que ele seja usado por todos os membros.Often, when an organization purchases a license or subscription for an application, the organization wants to proactively set up the application for use by all members of the organization. Como parte desse processo, um administrador pode autorizar que o aplicativo atue em nome de todos os usuários no locatário.As part of this process, an administrator can grant consent for the application to act on behalf of any user in the tenant. Se o administrador conceder permissão para todo o locatário, os funcionários da empresa não virão uma página de consentimento para o aplicativo.If the admin grants consent for the entire tenant, the organization's users won't see a consent page for the application.

Para solicitar consentimento de permissões delegadas para todos os usuários em um locatário, o aplicativo pode usar o ponto de extremidade de consentimento de administrador.To request consent for delegated permissions for all users in a tenant, your app can use the admin consent endpoint.

Além disso, os aplicativos devem usar o ponto de extremidade de consentimento do administrador para solicitar permissões de aplicativo.Additionally, applications must use the admin consent endpoint to request Application Permissions.

Permissões restringidas pelo administradorAdmin-restricted permissions

Algumas permissões de alto privilégio no ecossistema da Microsoft podem ser definidas como restritas ao administrador.Some high-privilege permissions in the Microsoft ecosystem can be set to admin-restricted. Exemplos desses tipos de permissão incluem as seguintes:Examples of these kinds of permissions include the following:

  • Ler os perfis completos de todos os usuários usando User.Read.AllRead all user's full profiles by using User.Read.All
  • Gravar dados no diretório da organização usando o Directory.ReadWrite.AllWrite data to an organization's directory by using Directory.ReadWrite.All
  • Ler todos os grupos no diretório da organização usando Groups.Read.AllRead all groups in an organization's directory by using Groups.Read.All

Embora um usuário consumidor possa conceder acesso de aplicativo para esse tipo de dados, os usuários organizacionais são impedidos de conceder acesso ao mesmo conjunto de dados confidenciais da empresa.Although a consumer user might grant an application access to this kind of data, organizational users are restricted from granting access to the same set of sensitive company data. Se seu aplicativo solicitar acesso a uma dessas permissões de um usuário da organização, o usuário receberá uma mensagem de erro informando que elas não estão autorizadas a dar consentimento às permissões do seu aplicativo.If your application requests access to one of these permissions from an organizational user, the user receives an error message that says they're not authorized to consent to your app's permissions.

Se seu aplicativo requer acesso a escopos restritos a administradores para as organizações, você deve solicitá-los diretamente de um administrador da empresa também usando o ponto de extremidade de consentimento do administrador descrito a seguir.If your app requires access to admin-restricted scopes for organizations, you should request them directly from a company administrator, also by using the admin consent endpoint, described next.

Se o aplicativo está solicitando permissões delegadas de privilégio alto e um administrador concede essas permissões pelo ponto de extremidade de consentimento do administrador, a permissão é concedida para todos os usuários no locatário.If the application is requesting high privilege delegated permissions and an administrator grants these permissions via the admin consent endpoint, consent is granted for all users in the tenant.

Se o aplicativo estiver solicitando permissões de aplicativo e um administrador conceder essas permissões por meio do ponto de extremidade de consentimento do administrador, essa concessão não será feita em nome de qualquer usuário específico.If the application is requesting application permissions and an administrator grants these permissions via the admin consent endpoint, this grant isn't done on behalf of any specific user. Na verdade, o aplicativo cliente recebe as permissões diretamente.Instead, the client application is granted permissions directly. Esses tipos de permissões são usados apenas por serviços de daemon e outros aplicativos não interativos que são executados em segundo plano.These types of permissions are only used by daemon services and other non-interactive applications that run in the background.

Observação

Observe que, depois de conceder o consentimento do administrador usando o ponto de extremidade de consentimento do administrador, você terminou de conceder o consentimento do administrador e os usuários não precisam executar outras ações adicionais.Please note after granting admin consent using the admin consent endpoint, you have finished granting admin consent and users do not need to perform any further additional actions. Depois de conceder o consentimento do administrador, os usuários poderão obter um token de acesso por meio de um fluxo de autenticação típico e o token de acesso resultante terá as permissões consentidas.After granting admin consent, users can get an access token via a typical auth flow and the resulting access token will have the consented permissions.

Quando um administrador da empresa usa seu aplicativo e é direcionado para o ponto de extremidade autorizado, a plataforma de identidade da Microsoft detecta a função do usuário e pergunta se ele gostaria de conceder as permissões solicitadas por você em nome de todo o locatário.When a Company Administrator uses your application and is directed to the authorize endpoint, Microsoft identity platform will detect the user's role and ask them if they would like to consent on behalf of the entire tenant for the permissions you have requested. No entanto, há também um ponto de extremidade de consentimento de administrador dedicado que você pode usar se quiser solicitar proativamente que um administrador conceda permissão em nome do locatário inteiro.However, there is also a dedicated admin consent endpoint you can use if you would like to proactively request that an administrator grants permission on behalf of the entire tenant. O uso desse ponto de extremidade também é necessário para solicitar permissões de aplicativo (que não podem ser solicitadas usando o ponto de extremidade de autorização).Using this endpoint is also necessary for requesting Application Permissions (which can't be requested using the authorize endpoint).

Se você seguir estas etapas, seu aplicativo poderá solicitar permissões para todos os usuários em um locatário, incluindo escopos restringidos pelo administrador.If you follow these steps, your app can request permissions for all users in a tenant, including admin-restricted scopes. Isso é uma operação com privilégios elevados e só deverá ser feita se for necessária para seu cenário.This is a high privilege operation and should only be done if necessary for your scenario.

Para obter um exemplo de código que implementa as etapas, veja o exemplo de escopos restritos ao administrador.To see a code sample that implements the steps, see the admin-restricted scopes sample.

Solicitar as permissões no portal de registro do aplicativoRequest the permissions in the app registration portal

O consentimento do administrador não aceita um parâmetro de escopo e, portanto, todas as permissões solicitadas devem ser definidas estaticamente no registro do aplicativo.The admin consent does not accept a scope parameter, so any permissions being requested must be statically defined in the application's registration. Em geral, é recomendável garantir que as permissões definidas estaticamente para um determinado aplicativo sejam um superconjunto das permissões que serão solicitadas dinamicamente/incrementalmente.In general, it's best practice to ensure that the permissions statically defined for a given application are a superset of the permissions that it will be requesting dynamically/incrementally.

Para configurar a lista de permissões solicitadas estaticamente para um aplicativoTo configure the list of statically requested permissions for an application

  1. Vá para seu aplicativo na experiência de portal do Azure – registros de aplicativo ou crie um aplicativo , caso ainda não tenha feito isso.Go to your application in the Azure portal – App registrations experience, or create an app if you haven't already.
  2. Localize a seção permissões de API e, dentro das permissões de API, clique em adicionar uma permissão.Locate the API Permissions section, and within the API permissions click Add a permission.
  3. Selecione Microsoft Graph na lista de APIs disponíveis e, em seguida, adicione as permissões que seu aplicativo requer.Select Microsoft Graph from the list of available APIs and then add the permissions that your app requires.
  4. Salve o registro do aplicativo.Save the app registration.

Normalmente, quando você cria um aplicativo que usa o ponto de extremidade de consentimento do administrador, o aplicativo precisa de uma página ou de um modo de exibição em que o administrador possa aprovar as permissões do aplicativo.Typically, when you build an application that uses the admin consent endpoint, the app needs a page or view in which the admin can approve the app's permissions. Essa página pode ser parte do fluxo de inscrição no aplicativo, parte das configurações do aplicativo ou um fluxo dedicado de "conexão".This page can be part of the app's sign-up flow, part of the app's settings, or it can be a dedicated "connect" flow. Em muitos casos, faz sentido que o aplicativo somente mostre o modo de exibição "conectar" depois que o usuário entra com uma conta corporativa ou de estudante da Microsoft.In many cases, it makes sense for the app to show this "connect" view only after a user has signed in with a work or school Microsoft account.

Ao conectar o usuário ao seu aplicativo, você pode identificar a organização à qual o administrador pertence antes de pedir a ele que aprove as permissões necessárias.When you sign the user into your app, you can identify the organization to which the admin belongs before asking them to approve the necessary permissions. Embora não seja estritamente necessário, isso pode ajudá-lo a criar uma experiência mais intuitiva para os usuários empresariais.Although not strictly necessary, it can help you create a more intuitive experience for your organizational users. Para conectar o usuário, siga nossos tutoriais de protocolo de plataforma de identidade da Microsoft.To sign the user in, follow our Microsoft identity platform protocol tutorials.

Solicitar permissões de um administrador de diretórioRequest the permissions from a directory admin

Quando estiver pronto para solicitar permissões do administrador da sua organização, você poderá redirecionar o usuário para o ponto de extremidade de consentimento do administradorda plataforma de identidade da Microsoft.When you're ready to request permissions from your organization's admin, you can redirect the user to the Microsoft identity platform admin consent endpoint.

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/adminconsent?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&state=12345
&redirect_uri=http://localhost/myapp/permissions
// Pro tip: Try pasting the below request in a browser!
https://login.microsoftonline.com/common/adminconsent?client_id=6731de76-14a6-49ae-97bc-6eba6914391e&state=12345&redirect_uri=http://localhost/myapp/permissions
ParâmetroParameter CondiçãoCondition DescriçãoDescription
tenant NecessárioRequired O locatário do diretório para o qual você deseja solicitar permissão.The directory tenant that you want to request permission from. Pode ser fornecido no GUID ou formato de nome amigável, OU referenciado de maneira genérica com common, como visto no exemplo.Can be provided in GUID or friendly name format OR generically referenced with common as seen in the example.
client_id NecessárioRequired A ID do aplicativo (cliente) que a portal do Azure – registros de aplicativo experiência atribuída ao seu aplicativo.The Application (client) ID that the Azure portal – App registrations experience assigned to your app.
redirect_uri NecessárioRequired O URI de redirecionamento onde você deseja que a resposta seja enviada para ser tratada pelo aplicativo.The redirect URI where you want the response to be sent for your app to handle. Ela deve corresponder exatamente a um redirecionamento de URIs que você registrou no portal de registro de aplicativo.It must exactly match one of the redirect URIs that you registered in the app registration portal.
state RecomendadoRecommended Um valor incluído na solicitação também será retornado na resposta do token.A value included in the request that will also be returned in the token response. Pode ser uma cadeia de caracteres de qualquer conteúdo desejado.It can be a string of any content you want. Use o estado para codificar as informações sobre o estado do usuário no aplicativo antes da solicitação de autenticação ocorrida, como a página ou exibição em que ele estava.Use the state to encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.

Neste ponto, o Azure AD requer um administrador de locatários para entrar e concluir a solicitação.At this point, Azure AD requires a tenant administrator to sign in to complete the request. O administrador deverá aprovar todas as permissões que você solicitou para o aplicativo no portal de registro de aplicativos.The administrator is asked to approve all the permissions that you have requested for your app in the app registration portal.

Resposta bem-sucedidaSuccessful response

Se o administrador aprovar as permissões para o seu aplicativo, a resposta bem-sucedida será:If the admin approves the permissions for your app, the successful response looks like this:

GET http://localhost/myapp/permissions?tenant=a8990e1f-ff32-408a-9f8e-78d3b9139b95&state=state=12345&admin_consent=True
ParâmetroParameter DescriçãoDescription
tenant O locatário do diretório que concedeu as permissões solicitadas, no formato de GUID.The directory tenant that granted your application the permissions it requested, in GUID format.
state Um valor incluído na solicitação também será retornado na resposta do token.A value included in the request that also will be returned in the token response. Pode ser uma cadeia de caracteres de qualquer conteúdo desejado.It can be a string of any content you want. O estado é usado para codificar as informações sobre o estado do usuário no aplicativo antes da solicitação de autenticação ocorrida, como a página ou exibição em que ele estava.The state is used to encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.
admin_consent Será definido como True.Will be set to True.

Resposta de erroError response

Se o administrador não aprovar as permissões para o seu aplicativo, a resposta de falha será:If the admin does not approve the permissions for your app, the failed response looks like this:

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
ParâmetroParameter DescriçãoDescription
error Uma cadeia de caracteres de códigos de erro que pode ser usada para classificar tipos de erro que ocorrem e pode ser usada para responder aos erros.An error code string that can be used to classify types of errors that occur, and can be used to react to errors.
error_description Uma mensagem de erro específica que pode ajudar um desenvolvedor a identificar a causa raiz de um erro.A specific error message that can help a developer identify the root cause of an error.

Depois de receber uma resposta bem-sucedida do ponto de extremidade de consentimento do administrador, o aplicativo terá as permissões solicitadas por ele.After you've received a successful response from the admin consent endpoint, your app has gained the permissions it requested. Em seguida, você pode solicitar um token para o recurso desejado.Next, you can request a token for the resource you want.

Usando permissõesUsing permissions

Depois que o usuário consente permissões para o aplicativo, este pode adquirir tokens de acesso que representam a permissão do seu aplicativo para acessar um recurso em alguma capacidade.After the user consents to permissions for your app, your app can acquire access tokens that represent your app's permission to access a resource in some capacity. Um token de acesso só pode ser usado para um único recurso, mas codificada dentro do token de acesso estará cada permissão que o aplicativo recebeu para esse recurso.An access token can be used only for a single resource, but encoded inside the access token is every permission that your app has been granted for that resource. Para adquirir um token de acesso, seu aplicativo pode fazer uma solicitação para o ponto de extremidade de token da plataforma de identidade da Microsoft, desta forma:To acquire an access token, your app can make a request to the Microsoft identity platform token endpoint, like this:

POST common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/json

{
    "grant_type": "authorization_code",
    "client_id": "6731de76-14a6-49ae-97bc-6eba6914391e",
    "scope": "https://outlook.office.com/mail.read https://outlook.office.com/mail.send",
    "code": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq..."
    "redirect_uri": "https://localhost/myapp",
    "client_secret": "zc53fwe80980293klaj9823"  // NOTE: Only required for web apps
}

Você pode usar o token de acesso resultante em solicitações HTTP para o recurso.You can use the resulting access token in HTTP requests to the resource. Ele confiável indica ao recurso que seu aplicativo tem a permissão apropriada para executar uma tarefa específica.It reliably indicates to the resource that your app has the proper permission to perform a specific task.

Para obter mais informações sobre o protocolo OAuth 2,0 e como obter tokens de acesso, consulte a referência do protocolo de ponto de extremidade da plataforma de identidade da Microsoft.For more information about the OAuth 2.0 protocol and how to get access tokens, see the Microsoft identity platform endpoint protocol reference.

O escopo /.defaultThe /.default scope

Você pode usar o /.default escopo para ajudar a migrar seus aplicativos do ponto de extremidade v 1.0 para o ponto de extremidade da plataforma Microsoft Identity.You can use the /.default scope to help migrate your apps from the v1.0 endpoint to the Microsoft identity platform endpoint. Esse é o escopo interno para cada aplicativo que se refere à lista estática de permissões configuradas no registro de aplicativo.This is a built-in scope for every application that refers to the static list of permissions configured on the application registration. Um valor scope de https://graph.microsoft.com/.default tem funcionalidade igual à dos pontos de extremidade v1.0 resource=https://graph.microsoft.com, isto é, solicita um token com os escopos no Microsoft Graph para os quais o aplicativo foi registrado no portal do Azure.A scope value of https://graph.microsoft.com/.default is functionally the same as the v1.0 endpoints resource=https://graph.microsoft.com - namely, it requests a token with the scopes on Microsoft Graph that the application has registered for in the Azure portal.

O escopo/.default pode ser usado em qualquer fluxo OAuth 2,0, mas é necessário no fluxo em nome de e no fluxo de credenciais do cliente.The /.default scope can be used in any OAuth 2.0 flow, but is necessary in the On-Behalf-Of flow and client credentials flow.

Observação

Os clientes não podem combinar/.defaulto consentimento estático () e dinâmico em uma única solicitação.Clients can't combine static (/.default) and dynamic consent in a single request. Portanto, scope=https://graph.microsoft.com/.default+mail.read resultará em um erro devido à combinação de tipos de escopo.Thus, scope=https://graph.microsoft.com/.default+mail.read will result in an error due to the combination of scope types.

O escopo /.default também dispara o comportamento de ponto de extremidade v1.0 para prompt=consent.The /.default scope triggers the v1.0 endpoint behavior for prompt=consent as well. Ele solicita consentimento para todas as permissões registrada pelo aplicativo, independentemente do recurso.It requests consent for all permissions registered by the application, regardless of the resource. Se incluído como parte da solicitação, o /.default escopo retorna um token que contém os escopos para o recurso solicitado.If included as part of the request, the /.default scope returns a token that contains the scopes for the resource requested.

Como /.default tem funcionalidade idêntica à do comportamento do ponto de extremidade v1.0 do resource, ele também carrega consigo o comportamento do consentimento do ponto de extremidade v1.0.Because /.default is functionally identical to the resource-centric v1.0 endpoint's behavior, it brings with it the consent behavior of the v1.0 endpoint as well. Ou seja, /.default dispara uma solicitação de consentimento somente se nenhuma permissão for concedida pelo usuário entre o cliente e o recurso.Namely, /.default only triggers a consent prompt if no permission has been granted between the client and the resource by the user. Se houver algum consentimento, um token retorna contendo todos os escopos concedidos pelo usuário para tal recurso.If any such consent exists, then a token will be returned containing all scopes granted by the user for that resource. No entanto, se nenhuma permissão for concedida ou se o parâmetro prompt=consent for fornecido, é exibida uma solicitação de consentimento para todos os escopos registrados pelo aplicativo cliente.However, if no permission has been granted, or the prompt=consent parameter has been provided, a consent prompt will be shown for all scopes registered by the client application.

Exemplo 1: O usuário, ou administrador de locatários, concedeu permissõesExample 1: The user, or tenant admin, has granted permissions

O usuário (ou um administrador de locatários) concedeu ao cliente as permissões mail.read e user.read do Microsoft Graph.The user (or a tenant administrator) has granted the client the Microsoft Graph permissions mail.read and user.read. Se o cliente faz uma solicitação por scope=https://graph.microsoft.com/.default, nenhuma solicitação de consentimento é exibida, independentemente do conteúdo das permissões registradas pelos aplicativos cliente para o Microsoft Graph.If the client makes a request for scope=https://graph.microsoft.com/.default, then no consent prompt will be shown regardless of the contents of the client applications registered permissions for Microsoft Graph. Um token retorna contendo os escopos mail.read e user.read.A token would be returned containing the scopes mail.read and user.read.

Exemplo 2: O usuário não concedeu permissões entre o cliente e o recursoExample 2: The user hasn't granted permissions between the client and the resource

Não existe consentimento para o usuário entre o cliente e o Microsoft Graph.No consent for the user exists between the client and Microsoft Graph. O cliente foi registrado para as permissões user.read e contacts.read, e para o escopo https://vault.azure.net/user_impersonation do Azure Key Vault.The client has registered for the user.read and contacts.read permissions, as well as the Azure Key Vault scope https://vault.azure.net/user_impersonation. Quando o cliente solicita um token para scope=https://graph.microsoft.com/.default, o usuário vê uma tela de consentimento para user.read, contacts.read e os escopos user_impersonation de Key Vault.When the client requests a token for scope=https://graph.microsoft.com/.default, the user will see a consent screen for the user.read, contacts.read, and the Key Vault user_impersonation scopes. O token retornado tem apenas os escopos user.read e contacts.read.The token returned will have just the user.read and contacts.read scopes in it.

Exemplo 3: O usuário consentiu e o cliente solicita escopos adicionaisExample 3: The user has consented and the client requests additional scopes

O usuário já consentiu mail.read para o cliente.The user has already consented to mail.read for the client. O cliente foi registrado para o escopo contacts.read em seu registro.The client has registered for the contacts.read scope in its registration. Quando o cliente faz uma solicitação por um token usando scope=https://graph.microsoft.com/.default e solicita consentimento por meio de prompt=consent, o usuário vê uma tela de consentimento apenas e para todas as permissões registradas pelo aplicativo.When the client makes a request for a token using scope=https://graph.microsoft.com/.default and requests consent through prompt=consent, then the user will see a consent screen for only and all the permissions registered by the application. contacts.read está presente na tela de consentimento, mas mail.read, não.contacts.read will be present in the consent screen, but mail.read will not. O token retornado é para o Microsoft Graph e contém mail.read e contacts.read.The token returned will be for Microsoft Graph and will contain mail.read and contacts.read.

Usando o escopo /.default com o clienteUsing the /.default scope with the client

Há um caso especial do escopo /.default em que um cliente solicita o seu próprio escopo /.default.A special case of the /.default scope exists where a client requests its own /.default scope. O exemplo a seguir demonstra esse cenário.The following example demonstrates this scenario.

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
response_type=token            //code or a hybrid flow is also possible here
&client_id=9ada6f8a-6d83-41bc-b169-a306c21527a5
&scope=9ada6f8a-6d83-41bc-b169-a306c21527a5/.default
&redirect_uri=https%3A%2F%2Flocalhost
&state=1234

Isso gera uma tela de consentimento para todas as permissões registradas (se aplicável com base nas descrições de consentimento e /.default acima) e, em seguida, retorna um id_token, e não um token de acesso.This produces a consent screen for all registered permissions (if applicable based on the above descriptions of consent and /.default), then returns an id_token, rather than an access token. Esse comportamento existe para determinados clientes herdados que se movem de ADAL para MSAL e não devem ser usados por novos clientes direcionados ao ponto de extremidade da plataforma Microsoft Identity.This behavior exists for certain legacy clients moving from ADAL to MSAL, and should not be used by new clients targeting the Microsoft identity platform endpoint.

Se você ou os usuários do aplicativo veem erros inesperados durante o processo de consentimento, consulte este artigo para ver etapas de solução de problemas: Erro inesperado ao executar o consentimento para um aplicativo.If you or your application's users are seeing unexpected errors during the consent process, see this article for troubleshooting steps: Unexpected error when performing consent to an application.