Plataforma de identidade da Microsoft e o fluxo de credenciais do cliente OAuth 2.0

O fluxo de concessão de credenciais de cliente do OAuth 2.0 permite que um serviço Web (cliente confidencial) use as próprias credenciais, em vez de personificação de um usuário, para autenticar-se ao chamar outro serviço Web. A concessão especificada na RFC 6749, às vezes chamada de OAuth de duas etapas, pode ser usada para acessar recursos hospedados na Web usando a identidade de um aplicativo. Esse tipo normalmente é usado para interações de servidor para servidor que devem ser executadas em segundo plano, sem interação imediata com um usuário e, geralmente, é 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 a um recurso, o recurso impõe que o próprio aplicativo tenha autorização para executar uma ação, já que não há nenhum usuário envolvido na autenticação. Este artigo aborda as duas etapas necessárias para:

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

Este artigo descreve como programar diretamente no protocolo do seu aplicativo. Quando possível, recomendamos que você use as MSAL (bibliotecas de autenticação da Microsoft) com suporte para adquirir tokens e chamar APIs Web seguras. Veja também os aplicativos de exemplo que usam MSAL. Como uma observação, os tokens de atualização nunca serão concedidos com esse fluxo, pois client_id e client_secret (que seriam necessários 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 uma 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 no código-fonte, insira-a em páginas da Web ou use-a em um aplicativo nativo amplamente distribuído.

Diagrama do 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

Um aplicativo geralmente recebe autorização direta para acessar um recurso de duas maneiras:

• Por meio de uma ACL (lista de controle de acesso) no recurso
• Por meio 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 são recomendados para clientes e recursos que executam o fluxo de credenciais de 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 seu aplicativo.

Listas de controle 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 declarações appid e iss. Em seguida, compara o aplicativo com uma ACL (lista de controle de acesso) que ele mantém. Granularidade e o método a ACL podem variar significativamente entre os recursos.

Um caso de uso comum é usar uma ACL para executar testes para um aplicativo Web ou para uma API Web. A API Web pode conceder apenas um subconjunto das permissões completas para um cliente específico. Para executar testes de ponta a ponta na API, você pode criar um cliente de teste para adquirir tokens da plataforma de identidade da Microsoft e, em seguida, enviá-los à API. A API então verifica a ACL para a ID do aplicativo do cliente de teste a fim de ter acesso completo à funcionalidade total da API. Se você usar esse tipo de ACL, certifique-se de validar não apenas o valor appid do chamador, mas também de validar que o valor iss do token é confiável.

Esse tipo de autorização é comum para daemons e contas de serviço que precisam acessar dados pertencentes a usuários consumidores com contas pessoais da Microsoft. Para dados de propriedade de organizações, é recomendável que você obtenha a autorização necessária por meio de permissões de aplicativo.

Controlando tokens sem a declaração roles

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. Portanto, tokens somente de aplicativo podem ser emitidos sem uma declaração roles. Os aplicativos que expõem APIs devem implementar verificações de permissão a fim de aceitar tokens.

Caso deseje impedir que os aplicativos obtenham tokens de acesso somente de aplicativo sem função para o seu aplicativo, verifique se os requisitos de atribuição estão habilitados para o seu aplicativo. Isso impedirá que usuários e aplicativos sem funções atribuídas obtenham token para esse aplicativo.

Permissões de aplicativo

Em vez de usar ACLs, você pode usar APIs para expor um conjunto de permissões de aplicativo. Elas são concedidas a um aplicativo por um administrador de uma organização e só podem ser usadas para acessar os 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 emails em todas as caixas de correio
• Ler e gravar mensagens em todas as caixas de correio
• Enviar emails como qualquer usuário
• Ler dados do diretório

Para usar funções de aplicativo (permissões de aplicativo) com sua API (em vez do Microsoft Graph), primeiro, exponha as funções de aplicativo no registro do 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 expuser nenhuma função de aplicativo no registro do aplicativo da API, não poderá especificar as permissões de aplicativo para essa API no registro do aplicativo cliente no centro de administração do Microsoft Entra.

Ao se autenticar como um aplicativo (em vez de um usuário), você não poderá usar as permissões delegadas, pois não há usuários em nome dos quais o aplicativo possa atuar. Você precisa usar permissões de aplicativo, também conhecidas como funções de aplicativo, que são concedidas por um administrador ou pelo proprietário da API.

Para obter mais informações sobre as permissões de aplicativo, confira Permissões e consentimento.

Recomendado: assine o administrador em seu aplicativo para que as funções de aplicativo sejam atribuídas

Normalmente, quando você cria um aplicativo que usa as permissões de aplicativo, o aplicativo exige uma página ou exibição na qual o administrador aprova as permissões do aplicativo. Essa página pode ser parte do fluxo de entrada do aplicativo, parte das configurações do aplicativo ou um fluxo dedicado de conexão. Geralmente, faz sentido que o aplicativo somente mostre o modo de exibição de conexão depois que o usuário entra com uma conta corporativa ou de estudante da Microsoft.

Se conectar o usuário ao seu aplicativo, você poderá identificar a organização à qual o usuário pertence antes de solicitar que o usuário aprove as permissões de aplicativo. Embora não seja estritamente necessário, isso pode ajudá-lo a criar uma experiência mais intuitiva para os usuários. Para conectar o usuário, siga os tutoriais de protocolo da plataforma de identidade da Microsoft.

Solicitar permissões de um administrador de diretório

Quando você estiver pronto para solicitar permissões ao administrador da organização, redirecione o usuário ao ponto de extremidade de consentimento do 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 solicitação a seguir em um navegador.

https://login.microsoftonline.com/common/adminconsent?client_id=00001111-aaaa-2222-bbbb-3333cccc4444&state=12345&redirect_uri=http://localhost/myapp/permissions

Nesse ponto, o Microsoft Entra ID impõe que somente um administrador de locatário pode entrar para concluir a solicitação. O administrador deverá aprovar todas as permissões diretas do aplicativo que você solicitou para o aplicativo no portal de registro de aplicativos.

Resposta bem-sucedida

Se o administrador aprovar as permissões para o 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 de 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, o aplicativo terá as permissões diretas solicitadas. Agora você pode solicitar um token para o recurso desejado.

Obter um token

Após adquirir a autorização necessária para seu aplicativo, continue adquirindo os tokens de acesso para as APIs. Para obter um token usando a concessão de credenciais do cliente, envie uma solicitação POST para a plataforma de identidade da Microsoft /token. Há 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 o solicitação baseada em certificado se difere apenas de uma maneira da solicitação baseada em segredo compartilhado: o parâmetro client_secret é substituído pelos parâmetros client_assertion_type 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 uma exceção crucial da origem de client_assertion. Nesse fluxo, seu aplicativo não cria a instrução JWT em si. Seu aplicativo usa um JWT criado por outro provedor de identidade. Isso é chamado de federação de identidade de carga de trabalho, em que sua identidade de 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, por exemplo, 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 criado por outros provedores de identidade, leia sobre o formato de declaração.

Resposta bem-sucedida

Uma resposta bem-sucedida de um dos métodos tem a seguinte aparência:

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}

Resposta de erro

Uma resposta de erro (400 Solicitação Incorreta) tem a seguinte 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 para o recurso. Quando o token expirar, repita a solicitação para o ponto de extremidade /token a fim de adquirir um novo token de acesso.

GET /v1.0/users HTTP/1.1
Host: graph.microsoft.com:443
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...

Experimente o comando a seguir em seu terminal, garantindo substituir o token pelo seu próprio.

curl -X GET -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG..." 'https://graph.microsoft.com/v1.0/users'

Exemplos de código e outras documentações

Leia a documentação de visão geral de credenciais de cliente da biblioteca de autenticação da Microsoft