Obter acesso sem um usuário

Para chamar o Microsoft Graph, um aplicativo deve obter um token de acesso da plataforma de identidade da Microsoft. Esse token de acesso mostra se o aplicativo está autorizado a acessar o Microsoft Graph em nome de um usuário conectado ou com sua própria identidade. Este artigo explica como um aplicativo pode acessar o Microsoft Graph com sua própria identidade, também chamada de acesso somente aplicativo.

Este artigo explica as solicitações HTTP brutas que um aplicativo faz para chamar o Microsoft Graph com sua própria identidade usando o popular fluxo de concessão de credenciais do cliente OAuth 2.0. Normalmente, você não precisa escrever solicitações HTTP brutas e, em vez disso, usar uma biblioteca de autenticação criada ou com suporte da Microsoft que ajuda você a obter tokens de acesso e chamar o Microsoft Graph. Para obter mais informações, consulte Usar a MSAL (Biblioteca de Autenticação da Microsoft).

Neste artigo, você concluirá as seguintes etapas para usar o fluxo de credenciais do cliente:

  1. Configure as permissões do aplicativo Microsoft Graph no aplicativo.
  2. Solicite o consentimento do administrador.
  3. Solicite um token de acesso.
  4. Chame o Microsoft Graph usando o token de acesso.

Pré-requisitos

Antes de prosseguir com as etapas deste artigo:

  1. Entenda os conceitos de autenticação e autorização na plataforma de identidade da Microsoft. Para obter mais informações, consulte Noções básicas de autenticação e autorização.
  2. Registre o aplicativo com o Microsoft Entra ID. Para obter mais informações, consulte Registrar um aplicativo na plataforma de identidade da Microsoft. Salve os seguintes valores do registro do aplicativo:
    • A ID do aplicativo (chamada de ID do Objeto no centro de administração do Microsoft Entra).
    • Um segredo do cliente (senha do aplicativo), um certificado ou uma credencial de identidade federada.
    • Um URI de redirecionamento para o aplicativo receber respostas de token do Microsoft Entra ID.
    • Um URI de redirecionamento para o serviço receber respostas de consentimento do administrador se o aplicativo implementar a funcionalidade para solicitar o consentimento do administrador.

Etapa 1: Configurar permissões para o Microsoft Graph

O Microsoft Graph expõe permissões de aplicativo para aplicativos que chamam o Microsoft Graph com sua própria identidade. Essas permissões sempre exigem o consentimento do administrador.

Pré-configure as permissões de aplicativo de que o aplicativo precisa ao registrá-lo. Um administrador pode consentir com essas permissões usando o centro de administração do Microsoft Entra ao instalar o aplicativo em sua organização ou você pode fornecer uma experiência de inscrição no aplicativo por meio da qual os administradores podem consentir com as permissões configuradas. Depois que o Microsoft Entra ID registra o consentimento do administrador, o aplicativo pode solicitar tokens sem precisar solicitar o consentimento novamente.

Para configurar permissões de aplicativo para o aplicativo na experiência de registros de aplicativo no centro de administração do Microsoft Entra, siga estas etapas:

  • Na página de permissões de API do aplicativo, escolha Adicionar uma permissão.
  • Selecione Microsoft Graph> selecione Permissões do aplicativo.
  • Na caixa de diálogo Selecionar Permissões , escolha as permissões para configurar o aplicativo.

A captura de tela a seguir mostra a caixa de diálogo Selecionar Permissões para permissões de aplicativo do Microsoft Graph.

Selecionar Janela de permissões para as permissões do aplicativo do Microsoft Graph.

Importante

Sempre configure o conjunto de permissões com privilégios mínimos exigido pelo aplicativo. Para obter mais informações, consulte Práticas recomendadas para usar permissões do Microsoft Graph.

Os administradores podem conceder as permissões de que seu aplicativo precisa no centro de administração do Microsoft Entra. No entanto, se você não tiver acesso ao centro de administração do Microsoft Entra, poderá fornecer uma experiência de inscrição para administradores usando o ponto de extremidade da plataforma de identidade da Microsoft/adminconsent.

Importante

Ao alterar as permissões configuradas, você também deve repetir o processo de consentimento do administrador. As alterações feitas no portal de registro do aplicativo não são refletidas até que um administrador autorizado, como um administrador de função privilegiada, consinta novamente com o aplicativo.

Solicitação

// 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  HTTP/1.1
Parâmetro Condição Descrição
locatário Obrigatório O locatário do qual você deseja solicitar permissão. O valor pode estar em um formato GUID ou de nome amigável. Se você não souber a qual locatário o usuário pertence e quiser permitir que ele entre com qualquer locatário, use common.
client_id Obrigatório A ID do aplicativo que o portal de registro de aplicativo do Azure atribuiu ao seu aplicativo.
redirect_uri Obrigatório O URI de redirecionamento em que você deseja que a resposta seja enviada para o seu aplicativo manipular. Ele deve corresponder a um dos URIs de redirecionamento que você registrou no portal. Ele deve ser codificado como URL e pode ter segmentos de caminho adicionais.
estado Recomendado Um valor incluído na solicitação que também é retornado na resposta do token. Pode ser uma cadeia de caracteres de qualquer conteúdo que você desejar. O estado é usado para codificar informações sobre o estado do usuário no aplicativo antes da solicitação de autenticação, como a página ou a exibição em que ele estava.

Com solicitações para o ponto de extremidade, o /adminconsent Microsoft Entra ID impõe que somente um administrador autorizado possa entrar para concluir a solicitação. O administrador é solicitado a aprovar todas as permissões de aplicativo solicitadas para seu aplicativo no portal de registro de aplicativo.

A captura de tela a seguir é um exemplo da caixa de diálogo de consentimento que o Microsoft Entra ID apresenta ao administrador:

A caixa de diálogo de consentimento do administrador indica as permissões de consentimento e quais ações as permissões permitem.

Resposta

Se o administrador aprovar as permissões de seu aplicativo, a resposta bem-sucedida ficará assim:

// Line breaks are for legibility only.

https://localhost/myapp/permissions?admin_consent=True&tenant=38d49456-54d4-455d-a8d6-c383c71e0a6d&state=12345#
Parâmetro Descrição
locatário O locatário que concede ao seu aplicativo as permissões solicitadas, em formato GUID.
state Um valor incluído na solicitação que também é retornado na resposta do token. Pode ser uma cadeia de caracteres de qualquer conteúdo que você desejar. O estado codifica informações sobre o estado do usuário no aplicativo antes da solicitação de autenticação, como a página ou a exibição em que ele estava.
admin_consent Defina como true.

Etapa 3: solicitar um token de acesso

No fluxo de concessão de credenciais do cliente OAuth 2.0, use os valores de ID do aplicativo e segredo do cliente que você salvou quando registrou seu aplicativo para solicitar um token de acesso diretamente do ponto de extremidade da plataforma de identidade da Microsoft/token.

Especifique as permissões pré-configuradas passando https://graph.microsoft.com/.default como o valor do scope parâmetro na solicitação de token.

Solicitação de token

Envie uma solicitação POST ao endpoint da /token plataforma de identidade para adquirir um token de acesso. Nessa solicitação, o cliente usa o segredo do cliente.

// 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=qWgdYA....L1qKv5bPX
&grant_type=client_credentials
Parâmetro Condição Descrição
locatário Obrigatório O locatário do qual você deseja solicitar permissão. O valor pode estar em um formato GUID ou de nome amigável.
client_id Obrigatório A ID do aplicativo que o portal de registro de aplicativo do Azure atribuído quando você registrou seu aplicativo.
scope Obrigatório O valor passado para o parâmetro scope nesta solicitação deve ser o identificador (URI do ID do aplicativo) do recurso desejado, afixado com o sufixo .default. Por exemplo, o URI da ID do aplicativo de recursos do Microsoft Graph é https://graph.microsoft.com/. Para o Microsoft Graph, o valor de scope é, portanto, https://graph.microsoft.com/.default. Esse valor informa o ponto de extremidade da plataforma de identidade da Microsoft para incluir no token de acesso todas as permissões de nível de aplicativo que o administrador consentiu.
client_secret Obrigatório O segredo do cliente que você gerou para seu aplicativo no portal de registro de aplicativo. Verifique se a URL está codificada.
grant_type Obrigatório Deve ser client_credentials.

Resposta do token

Uma resposta bem-sucedida tem esta aparência:

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "ext_expires_in":3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}
Parâmetro Descrição
access_token O token de acesso solicitado. Seu aplicativo pode usar esse token em chamadas para o Microsoft Graph.
expires_in Por quanto tempo o token de acesso é válido (em segundos).
ext_expires_in Usado para indicar um tempo de vida estendido para o token de acesso e para dar suporte à resiliência quando o serviço de emissão de token não está respondendo.
token_type Indica o valor do tipo de token. O único tipo compatível com o Microsoft Entra ID é Bearer.

Etapa 4: usar o token de acesso para chamar o Microsoft Graph

Depois de obter um token de acesso, o aplicativo o usa para chamar o Microsoft Graph anexando o token de acesso como um token de portador ao cabeçalho Authorization em uma solicitação HTTP. A solicitação a seguir obtém todos os usuários no locatário. O aplicativo deve ter a permissão User.Read.All para chamar essa API.

GET https://graph.microsoft.com/v1.0/users  HTTP/1.1
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
Host: graph.microsoft.com

Uma resposta bem-sucedida tem esta aparência (alguns cabeçalhos de resposta foram removidos):

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
Date: Wed, 26 Apr 2017 19:53:49 GMT
Content-Length: 407

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users",
    "value": [
        {
            "businessPhones": [],
            "displayName": "Conf Room Adams",
            "givenName": null,
            "jobTitle": null,
            "mail": "Adams@Contoso.com",
            "mobilePhone": null,
            "officeLocation": null,
            "preferredLanguage": null,
            "surname": null,
            "userPrincipalName": "Adams@Contoso.com",
            "id": "8afc02cb-4d62-4dba-b536-9f6d73e9be26"
        },
        {
            "businessPhones": [
                "+1 425 555 0109"
            ],
            "displayName": "Adele Vance",
            "givenName": "Adele",
            "jobTitle": "Retail Manager",
            "mail": "AdeleV@Contoso.com",
            "mobilePhone": null,
            "officeLocation": "18/2111",
            "preferredLanguage": null,
            "surname": "Vance",
            "userPrincipalName": "AdeleV@Contoso.com",
            "id": "59bb3898-0621-4414-ac61-74f9d7201355"
        }
    ]
}

Recursos e cenários de aplicativo com suporte

Os aplicativos que chamam o Microsoft Graph com sua própria identidade se enquadram em uma das duas categorias:

  • Serviços em segundo plano (daemons) que podem ser executados em um servidor sem um usuário conectado.
  • Aplicativos que têm um usuário conectado, mas também chamam o Microsoft Graph com sua própria identidade. Por exemplo, para usar uma funcionalidade que requer privilégios mais elevados do que o usuário tem.

Neste artigo, o aplicativo usa um segredo do cliente como a credencial. Opcionalmente, você pode configurar um certificado ou uma credencial de identidade federada.

Para obter mais informações sobre aplicativos que chamam o Microsoft Graph com sua própria identidade e usam o fluxo de credenciais do cliente, consulte Fluxos de autenticação e cenários de aplicativos: aplicativo daemon que chama uma API Web no nome do daemon.

Usar a Biblioteca de Autenticação da Microsoft (MSAL)

Neste artigo, você vê os detalhes do protocolo de baixo nível necessários somente ao criar e emitir manualmente solicitações HTTP brutas para executar o fluxo de credenciais do cliente. Em aplicativos de produção, use uma biblioteca de autenticação criada pela Microsoft ou com suporte, como a MSAL (Biblioteca de Autenticação da Microsoft), para obter tokens de segurança e chamar APIs Web protegidas, como o Microsoft Graph.

A MSAL e outras bibliotecas de autenticação com suporte simplificam o processo para você, manipulando detalhes como validação, manipulação de cookies, cache de token e conexões seguras. Essas bibliotecas permitem que você se concentre na funcionalidade do seu aplicativo.

Acesse os exemplos de código da plataforma de identidade da Microsoft para ver como usar a MSAL para obter tokens de acesso e chamar o Microsoft Graph.

Conteúdo relacionado

  • Last updated on