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 final de plataforma de identidade do MicrosoftMicrosoft identity platform endpoint

Os aplicativos que se integram à plataforma Microsoft Identity seguem um modelo de autorização que oferece aos usuários e administradores o 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 desse 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.

Nota

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.

Escopos e permissõesScopes 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 de um 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 com a plataforma de identidade da Microsoft tem um identificador de recurso ou um URI de ID do 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

Nota

É altamente recomendável que você use Microsoft Graph em vez do Azure AD Graph, a API de email do Office 365, etc.We strongly recommend that you use Microsoft Graph instead of Azure AD Graph, Office 365 Mail API, etc.

O mesmo acontece com todos os recursos de terceiros que se integraram à plataforma Microsoft Identity.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 podem ser usadas 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, 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
  • Gravar no calendário de um usuárioWrite to a user's calendar
  • Enviar correio como um utilizadorSend mail as a user

Ao definir esses tipos de permissões, o recurso tem um controle refinado sobre seus dados e como a funcionalidade da 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 de um 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 de permissões menores, aplicativos de terceiros podem ser criados para solicitar apenas as permissões específicas necessárias para executar sua função.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 ao 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ões são chamadosde 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 de 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 usandoCalendars.ReadRead a user's calendar by using Calendars.Read
  • Gravar no calendário de um usuário usandoCalendars.ReadWriteWrite to a user's calendar by using Calendars.ReadWrite
  • Enviar email como um usuário usando o porMail.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 a ler para obter mais informações.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.

  • As 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 consentidas por usuários não administrativos, mas algumas permissões com privilégios superiores 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 de função de administrador no Azure ad.To learn which administrator roles can consent to delegated permissions, see Administrator role permissions in Azure AD.

  • As permissões de aplicativo são usadas por aplicativos que são 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.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 permissões delegadas, as permissões efetivas de seu aplicativo serão a interseção menos privilegiada das permissões delegadas que o aplicativo recebeu (via 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. A aplicação nunca pode ter mais privilégios do que o utilizador com sessão iniciada.Your app can never have more privileges than the signed-in user. Nas organizações, os privilégios do utilizador com sessão iniciada podem ser determinados por uma política ou por associação a 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 de função de administrador no Azure ad.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 User. ReadWrite. All delegated.For example, assume your app has been granted the User.ReadWrite.All delegated permission. Esta permissão concede nominalmente permissão à aplicação para ler e atualizar o perfil de todos os utilizadores de uma organização.This permission nominally grants your app permission to read and update the profile of every user in an organization. Se o utilizador com sessão iniciada for administrador global, a aplicação poderá atualizar o perfil de todos os utilizadores da 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 dos outros utilizadores da organização porque o utilizador em cujo nome tem permissão para agir não tem esses 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 serão o nível completo de privilégios implícitos 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 tem a permissão User. ReadWrite. All Application pode atualizar o perfil de cada usuário 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. Não addressphone suporte para os escopos do e do OpenID Connect.The address and phone OpenID Connect scopes are not supported.

OpenIDopenid

Se um aplicativo executar a entrada usando o OpenID Connect, ele deverá solicitar o openid escopo.If an app performs sign-in by using OpenID Connect, it must request the openid scope. O openid escopo é exibido na página de consentimento da conta corporativa como a permissão "conectar você" e na página de consentimento do conta Microsoft pessoal como a permissão "exibir seu perfil e conectar-se a aplicativos e serviços usando sua conta 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 sub declaração.With this permission, an app can receive a unique identifier for the user in the form of the sub claim. Ele também dá ao aplicativo acesso ao ponto de extremidade de 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 email escopo pode ser usado com o openid escopo e qualquer outro.The email scope can be used with the openid scope and any others. Ele dá ao aplicativo acesso ao endereço de email principal do usuário na forma da email declaração.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 ele usar o email escopo, seu aplicativo deverá estar preparado para lidar com um caso no qual email a declaração 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 profile escopo pode ser usado com o openid escopo e qualquer outro.The profile scope can be used with the openid scope and any others. Ele dá ao aplicativo acesso a uma quantidade significativa 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 das declarações de perfil disponíveis no parâmetro id_tokens para um usuário específico, consulte a id_tokens referê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 dá ao aplicativo acesso a recursos em nome do usuário por um longo tempo. offline_access 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 aos quais você concedeu 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 vida longa.Refresh tokens are long-lived. Seu aplicativo pode obter novos tokens de acesso à medida que os antigos expiram.Your app can get new access tokens as older ones expire.

Se seu aplicativo não solicitar explicitamente o offline_access escopo, 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 quando você resgatar um código de autorização no fluxo de código de autorização do OAuth 2,0, receberá apenas um token de /token acesso do ponto de extremidade.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 de tempo.The access token is valid for a short time. O token de acesso geralmente expira em uma hora.The access token usually expires in one hour. Nesse ponto, seu aplicativo precisa redirecionar o usuário de volta para /authorize o ponto de extremidade 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 pode precisar inserir suas credenciais novamente ou consentir novamente 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 do OAuth 2,0 , um aplicativo pode solicitar as permissões necessárias usando scope o parâmetro de consulta.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 scope parâmetro é uma lista separada por espaços de permissões delegadas 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 de permissão ao identificador do recurso (o URI da ID do 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 do usuário e enviar email 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.

Nota

Neste momento, as offline_access permissões ("manter o acesso aos dados aos quais você concede acesso") e user.read ("entrar e ler 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 apropriada do offline_access aplicativo – dá ao aplicativo acesso a tokens de atualização, críticos para aplicativos Web user.read e nativos, enquanto sub fornece acesso à declaração, permitindo que o cliente ou o aplicativo seja corretamente Identifique o usuário ao longo do tempo e acesse informações de usuário rudimentares.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 aprova a solicitação de permissão, o consentimento é registrado e o usuário não precisa consentir novamente em entradas subsequentes para o 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.

Geralmente, quando uma organização adquire uma licença ou assinatura para um aplicativo, a organização deseja configurar proativamente o aplicativo para uso por todos os membros da organização.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 conceder consentimento para o aplicativo agir em nome de qualquer usuário 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 consentimento para o locatário inteiro, os usuários da organização não verã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 para permissões delegadas para todos os usuários em um locatário, seu aplicativo pode usar o ponto de extremidade de consentimento do 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 restritas ao 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ões incluem o seguinte:Examples of these kinds of permissions include the following:

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

Embora um usuário consumidor possa conceder a um aplicativo acesso a esse tipo de dados, os usuários organizacionais estão restritos a 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 exigir acesso a escopos restritos ao administrador para organizações, você deverá 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 estiver solicitando permissões delegadas de alto privilégio e um administrador conceder essas permissões por meio do ponto de extremidade de consentimento do administrador, o consentimento será concedido 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. Em vez disso, o aplicativo cliente recebe 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.

Nota

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 de autorização, a plataforma de identidade da Microsoft detectará a função do usuário e perguntará se deseja consentir em nome do locatário inteiro para as permissões que você solicitou.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, também há 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 de todo o locatário.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 essas etapas, seu aplicativo poderá solicitar permissões para todos os usuários em um locatário, incluindo escopos restritos ao administrador.If you follow these steps, your app can request permissions for all users in a tenant, including admin-restricted scopes. Essa é uma operação de alto privilégio e só deve ser feita se necessário para seu cenário.This is a high privilege operation and should only be done if necessary for your scenario.

Para ver um exemplo de código que implementa as etapas, consulte 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 de aplicativoRequest the permissions in the app registration portal

O consentimento do administrador não aceita um parâmetro de escopo, 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 exibição na qual 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 fazer parte do fluxo de inscrição do aplicativo, parte das configurações do aplicativo ou pode ser um fluxo de "conexão" dedicado.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 mostre esse modo de exibição "conectar" somente depois que um usuário tiver entrado com uma conta Microsoft corporativa ou de estudante.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 que eles aprovem 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, ele pode ajudá-lo a criar uma experiência mais intuitiva para seus usuários organizacionais.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 as 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 RequeridoRequired O locatário do diretório do qual você deseja solicitar permissão.The directory tenant that you want to request permission from. Pode ser fornecido em formato de nome amigável ou GUID ou referenciado genericamente 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 RequeridoRequired 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 RequeridoRequired O URI de redirecionamento no qual você deseja que a resposta seja enviada para que seu aplicativo manipule.The redirect URI where you want the response to be sent for your app to handle. Ele deve corresponder exatamente a um dos URIs de redirecionamento 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 que 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 informações sobre o estado do usuário no aplicativo antes que a solicitação de autenticação ocorra, como a página ou a exibição em que eles estavam.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 que um administrador de locatários entre para concluir a solicitação.At this point, Azure AD requires a tenant administrator to sign in to complete the request. O administrador é solicitado a aprovar todas as permissões que você solicitou para seu aplicativo no portal de registro de aplicativo.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 seu aplicativo, a resposta bem-sucedida terá esta aparência: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 de diretório que concedeu ao aplicativo as permissões solicitadas, no formato GUID.The directory tenant that granted your application the permissions it requested, in GUID format.
state Um valor incluído na solicitação que 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 informações sobre o estado do usuário no aplicativo antes que a solicitação de autenticação ocorra, como a página ou a exibição em que eles estavam.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 seu aplicativo, a resposta com falha terá esta aparência: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ódigo de erro que pode ser usada para classificar tipos de erros que ocorrem e pode ser usada para reagir a 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, seu aplicativo ganhou as permissões solicitadas.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 consentir permissões para seu aplicativo, seu aplicativo poderá adquirir tokens de acesso que representem 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 pode ser usado apenas para um único recurso, mas codificado dentro do token de acesso é cada permissão que seu 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 indica de maneira confiável o recurso de 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 é um escopo interno para cada aplicativo que se refere à lista estática de permissões configuradas no registro do aplicativo.This is a built-in scope for every application that refers to the static list of permissions configured on the application registration. Um scope valor de https://graph.microsoft.com/.default é funcionalmente o mesmo que os pontos de extremidade resource=https://graph.microsoft.com v 1.0, ou seja, ele solicita um token com os escopos no Microsoft Graph do qual o aplicativo se registrou 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.

Nota

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. Assim, 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 /.default escopo dispara o prompt=consent comportamento do ponto de extremidade v 1.0 também.The /.default scope triggers the v1.0 endpoint behavior for prompt=consent as well. Ele solicita consentimento para todas as permissões registradas 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 o resourceé funcionalmente idêntico ao comportamento do ponto de extremidade v 1.0 centrado no, ele também traz o comportamento de consentimento do ponto de extremidade v 1.0. /.defaultBecause /.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 apenas um prompt de consentimento se nenhuma permissão tiver sido concedida entre o cliente e o recurso pelo usuário.Namely, /.default only triggers a consent prompt if no permission has been granted between the client and the resource by the user. Se esse tipo de consentimento existir, um token será retornado contendo todos os escopos concedidos pelo usuário para esse 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 tiver sido concedida ou prompt=consent o parâmetro tiver sido fornecido, um prompt de consentimento será mostrado 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ário, 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 mail.read permissões user.readde Microsoft Graph e.The user (or a tenant administrator) has granted the client the Microsoft Graph permissions mail.read and user.read. Se o cliente fizer uma solicitação para scope=https://graph.microsoft.com/.defaulto, nenhum prompt de consentimento será mostrado, independentemente do conteúdo das permissões registradas de aplicativos cliente para 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 seria retornado 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 se registrou para user.read as contacts.read permissões e, bem como o escopo https://vault.azure.net/user_impersonationde 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 verá uma tela de consentimento para o user.read, contacts.reade os escopos de Key Vault user_impersonation .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 terá apenas os user.read escopos e. contacts.readThe 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 no para o cliente.The user has already consented to mail.read for the client. O cliente foi registrado para o contacts.read escopo em seu registro.The client has registered for the contacts.read scope in its registration. Quando o cliente faz uma solicitação para um token usando scope=https://graph.microsoft.com/.default e solicita consentimento por prompt=consentmeio do, o usuário verá uma tela de consentimento somente para e 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.readestará presente na tela de consentimento, mas mail.read não vai.contacts.read will be present in the consent screen, but mail.read will not. O token retornado será para Microsoft Graph e conterá mail.read e. contacts.readThe 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

Um caso especial do /.default escopo existe onde um cliente solicita seu próprio /.default escopo.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 produz uma tela de consentimento para todas as permissões registradas (se aplicável com base nas descrições acima /.defaultde consentimento e), em seguida, retorna um id_token, em vez de 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 estiverem vendo erros inesperados durante o processo de consentimento, consulte este artigo para obter as 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.