Obter acesso sem um usuário
Para chamar o Microsoft Graph, um aplicativo deve obter um token de acesso do plataforma de identidade da Microsoft. Esse token de acesso inclui informações sobre 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 fornece diretrizes sobre como um aplicativo pode acessar o Microsoft Graph com sua própria identidade, também chamada de acesso somente aplicativo.
Este artigo detalha as solicitações HTTP brutas envolvidas para um aplicativo chamar o Microsoft Graph com sua própria identidade usando um fluxo popular chamado fluxo de concessão de credenciais de cliente OAuth 2.0. Como alternativa, você pode evitar escrever solicitações HTTP brutas e usar uma biblioteca de autenticação criada pela Microsoft ou com suporte que manipula muitos desses detalhes para você e 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).
Pré-requisitos
Antes de prosseguir com as etapas deste artigo:
- Entenda os conceitos de autenticação e autorização no plataforma de identidade da Microsoft. Para obter mais informações, confira Noções básicas de autenticação e autorização.
- Registre o aplicativo com Microsoft Entra ID. Para obter mais informações, consulte Registrar um aplicativo com o plataforma de identidade da Microsoft.
Etapas de autenticação e autorização
Para que um aplicativo obtenha autorização e acesso ao Microsoft Graph usando o fluxo de credenciais do cliente, você deve seguir estas cinco etapas:
- Registre o aplicativo com Microsoft Entra ID.
- Configurar permissões de aplicativo do Microsoft Graph no aplicativo.
- Solicitar consentimento do administrador.
- Solicite um token de acesso.
- Chame o Microsoft Graph usando o token de acesso.
1. Registrar o aplicativo
Antes que o aplicativo possa usar o ponto de extremidade plataforma de identidade da Microsoft ou chamar o Microsoft Graph, ele deve ser registrado corretamente. Siga as etapas para registrar seu aplicativo no centro de administração do Microsoft Entra.
No registro do aplicativo, salve os seguintes valores:
- A ID do aplicativo (conhecida como ID do objeto no centro de administração do Microsoft Entra) atribuída pelo portal de registro do aplicativo.
- 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 de Microsoft Entra ID.
- Um URI de redirecionamento para que o serviço receba respostas de consentimento do administrador se o aplicativo implementar a funcionalidade para solicitar o consentimento do administrador.
2. Configure permissões para o Microsoft Graph
O Microsoft Graph expõe permissões de aplicativo para aplicativos que chamam o Microsoft Graph sob sua própria identidade. Essas permissões sempre exigem o consentimento do administrador.
Você pré-configura as permissões de aplicativo que o aplicativo precisa ao registrar o aplicativo. Um administrador pode consentir com essas permissões usando o centro de administração do Microsoft Entra quando 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 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 no portal de registros de aplicativos do Azure, siga estas etapas:
- Na página de permissões de API do aplicativo, escolha Adicionar uma permissão.
- Selecione Microsoft Graph.
- Selecione Permissões de aplicativos.
- Na caixa de diálogo Selecionar Permissões , escolha as permissões para configurar para 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.
Importante
Sempre configure o conjunto de permissões menos privilegiado exigido pelo aplicativo. Para obter mais informações, confira Melhores práticas para usar permissões do Microsoft Graph.
3. Solicitar consentimento do administrador
Os administradores podem conceder as permissões que seu aplicativo precisa no centro de administração do Microsoft Entra. No entanto, quando 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 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 de aplicativos não serão refletidas até que um administrador autorizado, como um administrador global, se reconsente ao 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 diretório do qual você deseja solicitar permissão. O valor pode estar no GUID ou em um formato de nome amigável. Se você não sabe a qual locatário o usuário pertence e deseja deixá-lo entrar 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 no qual você deseja que a resposta seja enviada para que seu aplicativo seja manipulado. Ele deve corresponder a uma das URIs de redirecionamento que você registrou no portal. Ela deve ser codificada por 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 desejado. O estado é usado para codificar informações sobre o estado do usuário no aplicativo antes da solicitação de autenticação ocorrer, como a página ou a exibição em que eles estavam. |
Experiência de consentimento do administrador
Com solicitações para o /adminconsent ponto de extremidade, Microsoft Entra ID impõe que apenas um administrador autorizado possa entrar para concluir a solicitação. O administrador é solicitado a aprovar todas as permissões de aplicativo que você solicitou para seu aplicativo no portal de registro do aplicativo.
A captura de tela a seguir é um exemplo da caixa de diálogo de consentimento que Microsoft Entra ID 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 locatário do diretório que concedeu as permissões de aplicativo solicitadas, no 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 desejado. O estado é usado para codificar informações sobre o estado do usuário no aplicativo antes da solicitação de autenticação ocorrer, como a página ou a exibição em que eles estavam. |
| admin_consent | Defina como True. |
4. Solicitar 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 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 para o ponto de extremidade da /token plataforma de identidade para adquirir um token de acesso. Nesta 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=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials
| Parâmetro | Condição | Descrição |
|---|---|---|
| locatário | Obrigatório | O locatário do diretório do qual você deseja solicitar permissão. O valor pode estar no GUID ou em um 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 gerado para seu aplicativo no portal de registro do aplicativo. Verifique se ela está codificada em 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. 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 que Microsoft Entra ID dá suporte é Bearer. |
5. Use o token de acesso para chamar o Microsoft Graph
Depois de ter um token de acesso, o aplicativo o usa para chamar o Microsoft Graph anexando o token de acesso como um token bearer ao cabeçalho Autorização 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 se parece com esta (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 dessas 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 a funcionalidade que requer privilégios mais elevados do que o usuário.
Neste artigo, o aplicativo usou um segredo do cliente como 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 em sua própria identidade e usam o fluxo de credenciais do cliente, confira Fluxos de autenticação e cenários de aplicativo: aplicativo Daemon que chama uma API Web no nome do daemon.
Usar a MSAL (Biblioteca de Autenticação da Microsoft)
Neste artigo, você percorreu os detalhes de protocolo de baixo nível geralmente necessários somente ao criar manualmente e emitir 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 pela Microsoft, como o Microsoft Graph.
O MSAL e outras bibliotecas de autenticação com suporte simplificam o processo para você lidando com detalhes como validação, manipulação de cookie, cache de token e conexões seguras, permitindo que você se concentre na funcionalidade do seu aplicativo.
A Microsoft criou e mantém uma ampla seleção de exemplos de código que demonstram o uso de bibliotecas de autenticação com suporte com o plataforma de identidade da Microsoft. Para acessar esses exemplos de código, consulte os exemplos de código plataforma de identidade da Microsoft.
Conteúdo relacionado
- Escolha entre exemplos de código criados e mantidos pela Microsoft para executar aplicativos personalizados que usam bibliotecas de autenticação com suporte, usuários de entrada e chamar o Microsoft Graph. Confira tutoriais do Microsoft Graph.
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários