Obter acesso sem um usuário
Para chamar o Microsoft Graph, uma aplicação tem de obter um token de acesso a partir da plataforma de identidades da Microsoft. Este token de acesso inclui informações sobre se a aplicação está autorizada a aceder ao Microsoft Graph em nome de um utilizador com sessão iniciada ou com a sua própria identidade. Este artigo fornece orientações sobre como uma aplicação pode aceder ao Microsoft Graph com a sua própria identidade, também denominada acesso apenas à aplicação.
Este artigo detalha os pedidos HTTP não processados envolvidos para uma aplicação chamar o Microsoft Graph com a sua própria identidade através de um fluxo popular chamado fluxo de concessão de credenciais de cliente OAuth 2.0. Em alternativa, pode evitar escrever pedidos HTTP não processados e utilizar uma biblioteca de autenticação criada pela Microsoft ou suportada que o ajuda a obter tokens de acesso e a chamar o Microsoft Graph. Para obter mais informações, consulte Utilizar a Biblioteca de Autenticação da Microsoft (MSAL).
Neste artigo, vai concluir os seguintes passos ao utilizar o fluxo de credenciais do cliente:
- Configurar permissões de aplicação do Microsoft Graph na aplicação.
- Pedir consentimento do administrador.
- Pedir um token de acesso.
- Chame o Microsoft Graph com o token de acesso.
Pré-requisitos
Antes de prosseguir com os passos neste artigo:
- Compreenda os conceitos de autenticação e autorização na plataforma de identidades da Microsoft. Para obter mais informações, veja Noções básicas de autenticação e autorização.
- Registe a aplicação com o Microsoft Entra ID. Para obter mais informações, veja Registar uma aplicação na plataforma de identidades da Microsoft. Guarde os seguintes valores do registo de aplicações:
- O ID da aplicação (conhecido como ID do Objeto no centro de administração do Microsoft Entra).
- Um segredo do cliente (palavra-passe da aplicação), um certificado ou uma credencial de identidade federada.
- Um URI de redirecionamento para a aplicação receber respostas de tokens do Microsoft Entra ID.
- Um URI de redirecionamento para o serviço receber respostas de consentimento do administrador se a aplicação implementar a funcionalidade para pedir o consentimento do administrador.
Configurar permissões para o Microsoft Graph
O Microsoft Graph expõe permissões de aplicação para aplicações que chamam o Microsoft Graph com a sua própria identidade. Estas permissões requerem sempre o consentimento do administrador.
Pode pré-configurar as permissões de aplicação de que a aplicação precisa quando registar a aplicação. Um administrador pode dar consentimento a estas permissões através do centro de administração do Microsoft Entra quando instala a aplicação na respetiva organização ou pode fornecer uma experiência de inscrição na aplicação através da qual os administradores podem dar consentimento às permissões que configurou. Assim que o ID do Microsoft Entra registar o consentimento do administrador, a aplicação pode pedir tokens sem ter de pedir novamente o consentimento.
Para configurar permissões de aplicação para a aplicação na experiência de registos de aplicações no centro de administração do Microsoft Entra, siga estes passos:
- Na página de permissões da API da aplicação, selecione Adicionar uma permissão.
- Selecione Microsoft Graph> selecione Permissões da aplicação.
- Na caixa de diálogo Selecionar Permissões , selecione as permissões a configurar para a aplicação.
A captura de tela a seguir mostra a caixa de diálogo Selecionar Permissões para permissões de aplicativo do Microsoft Graph.
Importante
Configure sempre o conjunto de permissões com menos privilégios exigido pela aplicação. Para obter mais informações, veja Melhores práticas para utilizar permissões do Microsoft Graph.
Passo 2: Pedir consentimento do administrador
Os administradores podem conceder as permissões de que a sua aplicação precisa no centro de administração do Microsoft Entra. No entanto, quando não tem acesso ao centro de administração do Microsoft Entra, pode fornecer uma experiência de inscrição para administradores através do ponto final da plataforma /adminconsent de identidades da Microsoft.
Importante
Ao alterar as permissões configuradas, você também deve repetir o processo de consentimento do administrador. As alterações efetuadas no portal de registo de aplicações só são refletidas quando um administrador autorizado, como um administrador de função com privilégios, se reconsente na aplicação.
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 inquilino ao qual pretende pedir permissão. O valor pode estar no GUID ou num formato de nome amigável. Se não souber a que inquilino pertence o utilizador e quiser deixá-lo iniciar sessão com qualquer inquilino, utilize 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 para onde pretende que a resposta seja enviada para a sua aplicação processar. Tem de corresponder a um dos URIs de redirecionamento que registou no portal. Tem de ser codificado por URL e pode ter segmentos de caminho adicionais. |
| estado | Recomendado | Um valor incluído no pedido que também é devolvido na resposta do token. Pode ser uma cadeia de qualquer conteúdo que pretenda. O estado é utilizado para codificar informações sobre o estado do utilizador na aplicação antes de o pedido de autenticação ter ocorrido, como a página ou vista em que se encontravam. |
Experiência de consentimento do administrador
Com os pedidos para o ponto final, o ID do /adminconsent Microsoft Entra impõe que apenas um administrador autorizado possa iniciar sessão para concluir o pedido. É pedido ao administrador que aprove todas as permissões de aplicação pedidas para a sua aplicação no portal de registo de aplicações.
A seguinte captura de ecrã é um exemplo da caixa de diálogo de consentimento que o ID do Microsoft Entra apresenta ao administrador:
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 inquilino que concedeu à sua aplicação as permissões que pediu, no formato GUID. |
| state | Um valor incluído no pedido que também é devolvido na resposta do token. Pode ser uma cadeia de qualquer conteúdo que pretenda. O estado é utilizado para codificar informações sobre o estado do utilizador na aplicação antes de o pedido de autenticação ter ocorrido, como a página ou vista em que se encontravam. |
| admin_consent | Defina como Verdadeiro. |
Passo 3: Pedir um token de acesso
No fluxo de concessão de credenciais do cliente OAuth 2.0, você usa a ID do aplicativo e os valores secretos do cliente que salvou quando registrou seu aplicativo para solicitar um token de acesso diretamente do ponto de extremidade /tokenda plataforma de identidade da Microsoft.
Especifique as permissões pré-configuradas ao transmitir https://graph.microsoft.com/.default como o valor do scope parâmetro no pedido de token.
Solicitação de token
Envie um pedido POST para o ponto final da /token plataforma de identidades para adquirir um token de acesso. Neste pedido, o cliente utiliza 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 inquilino ao qual pretende pedir permissão. O valor pode estar no GUID ou num formato 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 ao ponto de extremidade da plataforma de identidade da Microsoft para incluir no token de acesso todas as permissões no nível do aplicativo que o administrador consentiu. |
| client_secret | Obrigatório | O segredo do cliente que gerou para a sua aplicação no portal de registo de aplicações. Certifique-se de que está codificado com URL. |
| 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. A sua aplicação pode utilizar este token em chamadas para o Microsoft Graph. |
| expires_in | Por quanto tempo o token de acesso é válido (em segundos). |
| ext_expires_in | Utilizado para indicar uma duração prolongada para o token de acesso e para suportar resiliência quando o serviço de emissão de tokens não está a responder. |
| token_type | Indica o valor do tipo de token. O único tipo que o Microsoft Entra ID suporta é Bearer. |
Passo 4: Utilizar o token de acesso para chamar o Microsoft Graph
Depois de ter um token de acesso, a aplicação utiliza-o para chamar o Microsoft Graph ao anexar o token de acesso como token de Portador ao cabeçalho Autorização num pedido HTTP. O pedido seguinte obtém todos os utilizadores no inquilino. A aplicação tem de ter a permissão User.Read.All para chamar esta 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 o seguinte aspeto (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
As aplicações que chamam o Microsoft Graph com a sua própria identidade enquadram-se numa de duas categorias:
- Serviços em segundo plano (daemons) que podem ser executados em um servidor sem um usuário conectado.
- As aplicações que têm um utilizador com sessão iniciada, mas também chamam o Microsoft Graph com a sua própria identidade. Por exemplo, para utilizar funcionalidades que requerem privilégios mais elevados do que o utilizador.
Neste artigo, a aplicação utilizou um segredo do cliente como credencial. Opcionalmente, pode configurar um certificado ou uma credencial de identidade federada.
Para obter mais informações sobre as aplicações que chamam o Microsoft Graph com a sua própria identidade e utilizam o fluxo de credenciais de cliente, veja Fluxos de autenticação e cenários de aplicações: aplicação Daemon que chama uma API Web no nome do daemon.
Utilizar a Biblioteca de Autenticação da Microsoft (MSAL)
Neste artigo, percorreu os detalhes de protocolo de baixo nível necessários apenas ao criar e emitir manualmente pedidos HTTP não processados para executar o fluxo de credenciais do cliente. Nas aplicações de produção, utilize uma biblioteca de autenticação criada pela Microsoft ou suportada, como a Biblioteca de Autenticação da Microsoft (MSAL), para obter tokens de segurança e chamar APIs Web protegidas, como o Microsoft Graph.
A MSAL e outras bibliotecas de autenticação suportadas simplificam o processo por si ao processar detalhes como validação, processamento de cookies, colocação em cache de tokens e ligações seguras; permitindo-lhe concentrar-se na funcionalidade da sua aplicação.
Aceda aos exemplos de código da plataforma de identidades da Microsoft para ver como utilizar a MSAL para obter tokens de acesso e chamar o Microsoft Graph.
Conteúdo relacionado
Explore os tutoriais do Microsoft Graph para criar aplicações básicas que acedem a dados em cenários apenas de aplicações.