Plataforma de identidade da Microsoft e o fluxo On-Behalf-Of de OAuth 2.0

O fluxo OBO (On-Behalf-Of) descreve o cenário de uma API Web que usa uma identidade diferente dela para chamar outra API Web. Conhecido como delegação no OAuth, a intenção é transmitir a identidade e as permissões de um usuário por meio da cadeia de solicitações.

Para que o serviço de camada intermediária faça solicitações autenticadas para o serviço downstream, ele precisa proteger um token de acesso da plataforma de identidade da Microsoft. Ele usa apenas escopos delegados e não funções de aplicativo. As funções permanecem anexadas à entidade de segurança (o usuário) e nunca ao aplicativo que opera em nome do usuário. Isso ocorre para impedir que o usuário obtenha permissão em recursos aos quais não deve ter acesso.

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 a MSAL para obter exemplos.

Limitações do cliente

Se uma entidade de serviço solicitar um token somente de aplicativo e o enviar para uma API, essa API trocará um token que não representa a entidade de serviço original. Isso ocorre porque o fluxo OBO só funciona para entidades de usuário. Em vez disso, ele precisa usar o fluxo de credenciais do cliente para obter um token somente de aplicativo. No caso dos SPAs (aplicativos de página única), eles devem transmitir um token de acesso para um cliente confidencial de camada intermediária a fim de executar os fluxos OBO.

Se um cliente usa o fluxo implícito para obter um id_token e tem caracteres curinga em uma URL de resposta, o id_token não pode ser usado para um fluxo OBO. Um curinga é uma URL que termina com um caractere *. Por exemplo, se https://myapp.com/* foi a URL de resposta, o id_token não pode ser usado porque não é específico o suficiente para identificar o cliente. Isso evita que o token seja emitido. No entanto, os tokens de acesso adquiridos por meio do fluxo de concessão implícita são resgatados por um cliente confidencial, mesmo se o cliente que inicia o processo tiver uma URL de resposta curinga registrada. Isso ocorre porque o cliente confidencial pode identificar o cliente que adquiriu o token de acesso. Em seguida, o cliente confidencial pode usar o token de acesso para adquirir um novo token de acesso para a API downstream.

Além disso, os aplicativos com chaves de assinatura personalizadas não podem ser usados como APIs de camada intermediária no fluxo OBO. Isso inclui os aplicativos empresariais configurados para logon único. Se a API de camada intermediária usar uma chave de assinatura personalizada, a API downstream não validará a assinatura do token de acesso que é transmitido para ela. Isso resulta em um erro, pois os tokens assinados com uma chave controlada pelo cliente não podem ser aceitos com segurança.

Diagrama do protocolo

Suponha que o usuário foi autenticado em um aplicativo usando o fluxo de concessão de código de autorização do OAuth 2.0 ou outro fluxo de início de sessão. Nesse ponto, o aplicativo tem um token de acesso para a API A (token A) com as declarações e o consentimento do usuário para acessar a API Web de camada intermediária (API A). Agora, a API A precisa fazer uma solicitação autenticada para a API Web downstream (API B).

As etapas a seguir constituem o fluxo OBO e são explicadas com a ajuda do diagrama a seguir.

1. O aplicativo cliente faz uma solicitação para API A com o token A (com uma declaração aud da API A).
2. A API A se autentica no ponto de extremidade de emissão de token da plataforma de identidade da Microsoft e solicita um token para acessar a API B.
3. O ponto de extremidade de emissão de token da plataforma de identidade da Microsoft valida as credenciais da API A com o token A e emite o token de acesso da API B (token B) para a API A.
4. O token B é definido pela API A no cabeçalho de autorização da solicitação para a API B.
5. Os dados do recurso protegido são retornados pela API B para a API A e, em seguida, para o cliente.

Nesse cenário, o serviço de camada intermediária não tem nenhuma interação do usuário para obter o consentimento do usuário para acessar a API downstream. Portanto, a opção de permitir acesso à API downstream é apresentada antecipadamente como parte da etapa de consentimento durante a autenticação. Para saber como implementar isso no seu aplicativo, confira Como obter consentimento para o aplicativo de camada intermediária.

Solicitação de token de acesso de camada intermediária

Para solicitar um token de acesso, use um HTTP POST para o ponto de extremidade do token da plataforma de identidade da Microsoft específico ao locatário com os parâmetros a seguir.

https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token

Há dois casos que dependem se o aplicativo cliente escolhe ser protegido por um segredo compartilhado ou por um certificado.

Primeiro caso: solicitação de token de acesso com um segredo compartilhado

Ao usar um segredo compartilhado, uma solicitação de token de acesso de serviço a serviço contém os seguintes parâmetros:

Exemplo

O seguinte HTTP POST solicita um token de acesso e um token de atualização com o escopo user.read para a API da Web https://graph.microsoft.com. A solicitação é assinada com o segredo do cliente e é feita por um cliente confidencial.

//line breaks for legibility only
    
POST /oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com/<tenant>
Content-Type: application/x-www-form-urlencoded
    
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&client_secret=sampleCredentia1s
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCJ9.eyJhdWQiOiIyO{a lot of characters here}
&scope=https://graph.microsoft.com/user.read+offline_access
&requested_token_use=on_behalf_of

Segundo caso: solicitação de token de acesso com um certificado

Uma solicitação de token de acesso serviço a serviço com um certificado contém os seguintes parâmetros, além dos parâmetros do exemplo anterior:

Observe que os parâmetros são praticamente os mesmos como no caso da solicitação pelo segredo compartilhado, exceto pelo fato de o parâmetro client_secret ser substituído por dois parâmetros: client_assertion_type e client_assertion. O parâmetro client_assertion_type é definido como urn:ietf:params:oauth:client-assertion-type:jwt-bearer, e o parâmetro client_assertion é definido como o token JWT assinado com a chave privada do certificado.

Exemplo

O seguinte HTTP POST solicita um token de acesso com o escopo user.read para a API da Web https://graph.microsoft.com com um certificado. A solicitação é assinada com o segredo do cliente e é feita por um cliente confidencial.

// line breaks for legibility only
    
POST /oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com/<tenant>
Content-Type: application/x-www-form-urlencoded
    
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&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}
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCIsImtpZCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCJ9.eyJhdWQiO{a lot of characters here}
&requested_token_use=on_behalf_of
&scope=https://graph.microsoft.com/user.read+offline_access

Resposta de token de acesso de camada intermediária

Uma resposta de êxito é uma resposta JSON OAuth 2.0 com os parâmetros a seguir.

Exemplo de resposta de êxito

O exemplo a seguir mostra uma resposta bem-sucedida a uma solicitação para um token de acesso para a API Web https://graph.microsoft.com. A resposta contém um token de acesso e um token de atualização e é assinada com a chave privada do certificado.

{
    "token_type": "Bearer",
    "scope": "https://graph.microsoft.com/user.read",
    "expires_in": 3269,
    "ext_expires_in": 0,
    "access_token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1tQTZOVGFlN0NkV1c3UWZkQ0NDYy0tY0hGa18wZE50MVEtc2loVzRMd2RwQVZISGpnTVdQZ0tQeVJIaGlDbUN2NkdyMEpmYmRfY1RmMUFxU21TcFJkVXVydVJqX3Nqd0JoN211eHlBQSIsImFsZyI6IlJTMjU2IiwieDV0IjoiejAzOXpkc0Z1aXpwQmZCVksxVG4yNVFIWU8wIiwia2lkIjoiejAzOXpkc0Z1aXpwQmZCVksxVG4yNVFIWU8wIn0.eyJhdWQiOiJodHRwczovL2dyYXBoLm1pY3Jvc29mdC5jb20iLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMWRiNDcvIiwiaWF0IjoxNDkzOTMwMzA1LCJuYmYiOjE0OTM5MzAzMDUsImV4cCI6MTQ5MzkzMzg3NSwiYWNyIjoiMCIsImFpbyI6IkFTUUEyLzhEQUFBQU9KYnFFWlRNTnEyZFcxYXpKN1RZMDlYeDdOT29EMkJEUlRWMXJ3b2ZRc1k9IiwiYW1yIjpbInB3ZCJdLCJhcHBfZGlzcGxheW5hbWUiOiJUb2RvRG90bmV0T2JvIiwiYXBwaWQiOiIyODQ2ZjcxYi1hN2E0LTQ5ODctYmFiMy03NjAwMzViMmYzODkiLCJhcHBpZGFjciI6IjEiLCJmYW1pbHlfbmFtZSI6IkNhbnVtYWxsYSIsImdpdmVuX25hbWUiOiJOYXZ5YSIsImlwYWRkciI6IjE2Ny4yMjAuMC4xOTkiLCJuYW1lIjoiTmF2eWEgQ2FudW1hbGxhIiwib2lkIjoiZDVlOTc5YzctM2QyZC00MmFmLThmMzAtNzI3ZGQ0YzJkMzgzIiwib25wcmVtX3NpZCI6IlMtMS01LTIxLTIxMjc1MjExODQtMTYwNDAxMjkyMC0xODg3OTI3NTI3LTI2MTE4NDg0IiwicGxhdGYiOiIxNCIsInB1aWQiOiIxMDAzM0ZGRkEwNkQxN0M5Iiwic2NwIjoiVXNlci5SZWFkIiwic3ViIjoibWtMMHBiLXlpMXQ1ckRGd2JTZ1JvTWxrZE52b3UzSjNWNm84UFE3alVCRSIsInRpZCI6IjcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0NyIsInVuaXF1ZV9uYW1lIjoibmFjYW51bWFAbWljcm9zb2Z0LmNvbSIsInVwbiI6Im5hY2FudW1hQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJWR1ItdmtEZlBFQ2M1dWFDaENRSkFBIiwidmVyIjoiMS4wIn0.cubh1L2VtruiiwF8ut1m9uNBmnUJeYx4x0G30F7CqSpzHj1Sv5DCgNZXyUz3pEiz77G8IfOF0_U5A_02k-xzwdYvtJUYGH3bFISzdqymiEGmdfCIRKl9KMeoo2llGv0ScCniIhr2U1yxTIkIpp092xcdaDt-2_2q_ql1Ha_HtjvTV1f9XR3t7_Id9bR5BqwVX5zPO7JMYDVhUZRx08eqZcC-F3wi0xd_5ND_mavMuxe2wrpF-EZviO3yg0QVRr59tE3AoWl8lSGpVc97vvRCnp4WVRk26jJhYXFPsdk4yWqOKZqzr3IFGyD08WizD_vPSrXcCPbZP3XWaoTUKZSNJg",
    "refresh_token": "OAQABAAAAAABnfiG-mA6NTae7CdWW7QfdAALzDWjw6qSn4GUDfxWzJDZ6lk9qRw4An{a lot of characters here}"
}

Esse token de acesso é um token formatado para v1.0 para o Microsoft Graph. Isso ocorre porque o formato do token é baseado no recurso que está sendo acessado e não está relacionado aos pontos de extremidade usados para solicitá-lo. O Microsoft Graph está configurado para aceitar tokens v1.0. Portanto, a plataforma de identidade da Microsoft produz tokens de acesso v1.0 quando um cliente solicita tokens para o Microsoft Graph. Outros aplicativos poderiam indicar que desejam tokens de formato para v2.0, v1.0 ou até mesmo formatos de token de propriedade ou criptografado. Os pontos de extremidade v1.0 e v2.0 podem emitir qualquer formato de token. Dessa forma, o recurso sempre poderá obter o formato correto do token, independentemente de como ou de onde o token é solicitado pelo cliente.

Exemplo de resposta de erro

Uma resposta de erro retornará pelo ponto de extremidade do token durante a tentativa de adquirir um token de acesso para a API downstream se essa API tiver uma política de acesso condicional (como a autenticação multifator) definida. O serviço de camada intermediária deve revelar esse erro para o aplicativo cliente de modo que este possa fornecer a interação do usuário para satisfazer a política de acesso condicional.

Para apresentar esse erro ao cliente, o serviço de camada intermediária responde com HTTP 401 Não autorizado e com um cabeçalho HTTP WWW-Authenticate contendo o erro e o desafio de declaração. O cliente deve analisar esse cabeçalho e adquirir um novo token do emissor do token apresentando o desafio de declarações se houver um. Os clientes não devem tentar acessar o serviço de camada intermediária novamente usando um token de acesso armazenado em cache.

{
    "error":"interaction_required",
    "error_description":"AADSTS50079: Due to a configuration change made by your administrator, or because you moved to a new location, you must enroll in multifactor authentication to access 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2017-05-01 22:43:20Z",
    "error_codes":[50079],
    "timestamp":"2017-05-01 22:43:20Z",
    "trace_id":"0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id":"aaaa0000-bb11-2222-33cc-444444dddddd",
    "claims":"{\"access_token\":{\"polids\":{\"essential\":true,\"values\":[\"00aa00aa-bb11-cc22-dd33-44ee44ee44ee\"]}}}"
}

Usar o token de acesso para acessar o recurso protegido

Agora, o serviço de camada intermediária pode usar o token adquirido anteriormente para fazer solicitações autenticadas para a API Web downstream definindo o token no cabeçalho Authorization.

Exemplo

    GET /v1.0/me HTTP/1.1
    Host: graph.microsoft.com
    Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw

Declarações SAML obtidas com um fluxo OBO do OAuth 2.0

Alguns serviços Web baseados em OAuth precisam acessar outras APIs de serviços Web que aceitam declarações SAML em fluxos não interativos. O Microsoft Entra ID pode fornecer uma declaração SAML em resposta a um fluxo On-Behalf-Of que usa um serviço Web baseado em SAML como recurso de destino.

Essa é uma extensão não padrão para o fluxo On-Behalf-Of do OAuth 2.0 que permite que um aplicativo baseado em OAuth2 acesse pontos de extremidade da API do serviço Web que consomem tokens SAML.

Obter um token SAML usando uma solicitação OBO com um segredo compartilhado

Uma solicitação de serviço a serviço para obter uma declaração SAML contém os seguintes parâmetros:

A resposta contém um token SAML codificado em Base 64url e UTF8.

• SubjectConfirmationData para uma declaração SAML é originado de uma chamada OBO: se o aplicativo de destino exigir um valor Recipient em SubjectConfirmationData, o valor deverá ser um URL de Resposta sem curinga na configuração do aplicativo de recurso. Como o URL de Resposta padrão não é usado para determinar o valor de Recipient, talvez seja necessário reordenar os URLs de Resposta na configuração do aplicativo para garantir que o primeiro URL de Resposta sem curinga seja usado. Para obter mais informações, confira URLs de resposta.
• O nó SubjectConfirmationData: o nó não pode conter um atributo InResponseTo, pois não faz parte de uma resposta SAML. O aplicativo que recebe o token SAML precisa ser capaz de aceitar a declaração SAML sem um atributo InResponseTo.
• Permissões de API: você precisa adicionar as permissões de API necessárias no aplicativo de camada intermediária para permitir o acesso ao aplicativo SAML, para que ele possa solicitar um token para o escopo /.default do aplicativo SAML.
• Consentimento: o consentimento deve ser concedido para receber um token SAML contendo dados de usuário em um fluxo OAuth. Para saber mais, confira Obter consentimento para o aplicativo de camada intermediária.

Resposta com declaração SAML

• token_type: Portador
• expires_in: 3296
• ext_expires_in: 0
• expires_on: 1529627844
• resource: https://api.contoso.com
• access_token: <Declaração SAML>
• issued_token_type: urn:ietf:params:oauth:token-type:saml2
• refresh_token: <Atualizar token>

Obter consentimento para o aplicativo de camada intermediária

A meta do fluxo OBO é garantir que o consentimento apropriado seja fornecido para que o aplicativo cliente possa chamar o aplicativo de camada intermediária e o aplicativo de camada intermediária tenha permissão para chamar o recurso de back-end. Dependendo da arquitetura ou do uso do aplicativo, considere o seguinte para garantir que o fluxo OBO seja bem-sucedido:

.default e consentimento combinado

O aplicativo de camada intermediária adiciona o cliente à lista de aplicativos cliente conhecidos (knownClientApplications) em seu manifesto. Se uma solicitação de consentimento for disparada pelo cliente, o fluxo de autorização será tanto para ele próprio quanto para o aplicativo de camada intermediária. Na plataforma de identidade da Microsoft, isso é feito usando o .default escopo. O escopo .default é um escopo especial usado para solicitar consentimento para acessar todos os escopos para os quais o aplicativo tem permissões. Isso é útil quando o aplicativo precisa acessar vários recursos, mas o usuário só deve ser solicitado o consentimento uma vez.

Ao disparar uma tela de consentimento usando aplicativos clientes conhecidos e .default, a tela de consentimento mostra as permissões para o cliente e a API de camada intermediária e também solicita todas as permissões necessárias para a API de camada intermediária. O usuário fornece o consentimento para ambos os aplicativos e, em seguida, o fluxo OBO funciona.

O serviço de recurso (API) identificado na solicitação deve ser a API para a qual o aplicativo cliente está solicitando um token de acesso como resultado da entrada do usuário. Por exemplo, scope=openid https://middle-tier-api.example.com/.default (para solicitar um token de acesso para a API de camada intermediária) ou scope=openid offline_access .default (quando um recurso não é identificado, ele usa o Microsoft Graph como padrão).

Independentemente da API identificada na solicitação de autorização, o prompt de consentimento é combinado com todas as permissões necessárias configuradas para o aplicativo cliente. Todas as permissões necessárias configuradas para cada API de camada intermediária indicada na lista de permissões necessárias do cliente, que identificaram o cliente como um aplicativo cliente conhecido, também são incluídas.

Aplicativos pré-autorizados

Os recursos podem indicar que um determinado aplicativo sempre terá permissão para receber determinados escopos. Isso é útil para estabelecer conexões entre um cliente de front-end e um recurso de back-end de maneira mais contínua. Um recurso pode declarar vários aplicativos pré-autorizados (preAuthorizedApplications) no manifesto. Um aplicativo desse tipo pode solicitar essas permissões em um fluxo OBO e recebê-las sem que o usuário forneça o consentimento.

Consentimento do administrador

Um administrador de locatários pode garantir que os aplicativos tenham permissão para chamar as APIs necessárias, fornecendo consentimento do administrador para o aplicativo de camada intermediária. Para fazer isso, o administrador pode localizar o aplicativo de camada intermediária em seu locatário, abrir a página de permissões necessárias e optar por dar permissão ao aplicativo. Para saber mais sobre o consentimento do administrador, confira a documentação de permissões e consentimento.

Uso de um único aplicativo

Em alguns cenários, você poderia ter apenas um emparelhamento único de cliente de camada intermediária e front-end. Nesse caso, talvez fosse mais fácil fazer isso em um único aplicativo, eliminando a necessidade de um aplicativo de camada intermediária completamente. Para fazer a autenticação entre o front-end e a API web, você pode usar cookies, um id_token ou um token de acesso solicitado para o aplicativo em si. Em seguida, solicite o consentimento desse aplicativo único para o recurso de back-end.

Confira também

Saiba mais sobre o protocolo OAuth 2.0 e outra maneira de executar autenticação de serviço para serviço usando as credenciais do cliente.

• Concessão de credenciais de cliente OAuth 2.0 na plataforma de identidade da Microsoft
• Fluxo de código do OAuth 2.0 na plataforma de identidade da Microsoft
• Como usar o escopo /.default