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

  • Artigo

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.

Mostra o fluxo On-Behalf-Of do OAuth 2.0

  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

Aviso

NÃO envie tokens de acesso que foram emitidos para a camada intermediária para nenhum lugar, exceto o destinatário pretendido do token. Os tokens de acesso emitidos para a camada intermediária destinam-se a uso somente por essa camada intermediária para comunicação com o ponto de extremidade destinatário.

Os riscos de segurança da retransmissão de tokens de acesso de um recurso de camada intermediária para um cliente (em vez de o cliente obter os tokens de acesso por conta própria) incluem:

  • Aumento do risco de interceptação de token em canais SSL/TLS comprometidos.
  • Incapacidade de atender a cenários de associação de token e de acesso condicional que exigem step-up de declaração (por exemplo, MFA, Frequência de Conexão).
  • Incompatibilidade com políticas baseadas em dispositivo configuradas pelo administrador (por exemplo, MDM e políticas baseadas em localização).

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:

Parâmetro Tipo Descrição
grant_type Obrigatório O tipo de solicitação de token. Para uma solicitação usando um JWT, o valor deve ser urn:ietf:params:oauth:grant-type:jwt-bearer.
client_id Obrigatório O ID do aplicativo (cliente) que a página do centro de administração do Microsoft Entra – Registros de aplicativo atribui ao seu aplicativo.
client_secret Obrigatório O segredo do cliente que você gerou para o aplicativo na página do centro de administração do Microsoft Entra – Registros de aplicativo. O padrão de autenticação básico de fornecer credenciais no cabeçalho de autorização, conforme a RFC 6749, também tem suporte.
assertion Obrigatório O token de acesso enviado para a API de camada intermediária. Esse token precisa que uma declaração (aud) do público-alvo do aplicativo faça essa solicitação OBO (o aplicativo indicado pelo campo client-id). Os aplicativos não podem resgatar um token para um aplicativo diferente (por exemplo, se um cliente enviar a uma API um token destinado ao Microsoft Graph, a API não poderá resgatá-lo usando o OBO. Ela deverá rejeitar o token).
scope Obrigatório Lista de escopos separados por espaço para a solicitação de token. Para obter mais informações, consulte escopos.
requested_token_use Obrigatório Especifica como a solicitação deve ser processada. No fluxo OBO, o valor precisa ser definido como on_behalf_of.

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:

Parâmetro Tipo Descrição
grant_type Obrigatório O tipo da solicitação de token. Para uma solicitação usando um JWT, o valor deve ser urn:ietf:params:oauth:grant-type:jwt-bearer.
client_id Obrigatório O ID do aplicativo (cliente) que a página do centro de administração do Microsoft Entra – Registros de aplicativo atribui ao seu aplicativo.
client_assertion_type Obrigatório O valor deve ser urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion Obrigatório Uma asserção (um token Web JSON) que você precisa para criar e assinar com o certificado registrado como credenciais do seu aplicativo. Para saber mais sobre como registrar seu certificado e o formato da asserção, confira credenciais de certificado.
assertion Obrigatório O token de acesso enviado para a API de camada intermediária. Esse token precisa que uma declaração (aud) do público-alvo do aplicativo faça essa solicitação OBO (o aplicativo indicado pelo campo client-id). Os aplicativos não podem resgatar um token para um aplicativo diferente (por exemplo, se um cliente enviar a uma API um token destinado ao MS Graph, a API não poderá resgatá-lo usando o OBO. Ela deverá rejeitar o token).
requested_token_use Obrigatório Especifica como a solicitação deve ser processada. No fluxo OBO, o valor precisa ser definido como on_behalf_of.
scope Obrigatório Lista de escopos separados por espaço para a solicitação de token. Para obter mais informações, consulte escopos.

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.

Parâmetro Descrição
token_type Indica o valor do tipo de token. O único tipo compatível com a plataforma de identidade da Microsoft é Bearer. Para saber mais sobre os tokens de portador, confira o artigo Estrutura de Autorização do OAuth 2.0: Uso do Token de Portador (RFC 6750).
scope O escopo do acesso concedido no token.
expires_in O tempo, em segundos, pelo qual o token de acesso é válido.
access_token O token de acesso solicitado. O serviço de chamada pode usar esse token para se autenticar no serviço de recebimento.
refresh_token O token de atualização para o token de acesso solicitado. O serviço de chamada poderá usar esse token para solicitar outro token de acesso depois que o token de acesso atual expirar. O token de atualização é fornecido apenas se o offline_access escopo foi solicitado.

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.

Aviso

Não tente validar nem ler tokens de APIs que não sejam suas em seu código, incluindo os tokens deste exemplo. Os tokens de 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 do consumidor (conta Microsoft). Embora a leitura de tokens seja uma ferramenta útil de depuração e aprendizagem, não assuma dependências disso em seu código ou assuma informações específicas sobre tokens que não são de uma API que você controla.

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\":[\"9ab03e19-ed42-4168-b6b7-7001fb3e933a\"]}}}"
}

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.

Dica

Quando chama um serviço Web protegido por SAML de um aplicativo Web de front-end, você pode simplesmente chamar a API e iniciar um fluxo de autenticação interativa normal, com a sessão existente do usuário. Você só precisa usar um fluxo OBO quando uma chamada de serviço a serviço exigir um token SAML para fornecer o contexto de usuário.

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:

Parâmetro Tipo Descrição
grant_type obrigatório O tipo da solicitação de token. Para uma solicitação que usa um JWT, o valor deve ser urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion obrigatório O valor do token de acesso usado na solicitação.
client_id obrigatório A ID do aplicativo atribuída ao serviço de chamada durante o registro com o Microsoft Entra ID. Para encontrar a ID do aplicativo no centro de administração do Microsoft Entra, navegue até Identidade>Aplicativos>Registros de aplicativo e selecione o nome do aplicativo.
client_secret obrigatório A chave registrada para o serviço de chamada no Microsoft Entra ID. Esse valor deve ter sido anotado no momento do registro. O padrão de autenticação básico de fornecer credenciais no cabeçalho de autorização, conforme a RFC 6749, também tem suporte.
scope obrigatório Lista de escopos separados por espaço para a solicitação de token. Para obter mais informações, consulte escopos. O SAML em si não tem um conceito de escopos, mas é usado para identificar o aplicativo SAML de destino para o qual você deseja receber um token. Para esse fluxo OBO, o valor do escopo sempre deve ser a ID da Entidade SAML com /.default anexado. Por exemplo, caso a ID da Entidade do aplicativo SAML seja https://testapp.contoso.com, o escopo solicitado deve ser https://testapp.contoso.com/.default. Caso a ID da Entidade não comece com um esquema de URI como https:, o Microsoft Entra prefixa a ID da Entidade com spn:. Nesse caso, solicite o escopo spn:<EntityID>/.default, por exemplo spn:testapp/.default, caso a ID da Entidade seja testapp. O valor do escopo solicitado aqui determina o elemento Audience resultante no token SAML, que poderia ser importante para o aplicativo SAML que está recebendo o token.
requested_token_use necessárias Especifica como a solicitação deve ser processada. No fluxo em nome de, o valor deve ser on_behalf_of.
requested_token_type obrigatório Especifica o tipo de token solicitado. O valor pode ser urn:ietf:params:oauth:token-type:saml2 ou urn:ietf:params:oauth:token-type:saml1, dependendo dos requisitos do recurso acessado.

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

Parâmetro Descrição
token_type Indica o valor do tipo de token. O único tipo compatível com o Microsoft Entra ID é Portador. Para saber mais sobre os tokens de portador, confira Estrutura de Autorização do OAuth 2.0: Uso do Token de Portador (RFC 6750).
scope O escopo do acesso concedido no token.
expires_in O período de tempo pelo qual o token de acesso é válido (em segundos).
expires_on A hora de expiração do token de acesso. A data é representada como o número de segundos de 1970-01-01T0:0:0Z UTC até a hora de expiração. Esse valor é usado para determinar o tempo de vida de tokens em cache.
recurso O URI da ID do aplicativo do serviço de recebimento (recurso protegido).
access_token O parâmetro que retorna a declaração SAML.
refresh_token O token de atualização. O serviço de chamada poderá usar esse token para solicitar outro token de acesso depois que a declaração SAML atual expirar.
  • 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>

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:

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.

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.