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:

• Autorizar um aplicativo a chamar uma API
• Como obter os tokens necessários para chamar essa API.

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

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

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

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=qWgdYAmab0YSkuL1qKv5bPX
&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'

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

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

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..."
}

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"
}

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 eyJ0eXAiOiJKV1QiLCJhbG...

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