Plataforma de identidades da Microsoft e fluxo de credenciais de cliente OAuth 2.0
O fluxo de concessão de credenciais do cliente OAuth 2.0 permite que um serviço Web (cliente confidencial) use suas próprias credenciais, em vez de representar um usuário, para autenticar ao chamar outro serviço Web. A concessão especificada no RFC 6749, às vezes chamada de OAuth de duas pernas, pode ser usada para acessar recursos hospedados na Web usando a identidade de um aplicativo. Esse tipo é comumente usado para interações de servidor para servidor que devem ser executadas em segundo plano, sem interação imediata com um usuário, e é frequentemente chamado de daemons ou contas de serviço.
No fluxo de credenciais do cliente, as permissões são concedidas diretamente ao próprio aplicativo por um administrador. Quando o aplicativo apresenta um token para um recurso, o recurso impõe que o próprio aplicativo tenha autorização para executar uma ação, uma vez que não há nenhum usuário envolvido na autenticação. Este artigo aborda ambas as etapas necessárias para:
Este artigo descreve como programar diretamente contra o protocolo na sua aplicação. Quando possível, recomendamos que utilize as Bibliotecas de Autenticação da Microsoft (MSAL) suportadas para adquirir tokens e chamar as APIs Web seguras. Você também pode consultar os aplicativos de exemplo que usam o MSAL. Como uma observação lateral, os tokens de atualização nunca serão concedidos com esse fluxo, pois client_id e client_secret (que seria necessário para obter um token de atualização) podem ser usados para obter um token de acesso.
Para um nível mais alto de garantia, a plataforma de identidade da Microsoft também permite que o serviço de chamada se autentique usando um certificado ou credencial federada em vez de um segredo compartilhado. Como as próprias credenciais do aplicativo estão sendo usadas, essas credenciais devem ser mantidas seguras. Nunca publique essa credencial em seu código-fonte, incorpore-a em páginas da Web ou use-a em um aplicativo nativo amplamente distribuído.
Diagrama de protocolo
Todo o fluxo de credenciais do cliente é semelhante ao diagrama a seguir. Descrevemos cada uma das etapas mais adiante neste artigo.
Obter autorização direta
Normalmente, um aplicativo recebe autorização direta para acessar um recurso de duas maneiras:
- Através de uma lista de controle de acesso (ACL) no recurso
- Através da atribuição de permissão de aplicativo no Microsoft Entra ID
Esses dois métodos são os mais comuns no Microsoft Entra ID e os recomendamos para clientes e recursos que executam o fluxo de credenciais do cliente. Um recurso também pode optar por autorizar seus clientes de outras maneiras. Cada servidor de recursos pode escolher o método que faz mais sentido para sua aplicação.
Listas de controlo de acesso
Um provedor de recursos pode impor uma verificação de autorização com base em uma lista de IDs de aplicativo (cliente) que ele conhece e concede um nível específico de acesso. Quando o recurso recebe um token da plataforma de identidade da Microsoft, ele pode decodificar o token e extrair a ID do aplicativo do cliente das appid declarações e iss . Em seguida, ele compara o aplicativo com uma lista de controle de acesso (ACL) que ele mantém. A granularidade e o método da ACL podem variar substancialmente entre recursos.
Um caso de uso comum é usar uma ACL para executar testes para um aplicativo Web ou para uma API Web. A API da Web pode conceder apenas um subconjunto de permissões completas a um cliente específico. Para executar testes de ponta a ponta na API, você pode criar um cliente de teste que adquire tokens da plataforma de identidade da Microsoft e, em seguida, os envia para a API. Em seguida, a API verifica a ACL quanto ao ID do aplicativo do cliente de teste para obter acesso total a toda a funcionalidade da API. Se você usar esse tipo de ACL, certifique-se de validar não apenas o valor do appid chamador, mas também validar se o iss valor do token é confiável.
Esse tipo de autorização é comum para daemons e contas de serviço que precisam acessar dados de propriedade de usuários consumidores que têm contas pessoais da Microsoft. Para dados pertencentes a organizações, recomendamos que você obtenha a autorização necessária por meio de permissões de aplicativo.
Controlando tokens sem a roles reivindicação
Para habilitar esse padrão de autorização baseado em ACL, o Microsoft Entra ID não exige que os aplicativos sejam autorizados a obter tokens para outro aplicativo. Assim, tokens somente de aplicativo podem ser emitidos sem uma roles reivindicação. Os aplicativos que expõem APIs devem implementar verificações de permissão para aceitar tokens.
Se você quiser impedir que os aplicativos obtenham tokens de acesso somente de aplicativo sem função para seu aplicativo, certifique-se de que os requisitos de atribuição estejam habilitados para seu aplicativo. Isso impedirá que usuários e aplicativos sem funções atribuídas possam obter um token para esse aplicativo.
Permissões de aplicação
Em vez de usar ACLs, você pode usar APIs para expor um conjunto de permissões de aplicativos. Eles são concedidos a um aplicativo pelo administrador de uma organização e podem ser usados apenas para acessar dados pertencentes a essa organização e seus funcionários. Por exemplo, o Microsoft Graph expõe várias permissões de aplicativo para fazer o seguinte:
- Ler correio em todas as caixas de correio
- Ler e escrever correio em todas as caixas de correio
- Enviar e-mail como qualquer usuário
- Ler dados do diretório
Para usar funções de aplicativo (permissões de aplicativo) com sua própria API (em oposição ao Microsoft Graph), você deve primeiro expor as funções de aplicativo no registro de aplicativo da API no centro de administração do Microsoft Entra. Em seguida, configure as funções de aplicativo necessárias selecionando essas permissões no registro do aplicativo cliente. Se você não tiver exposto nenhuma função de aplicativo no registro de aplicativo da API, não poderá especificar permissões de aplicativo para essa API no registro do aplicativo cliente no centro de administração do Microsoft Entra.
Ao autenticar como um aplicativo (em vez de com um usuário), você não pode usar permissões delegadas porque não há nenhum usuário para seu aplicativo agir em nome. Você deve usar permissões de aplicativo, também conhecidas como funções de aplicativo, concedidas por um administrador ou pelo proprietário da API.
Para obter mais informações sobre permissões de aplicativo, consulte Permissões e consentimento.
Recomendado: Inicie sessão com o administrador na sua aplicação para atribuir funções à aplicação
Normalmente, quando você cria um aplicativo que usa permissões de aplicativo, o aplicativo requer uma página ou exibição na qual o administrador aprova as permissões do aplicativo. Esta página pode fazer parte do fluxo de início de sessão da aplicação, parte das definições da aplicação ou um fluxo de ligação dedicado. Muitas vezes, faz sentido que a aplicação mostre esta vista de ligação apenas depois de um utilizador ter iniciado sessão com uma conta Microsoft escolar ou profissional.
Se você entrar o usuário em seu aplicativo, poderá identificar a organização à qual o usuário pertence antes de pedir que o usuário aprove as permissões do aplicativo. Embora não seja estritamente necessário, pode ajudá-lo a criar uma experiência mais intuitiva para os seus utilizadores. Para iniciar sessão no utilizador, siga os tutoriais do protocolo da plataforma de identidade da Microsoft.
Solicitar as permissões de um administrador de diretório
Quando estiver pronto para solicitar permissões ao administrador da organização, você poderá redirecionar o usuário para o ponto de extremidade de consentimento de administrador da plataforma de identidade da Microsoft.
// Line breaks are for legibility only.
GET https://login.microsoftonline.com/{tenant}/adminconsent?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&state=12345
&redirect_uri=http://localhost/myapp/permissions
Dica profissional: tente colar a seguinte solicitação em um navegador.
https://login.microsoftonline.com/common/adminconsent?client_id=00001111-aaaa-2222-bbbb-3333cccc4444&state=12345&redirect_uri=http://localhost/myapp/permissions
| Parâmetro | Condição | Description |
|---|---|---|
tenant |
Obrigatório | O locatário do diretório do qual você deseja solicitar permissão. Isso pode ser em GUID ou formato 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 |
Necessário | A ID do Aplicativo (cliente) que o Centro de administração do Microsoft Entra – Registros de aplicativo experiência atribuída ao seu aplicativo. |
redirect_uri |
Necessário | O URI de redirecionamento para onde você deseja que a resposta seja enviada para seu aplicativo manipular. Ele deve corresponder exatamente a um dos URIs de redirecionamento que você registrou no portal, exceto que ele deve ser codificado por URL e pode ter segmentos de caminho adicionais. |
state |
Recomendado | Um valor incluído na solicitação que também é retornado na resposta do token. Pode ser uma sequência de qualquer conteúdo que você quiser. 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 exibição em que eles estavam. |
Neste ponto, o Microsoft Entra ID impõe que apenas um administrador de locatário possa entrar para concluir a solicitação. O administrador será solicitado a aprovar todas as permissões diretas do aplicativo que você solicitou para seu aplicativo no portal de registro do aplicativo.
Resposta com êxito
Se o administrador aprovar as permissões para seu aplicativo, a resposta bem-sucedida terá esta aparência:
GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True
| Parâmetro | Description |
|---|---|
tenant |
O locatário de diretório que concedeu ao seu aplicativo as permissões solicitadas, no formato GUID. |
state |
Um valor incluído na solicitação que também é retornado na resposta do token. Pode ser uma sequência de qualquer conteúdo que você quiser. 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 exibição em que eles estavam. |
admin_consent |
Defina como True. |
Resposta de erro
Se o administrador não aprovar as permissões para o seu aplicativo, a resposta com falha terá esta aparência:
GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
| Parâmetro | Description |
|---|---|
error |
Uma cadeia de caracteres de código de erro que você pode usar para classificar tipos de erros e que você pode usar para reagir a erros. |
error_description |
Uma mensagem de erro específica que pode ajudá-lo a identificar a causa raiz de um erro. |
Depois de receber uma resposta bem-sucedida do ponto de extremidade de provisionamento do aplicativo, seu aplicativo ganhou as permissões diretas do aplicativo solicitadas. Agora você pode solicitar um token para o recurso desejado.
Obter um token
Depois de obter a autorização necessária para seu aplicativo, prossiga com a aquisição de tokens de acesso para APIs. Para obter um token usando a concessão de credenciais do cliente, envie uma solicitação POST para a plataforma de identidade da /token Microsoft. Existem alguns casos diferentes:
- Solicitação de token de acesso com um segredo compartilhado
- Solicitação de token de acesso com um certificado
- Solicitação de token de acesso com uma credencial federada
Primeiro caso: Solicitação de token de acesso com um segredo compartilhado
POST /{tenant}/oauth2/v2.0/token HTTP/1.1 //Line breaks for clarity
Host: login.microsoftonline.com:443
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=sampleCredentials
&grant_type=client_credentials
# Replace {tenant} with your tenant!
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'client_id=00001111-aaaa-2222-bbbb-3333cccc4444&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default&client_secret=A1bC2dE3f...&grant_type=client_credentials' 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token'
| Parâmetro | Condição | Description |
|---|---|---|
tenant |
Obrigatório | O locatário de diretório contra o qual o aplicativo planeja operar, no formato GUID ou nome de domínio. |
client_id |
Necessário | A ID do aplicativo atribuída ao seu aplicativo. Pode encontrar esta informação no portal onde registou a sua aplicação. |
scope |
Necessário | O valor passado para o scope parâmetro nesta solicitação deve ser o identificador de recurso (URI de ID do aplicativo) do recurso desejado, afixado com o sufixo .default . Todos os escopos incluídos devem ser para um único recurso. A inclusão de escopos para vários recursos resultará em um erro. Para o exemplo do Microsoft Graph, o valor é https://graph.microsoft.com/.default. Esse valor informa à plataforma de identidade da Microsoft que, de todas as permissões diretas de aplicativo que você configurou para seu aplicativo, o ponto de extremidade deve emitir um token para as associadas ao recurso que você deseja usar. Para saber mais sobre o /.default escopo, consulte a documentação de consentimento. |
client_secret |
Necessário | O segredo do cliente que você gerou para seu aplicativo no portal de registro do aplicativo. O segredo do cliente deve ser codificado por URL antes de ser enviado. O padrão de autenticação básica de fornecer credenciais no cabeçalho de autorização, de acordo com RFC 6749 , também é suportado. |
grant_type |
Necessário | Deve ser definido como client_credentials. |
Segundo caso: Solicitação de token de acesso com um certificado
POST /{tenant}/oauth2/v2.0/token HTTP/1.1 // Line breaks for clarity
Host: login.microsoftonline.com:443
Content-Type: application/x-www-form-urlencoded
scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=11112222-bbbb-3333-cccc-4444dddd5555
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials
| Parâmetro | Condição | Description |
|---|---|---|
tenant |
Obrigatório | O locatário de diretório contra o qual o aplicativo planeja operar, no formato GUID ou nome de domínio. |
client_id |
Necessário | A ID do aplicativo (cliente) atribuída ao seu aplicativo. |
scope |
Necessário | O valor passado para o scope parâmetro nesta solicitação deve ser o identificador de recurso (URI de ID do aplicativo) do recurso desejado, afixado com o sufixo .default . Todos os escopos incluídos devem ser para um único recurso. A inclusão de escopos para vários recursos resultará em um erro. Para o exemplo do Microsoft Graph, o valor é https://graph.microsoft.com/.default. Esse valor informa à plataforma de identidade da Microsoft que, de todas as permissões diretas de aplicativo que você configurou para seu aplicativo, o ponto de extremidade deve emitir um token para as associadas ao recurso que você deseja usar. Para saber mais sobre o /.default escopo, consulte a documentação de consentimento. |
client_assertion_type |
Necessário | O valor deve ser definido como urn:ietf:params:oauth:client-assertion-type:jwt-bearer. |
client_assertion |
Necessário | Uma asserção (um token da Web JSON) que você precisa criar e assinar com o certificado registrado como credenciais para seu aplicativo. Leia sobre credenciais de certificado para saber como registrar seu certificado e o formato da declaração. |
grant_type |
Necessário | Deve ser definido como client_credentials. |
Os parâmetros para a solicitação baseada em certificado diferem em apenas uma maneira da solicitação baseada em segredo compartilhado: o client_secret parâmetro é substituído pelos client_assertion_type parâmetros e client_assertion .
Terceiro caso: Solicitação de token de acesso com uma credencial federada
POST /{tenant}/oauth2/v2.0/token HTTP/1.1 // Line breaks for clarity
Host: login.microsoftonline.com:443
Content-Type: application/x-www-form-urlencoded
scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=11112222-bbbb-3333-cccc-4444dddd5555&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials
| Parâmetro | Condição | Description |
|---|---|---|
client_assertion |
Obrigatório | Uma asserção (um token da Web JWT ou JSON) que seu aplicativo obtém de outro provedor de identidade fora da plataforma de identidade da Microsoft, como o Kubernetes. As especificidades deste JWT devem ser registradas em seu aplicativo como uma credencial de identidade federada. Leia sobre a federação de identidades de carga de trabalho para saber como configurar e usar asserções geradas por outros provedores de identidade. |
Tudo na solicitação é igual ao fluxo baseado em certificado, com a exceção crucial da origem do client_assertion. Nesse fluxo, seu aplicativo não cria a asserção JWT em si. Em vez disso, seu aplicativo usa um JWT criado por outro provedor de identidade. Isso é chamado de federação de identidade de carga de trabalho, onde a identidade de seus aplicativos em outra plataforma de identidade é usada para adquirir tokens dentro da plataforma de identidade da Microsoft. Isso é mais adequado para cenários entre nuvens, como hospedar sua computação fora do Azure, mas acessar APIs protegidas pela plataforma de identidade da Microsoft. Para obter informações sobre o formato necessário de JWTs criados por outros provedores de identidade, leia sobre o formato de asserção.
Resposta com êxito
Uma resposta bem-sucedida de qualquer método tem esta aparência:
{
"token_type": "Bearer",
"expires_in": 3599,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}
| Parâmetro | Description |
|---|---|
access_token |
O token de acesso solicitado. O aplicativo pode usar esse token para autenticar no recurso seguro, como em uma API da Web. |
token_type |
Indica o valor do tipo de token. O único tipo suportado pela plataforma de identidade da Microsoft é bearero . |
expires_in |
A quantidade de tempo que um token de acesso é válido (em segundos). |
Aviso
Não tente validar ou ler tokens para qualquer API que você não possua, incluindo os tokens neste exemplo, em seu código. Os tokens para serviços da Microsoft podem usar um formato especial que não será validado como um JWT e também podem ser criptografados para usuários consumidores (conta da Microsoft). Embora a leitura de tokens seja uma ferramenta útil de depuração e aprendizagem, não dependa disso em seu código ou assuma especificidades sobre tokens que não são para uma API que você controla.
Resposta de erro
Uma resposta de erro (400 Bad Request) tem esta aparência:
{
"error": "invalid_scope",
"error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/.default is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
"error_codes": [
70011
],
"timestamp": "YYYY-MM-DD HH:MM:SSZ",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Parâmetro | Description |
|---|---|
error |
Uma cadeia de caracteres de código de erro que você pode usar para classificar tipos de erros que ocorrem e para reagir a erros. |
error_description |
Uma mensagem de erro específica que pode ajudá-lo a identificar a causa raiz de um erro de autenticação. |
error_codes |
Uma lista de códigos de erro específicos do STS que podem ajudar no diagnóstico. |
timestamp |
A hora em que o erro ocorreu. |
trace_id |
Um identificador exclusivo para a solicitação de ajuda com diagnósticos. |
correlation_id |
Um identificador exclusivo para a solicitação para ajudar com diagnósticos entre componentes. |
Usar um token
Agora que você adquiriu um token, use-o para fazer solicitações ao recurso. Quando o token expirar, repita a solicitação para o /token ponto de extremidade para adquirir um novo token de acesso.
GET /v1.0/users HTTP/1.1
Host: graph.microsoft.com:443
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
Tente o seguinte comando no seu terminal, garantindo a substituição do token pelo seu.
curl -X GET -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...." 'https://graph.microsoft.com/v1.0/users'
Exemplos de código e outra documentação
Leia a documentação de visão geral das credenciais do cliente na Biblioteca de Autenticação da Microsoft
| Exemplo | Plataforma | Description |
|---|---|---|
| diretório-ativo-dotnetcore-daemon-v2 | .NET 6.0+ | Um aplicativo ASP.NET Core que exibe os usuários de um locatário consultando o Microsoft Graph usando a identidade do aplicativo, em vez de em nome de um usuário. O exemplo também ilustra a variação usando certificados para autenticação. |
| diretório-ativo-dotnet-daemon-v2 | ASP.NET MVC | Um aplicativo Web que sincroniza dados do Microsoft Graph usando a identidade do aplicativo, em vez de em nome de um usuário. |
| ms-identity-javascript-nodejs-console | Node.js Console | Um aplicativo Node.js que exibe os usuários de um locatário consultando o Microsoft Graph usando a identidade do aplicativo |