Obter acesso sem um usuárioGet access without a user

Alguns aplicativos chamam o Microsoft Graph com sua própria identidade e não em nome de um usuário. Em muitos casos, esses são os serviços em plano de fundo ou daemons que podem ser executados em um servidor sem a presença de um usuário conectado. Um exemplo de como um aplicativo pode ser um serviço de arquivamento de email que é ativado e executado durante a noite. Em alguns casos, aplicativos que tenham um usuário conectado no momento talvez precisem chamar o Microsoft Graph com sua própria identidade também. Por exemplo, um aplicativo talvez precise usar a funcionalidade que exige privilégios mais elevados em uma organização do que aqueles realizados pelo usuário conectado.Some apps call Microsoft Graph with their own identity and not on behalf of a user. In many cases, these are background services or daemons that run on a server without the presence of a signed-in user. An example of such an app might be an email archival service that wakes up and runs overnight. In some cases, apps that have a signed-in user present may also need to call Microsoft Graph under their own identity. For example, an app may need to use functionality that requires more elevated privileges in an organization than those carried by the signed-in user.

Os aplicativos que chamam o Microsoft Graph com sua própria identidade usam o fluxo de concessão de credenciais do cliente OAuth 2.0 para obter tokens de acesso do Azure AD. Este tópico descreve as etapas básicas para configurar um serviço e usa o fluxo de concessão de credenciais do cliente OAuth para obter um token de acesso.Apps that call Microsoft Graph with their own identity use the OAuth 2.0 client credentials grant flow to get access tokens from Azure AD. In this topic, we will walk through the basic steps to configure a service and use the OAuth client credentials grant flow to get an access token.

Etapas de autenticação e autorizaçãoAuthentication and authorization steps

As etapas básicas necessárias para configurar um serviço e obter um token para o ponto de extremidade da plataforma de identidade da Microsoft que seu serviço pode usar para fazer chamadas para o Microsoft Graph com sua própria identidade são:The basic steps required to configure a service and get a token from the Microsoft identity platform endpoint that your service can use to call Microsoft Graph under its own identity are:

  1. Registre seu aplicativo.Register your app.
  2. Configure permissões para o Microsoft Graph em seu aplicativo.Configure permissions for Microsoft Graph on your app.
  3. Obtenha o consentimento do administrador.Get administrator consent.
  4. Obtenha um token de acesso.Get an access token.
  5. Use o token de acesso para chamar o Microsoft Graph.Use the access token to call Microsoft Graph.

1. Registre seu aplicativo1. Register your app

Para autenticar com o ponto de extremidade da plataforma de identidade da Microsoft, primeiro você deve registrar seu aplicativo no Portal de Registro de Aplicativos do Azure. Você pode usar uma conta da Microsoft ou uma conta corporativa ou de estudante para registrar seu aplicativo.To authenticate with the Microsoft identity platform endpoint, you must first register your app at the Azure app registration portal. You can use either a Microsoft account or a work or school account to register your app.

Para um serviço que chamará o Microsoft Graph com sua própria identidade, você precisa registrar seu aplicativo na plataforma Web e copiar os seguintes valores:For a service that will call Microsoft Graph under its own identity, you need to register your app for the Web platform and copy the following values:

  • A ID do Aplicativo atribuída pelo portal de registro de aplicativo do Azure.The Application ID assigned by the Azure app registration portal.
  • Um Segredo do Cliente (aplicativo), que pode ser uma senha ou um par de chaves públicas/particulares (certificado).A Client (application) Secret, either a password or a public/private key pair (certificate).
  • Uma URL de redirecionamento para seu serviço receber respostas do token.A Redirect URL for your service to receive token responses.
  • Uma URL de redirecionamento para seu serviço receber respostas de consentimento do administrador se seu aplicativo implementar a funcionalidade para solicitar o consentimento do administrador.A Redirect URL for your service to receive admin consent responses if your app implements functionality to request administrator consent.

Para saber como configurar um aplicativo usando o Portal de Registro de Aplicativos do Azure, confira Registre seu aplicativo.For steps on how to configure an app using the Azure app registration portal, see Register your app.

Com o fluxo de concessão de credenciais do cliente OAuth 2.0, seu aplicativo é autenticado diretamente no ponto de extremidade /token da plataforma de identidade da Microsoft usando a ID do Aplicativo atribuída pelo Azure AD e o Segredo do Aplicativo que você cria usando o portal.With the OAuth 2.0 client credentials grant flow, your app authenticates directly at the Microsoft identity platform /token endpoint using the Application ID assigned by Azure AD and the Application Secret that you create using the portal.

2. Configure permissões para o Microsoft Graph2. Configure permissions for Microsoft Graph

Para aplicativos que chamam o Microsoft com sua própria identidade, o Microsoft Graph expõe permissões do aplicativo. (O Microsoft Graph também pode expor as permissões delegadas para aplicativos que chamam o Microsoft Graph em nome de um usuário.) Configure previamente as permissões do aplicativo necessárias quando registrar o aplicativo. As permissões do aplicativo sempre exigem o consentimento do administrador. Um administrador pode autorizar essas permissões usando o Portal do Azure quando o aplicativo for instalado em sua organização ou pode fornecer uma experiência de inscrição em seu aplicativo por meio da qual os administradores podem concordar com as permissões configuradas. Depois que o consentimento do administrador for registrado pelo Azure AD, seu aplicativo poderá solicitar tokens sem ter que solicitar consentimento novamente. Para obter mais informações sobre as permissões disponibilizadas pelo Microsoft Graph, confira a Referência de permissõesFor apps that call Microsoft Graph under their own identity, Microsoft Graph exposes application permissions. (Microsoft Graph also exposes delegated permissions for apps that call Microsoft Graph on behalf of a user.) You pre-configure the application permissions your app needs when you register your app. Application permissions always require administrator consent. An administrator can either consent to these permissions using the Azure portal when your app is installed in their organization, or you can provide a sign-up experience in your app through which administrators can consent to the permissions you configured. Once administrator consent is recorded by Azure AD, your app can request tokens without having to request consent again. For more detailed information about the permissions available with Microsoft Graph, see the Permissions reference

Para configurar as permissões de aplicativo para seu aplicativo no Portal de Registros de Aplicativos do Azure: na página permissões de API do aplicativo, escolha Adicionar uma permissão, selecione Microsoft Graph, e, em seguida, escolha as permissões exigidas pelo aplicativo em Permissões do aplicativo.To configure application permissions for your app in the Azure app registration portal: under an application's API permissions page, choose Add a permission, select Microsoft Graph, and then choose the permissions your app requires under Application permissions.

A captura de tela a seguir mostra a caixa de diálogo Selecionar Permissões para permissões de aplicativo do Microsoft Graph.The following screenshot shows the Select Permissions dialog for Microsoft Graph application permissions.

Marque a caixa de diálogo Permissões para as Permissões de aplicativo do Microsoft Graph.

Observação: Recomendamos que você configure o conjunto com menos privilégios de permissões necessárias para seu aplicativo. Isso proporciona uma experiência muito mais confortável para os administradores do que ter que consentir com uma longa lista de permissões.Note: We recommend configuring the least privileged set of permissions required by your app. This provides a much more comfortable experience for administrators than having to consent to a long list of permissions.

Você pode confiar em um administrador para conceder as permissões que seu aplicativo precisa no Portal do Azure. No entanto, muitas vezes, a melhor opção seria fornecer uma experiência de inscrição para administradores usando o ponto de extremidade /adminconsent da plataforma de identidade da Microsoft.You can rely on an administrator to grant the permissions your app needs at the Azure portal; however, often, a better option is to provide a sign-up experience for administrators by using the Microsoft identity platform /adminconsent endpoint.

Importante: Sempre que fizer uma alteração nas permissões configuradas, convém repetir o processo de Consentimento do Administrador.Important: Any time you make a change to the configured permissions, you must also repeat the Admin Consent process. As alterações feitas no portal de registro de aplicativos não serão refletidas até que o consentimento tiver sido reaplicado pelo administrador do locatário.Changes made in the app registration portal will not be reflected until consent has been reapplied by the tenant's administrator.

SolicitaçãoRequest

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/adminconsent
?client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&state=12345
&redirect_uri=https://localhost/myapp/permissions
ParâmetroParameter CondiçãoCondition DescriçãoDescription
locatáriotenant ObrigatórioRequired O locatário do diretório do qual você deseja solicitar permissão. Pode ser no formato de nome amigável ou GUID. Se você não souber a qual locatário o usuário pertence e quiser permitir que ele entre em qualquer locatário, use common.The directory tenant that you want to request permission from. This can be in GUID or friendly name format. If you don't know which tenant the user belongs to and you want to let them sign in with any tenant, use common.
client_idclient_id ObrigatórioRequired A ID de Aplicativo que o Portal de Registro de Aplicativos do Azure atribuiu a seu aplicativo.The Application ID that the Azure app registration portal assigned to your app.
redirect_uriredirect_uri ObrigatórioRequired O URI de redirecionamento para onde você deseja que a resposta seja enviada para que o aplicativo trate da situação. Ele deve corresponder exatamente a um dos URIs de redirecionamento registrados no portal, exceto que ele deve ser codificado por URL e pode ter segmentos de caminho adicionais.The redirect URI where you want the response to be sent for your app to handle. It must exactly match one of the redirect URIs that you registered in the portal, except that it must be URL encoded, and it can have additional path segments.
estadostate RecomendadoRecommended Um valor incluído na solicitação e que também será retornado na resposta do token. Pode ser uma cadeia de caracteres de qualquer conteúdo que você desejar. O estado é usado para codificar as informações sobre o estado do usuário no aplicativo antes da solicitação de autenticação ter ocorrido, como a página ou o modo de exibição em que ele estava.A value that is included in the request that also is returned in the token response. It can be a string of any content that you want. 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.

Através de solicitações ao ponto de extremidade /adminconsent, o Azure AD exige que apenas um administrador de locatário possa fazer logon para concluir a solicitação. O administrador será solicitado a aprovar todas as Permissões de aplicativo que você solicitar para seu aplicativo no Portal de Registro de Aplicativos.With requests to the /adminconsent endpoint, Azure AD enforces that only a tenant administrator can sign in to complete the request. The administrator will be asked to approve all the application permissions that you have requested for your app in the app registration portal.

Veja a seguir um exemplo da caixa de diálogo de consentimento que o Azure AD apresenta ao administrador:The following is an example of the consent dialog that Azure AD presents to the administrator:

Caixa de diálogo do consentimento do administrador.

RespostaResponse

Se o administrador aprovar as permissões de seu aplicativo, a resposta bem-sucedida ficará assim:If the administrator approves the permissions for your application, the successful response looks like this:

// Line breaks are for legibility only.

GET https://localhost/myapp/permissions
?tenant=a8990e1f-ff32-408a-9f8e-78d3b9139b95&state=12345
&admin_consent=True
ParâmetroParameter DescriçãoDescription
locatáriotenant O locatário do diretório que concedeu as permissões de aplicativo solicitadas, no formato GUID.The directory tenant that granted your application the permissions that it requested, in GUID format.
estadostate Um valor incluído na solicitação e que também será retornado na resposta do token. Pode ser uma cadeia de caracteres de qualquer conteúdo que você desejar. O estado é usado para codificar as informações sobre o estado do usuário no aplicativo antes da solicitação de autenticação ter ocorrido, como a página ou o modo de exibição em que ele estava.A value that is included in the request that also is returned in the token response. It can be a string of any content that you want. 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_consentadmin_consent Definir como true.Set to true.

Experimente: Você pode experimentar ao colar a solicitação abaixo em um navegador. Se fizer logon como um Administrador global em um locatário do Azure AD, você verá a caixa de diálogo de consentimento do administrador para o aplicativo. (Este aplicativo será diferente do aplicativo exibido na tela da caixa de diálogo do consentimento previamente mostrada.)Try: You can try this for yourself by pasting the following request in a browser. If you sign in as a Global administrator for an Azure AD tenant, you will be presented with the administrator consent dialog box for the app. (This will be a different app than that in the consent dialog box screenshot shown earlier.)

https://login.microsoftonline.com/common/adminconsent?client_id=6731de76-14a6-49ae-97bc-6eba6914391e&state=12345&redirect_uri=https://localhost/myapp/permissions

4. Obter um token de acesso4. Get an access token

No fluxo de concessão de credenciais do cliente OAuth 2.0, use os valores do Segredo do Aplicativo e ID do Aplicativo salvos quando você registrou o aplicativo para solicitar um token de acesso diretamente no ponto de extremidade /token da plataforma de identidade da Microsoft.In the OAuth 2.0 client credentials grant flow, you use the Application ID and Application Secret values that you saved when you registered your app to request an access token directly from the Microsoft identity platform /token endpoint.

Você especifica as permissões pré-configuradas passando https://graph.microsoft.com/.default como o valor para o parâmetro scope na solicitação de token. Confira a descrição do parâmetro scope na solicitação de token abaixo para obter detalhes.You specify the pre-configured permissions by passing https://graph.microsoft.com/.default as the value for the scope parameter in the token request. See the scope parameter description in the token request below for details.

Solicitação de tokenToken request

Envie uma solicitação POST ao ponto de extremidade /token da plataforma de identidade para adquirir um token de acesso:You send a POST request to the /token identity platform endpoint to acquire an access token:

// Line breaks are for legibility only.

POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials
ParâmetroParameter CondiçãoCondition DescriçãoDescription
locatáriotenant ObrigatórioRequired O locatário do diretório do qual você deseja solicitar permissão. Pode ser no formato de nome amigável ou GUID.The directory tenant that you want to request permission from. This can be in GUID or friendly name format.
client_idclient_id ObrigatórioRequired A ID de Aplicativo que o Portal de Registro de Aplicativos do Azure atribuiu quando você registrou seu aplicativo.The Application ID that the Azure app registration portal assigned when you registered your app.
scopescope ObrigatórioRequired O valor passado para o parâmetro scope nesta solicitação deve ser o identificador do recurso (URI da ID do Aplicativo) do recurso desejado, afixado com o sufixo .default.The value passed for the scope parameter in this request should be the resource identifier (Application ID URI) of the resource you want, affixed with the .default suffix. Para o Microsoft Graph, o valor é https://graph.microsoft.com/.default.For Microsoft Graph, the value is https://graph.microsoft.com/.default. Esse valor informa ao ponto de extremidade da plataforma de identidade da Microsoft que, de todas as permissões de aplicativo que você configurou para seu aplicativo, ele deve emitir um token para os aplicativos associados ao recurso que você deseja usar.This value informs the Microsoft identity platform endpoint that of all the application permissions you have configured for your app, it should issue a token for the ones associated with the resource you want to use.
client_secretclient_secret ObrigatórioRequired O Segredo do Aplicativo gerado para seu aplicativo no portal de registro de aplicativos.The Application Secret that you generated for your app in the app registration portal.
grant_typegrant_type ObrigatórioRequired Deve ser client_credentials.Must be client_credentials.

Resposta do tokenToken response

Uma resposta bem-sucedida tem esta aparência:A successful response looks like this:

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}
ParâmetroParameter DescriçãoDescription
access_tokenaccess_token O token de acesso solicitado. Seu aplicativo pode usar esse token em chamadas para o Microsoft Graph.The requested access token. Your app can use this token in calls to Microsoft Graph.
token_typetoken_type Indica o valor de tipo de token. O único tipo ao qual o Azure AD dá suporte é bearer.Indicates the token type value. The only type that Azure AD supports is bearer.
expires_inexpires_in Por quanto tempo o token de acesso é válido (em segundos).How long the access token is valid (in seconds).

5. Use o token de acesso para chamar o Microsoft Graph5. Use the access token to call Microsoft Graph

Após obter o token de acesso, você pode usá-lo para chamar o Microsoft Graph, incluindo-o no cabeçalho Authorization de uma solicitação. A solicitação a seguir obtém o perfil de um usuário específico. Seu aplicativo deve ter a permissão User.Read.All para chamar essa API.After you have an access token, you can use it to call Microsoft Graph by including it in the Authorization header of a request. The following request gets the profile of a specific user. Your app must have the User.Read.All permission to call this API.

GET https://graph.microsoft.com/v1.0/users/12345678-73a6-4952-a53a-e9916737ff7f
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
Host: graph.microsoft.com

Uma resposta bem-sucedida terá a seguinte aparência (alguns cabeçalhos de resposta foram removidos):A successful response will look similar to this (some response headers have been removed):

HTTP/1.1 200 OK
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8
request-id: f45d08c0-6901-473a-90f5-7867287de97f
client-request-id: f45d08c0-6901-473a-90f5-7867287de97f
OData-Version: 4.0
Duration: 309.0273
Date: Wed, 26 Apr 2017 19:53:49 GMT
Content-Length: 407
{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users/$entity",
    "id":"12345678-73a6-4952-a53a-e9916737ff7f",
    "businessPhones":[
        "+1 555555555"
    ],
    "displayName":"Chris Green",
    "givenName":"Chris",
    "jobTitle":"Software Engineer",
    "mail":null,
    "mobilePhone":"+1 5555555555",
    "officeLocation":"Seattle Office",
    "preferredLanguage":null,
    "surname":"Green",
    "userPrincipalName":"ChrisG@contoso.onmicrosoft.com"
}

Recursos e cenários de aplicativo com suporteSupported app scenarios and resources

Os aplicativos que chamam o Microsoft Graph com sua própria identidade se enquadram em uma dessas categorias:Apps that call Microsoft Graph under their own identity fall into one of two categories:

  • Serviços em segundo plano (daemons) que podem ser executados em um servidor sem um usuário conectado.Background services (daemons) that run on a server without a signed-in user.
  • Aplicativos que têm um usuário conectado, mas que também chamam o Microsoft Graph com sua própria identidade. Por exemplo, para usar a funcionalidade que exige privilégios mais elevados do usuário.Apps that have a signed-in user but also call Microsoft Graph with their own identity; for example, to use functionality that requires more elevated privileges than those of the user.

Os aplicativos que chamam o Microsoft Graph com sua própria identidade usam a concessão de credenciais do cliente OAuth 2.0 para autenticar com o Azure AD e obter um token.Apps that call Microsoft Graph with their own identity use the OAuth 2.0 client credentials grant to authenticate with Azure AD and get a token. Para o ponto de extremidade da plataforma de identidade da Microsoft, você pode explorar esse cenário ainda mais com os seguintes recursos:For the Microsoft identity platform endpoint, you can explore this scenario further with the following resources:

Considerações sobre o ponto de extremidadeEndpoint considerations

A Microsoft continua oferecendo suporte ao ponto de extremidade do Azure AD.Microsoft continues to support the Azure AD endpoint. Existem várias diferenças entre a utilização do ponto de extremidade da plataforma de identidade da Microsoft e o ponto de extremidade do Azure AD.There are several differences between using the Microsoft identity platform endpoint and the Azure AD endpoint. Durante o uso do ponto de extremidade do Azure AD:When using the Azure AD endpoint:

  • Se o aplicativo for multilocatário, você deve configurá-lo explicitamente para funcionar como multilocatário no portal do Azure.If your app is a multi-tenant app, you must explicitly configure it to be multi-tenant in the Azure portal.
  • Não há administrador no ponto de extremidade (/adminconsent).There is no admin consent endpoint (/adminconsent). Em vez disso, seu aplicativo pode solicitar consentimento do administrador durante o tempo de execução adicionando o parâmetro prompt=admin_consent a uma solicitação de autorização.Instead, your app can request administrator consent during runtime by adding the prompt=admin_consent parameter to an authorization request. Para obter mais informações, confira Como acionar a estrutura do consentimento do Azure AD no tempo de execução no artigo Integração de aplicativos com o Azure Active Directory.For more information, see Triggering the Azure AD consent framework at runtime in Integrating applications with Azure Active Directory.
  • Os parâmetros nas solicitações de token e de autorização são diferentes. Por exemplo, não existe um parâmetro scope nas solicitações do ponto de extremidade do Azure AD. Em vez disso, o parâmetro resource é usado para especificar o URI do recurso (resource=https://graph.microsoft.com) que a autorização (para consentimento do administrador) ou um token está solicitando.The parameters in authorization and token requests are different. For example, there is no scope parameter in Azure AD endpoint requests; instead, the resource parameter is used to specify the URI of the resource (resource=https://graph.microsoft.com) that authorization (for administrator consent) or a token is being requested for.

Você pode explorar esse cenário ainda mais com os seguintes recursos:For the Azure AD endpoint, you can explore this scenario further with the following resources:

  • Para saber mais sobre a plataforma de identidade da Microsoft com diferentes tipos de aplicativos, confira os links de Introdução na documentação da plataforma de identidade da Microsoft.For information about using the Microsoft identity platform with different kinds of apps, see the Get Started links in the Microsoft identity platform documentation. Este guia contém links para tópicos de visão geral, guias de início rápido, tutoriais, exemplos de código e documentação de protocolo para diferentes tipos de aplicativos compatíveis com a plataforma de identidade da Microsoft.The guide contains links to overview topics, quickstarts, tutorials, code samples, and protocol documentation for different kinds of apps supported by the Microsoft identity platform.
  • Para saber mais sobre a MSAL (Biblioteca de Autenticação da Microsoft) e o middleware de servidor disponíveis para uso com o ponto de extremidade da plataforma de identidade da Microsoft, confira Bibliotecas de Autenticação da Microsoft.For information about the Microsoft Authentication Library (MSAL) and server middleware available for use with the Microsoft identity platform endpoint, see Microsoft Authentication Libraries.