Compartilhar via

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 está operando 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 contra o protocolo em 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 protegidas. Consulte também os aplicativos de exemplo que usam 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 deve 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 que o cliente iniciador tenha 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 é passado para ele. Isso resulta em um erro porque os tokens assinados com uma chave controlada pelo cliente não podem ser aceitos com segurança.

Diagrama de protocolo

Suponha que o usuário autenticou um aplicativo usando o fluxo de concessão de código de autorização OAuth 2.0 ou outro fluxo de entrada. Neste 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 (API API) de camada intermediária. 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 OAuth2.0 On-Behalf-Of

  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 em seu aplicativo, consulte Obtendo 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 qualquer lugar, exceto o público-alvo pretendido para o token. Os tokens de acesso emitidos para a camada intermediária destinam-se a ser usados apenas por essa camada intermediária para se comunicarem com o ponto de extremidade de audiência pretendido.

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 A ID do aplicativo (cliente) que o Centro de administração do Microsoft Entra – página registros de aplicativo atribuiu 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. Também há suporte para o padrão de autenticação básica de fornecer credenciais no cabeçalho autorização, por RFC 6749 .
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 A ID do aplicativo (cliente) que o Centro de administração do Microsoft Entra – página registros de aplicativo atribuiu 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 criar e assinar usando o certificado que você registrou como credenciais para seu aplicativo. Para saber como registrar seu certificado e o formato da declaração, consulte as credenciais do 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 quase os mesmos que no caso da solicitação por segredo compartilhado, exceto que o client_secret parâmetro é substituído por dois parâmetros: a 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 obter mais informações sobre tokens de portador, consulte a Estrutura de Autorização do OAuth 2.0: Uso de 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 de token se baseia 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 podem indicar que desejam tokens de formato v2.0, tokens de formato v1.0 ou até mesmo formatos de token proprietários ou criptografados. Os pontos de extremidade v1.0 e v2.0 podem emitir qualquer formato de token. Dessa forma, o recurso sempre pode obter o formato certo do token, independentemente de como ou onde o token é solicitado pelo cliente.

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. Tokens para serviços da Microsoft podem usar um formato especial que não será validado como um JWT e também pode ser criptografado para usuários consumidores (conta da Microsoft). Embora a leitura de tokens seja uma ferramenta útil de depuração e aprendizado, não use dependências sobre isso em seu código ou assuma detalhes sobre tokens que não são para uma API que você controla.

Exemplo de resposta de erro

Uma resposta de erro é retornada pelo ponto de extremidade de token ao tentar adquirir um token de acesso para a API downstream, se a API downstream tiver uma política de Acesso Condicional (como autenticação multifator). 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 exibir esse erro de volta 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 novamente acessar o serviço de camada intermediária 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 Authorization cabeçalho.

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 deBehalf-Of OAuth 2.0 on-Behalf-Of 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
tipo_de_concessão Necessá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.
declaração Necessário O valor do token de acesso usado na solicitação.
ID do cliente Necessário A ID do aplicativo atribuída ao serviço de chamada durante o registro com o Microsoft Entra ID. Para localizar a ID do aplicativo no Centro de administração do Microsoft Entra, navegue atéos registros do aplicativo> e selecione o nome do aplicativo.
segredo_do_cliente Necessário A chave registrada para o serviço de chamada no Microsoft Entra ID. Esse valor deve ser observado no momento do registro. Também há suporte para o padrão de autenticação básica de fornecer credenciais no cabeçalho autorização, por RFC 6749 .
âmbito Necessá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 de escopo solicitado aqui determina o elemento resultante Audience no token SAML, o que pode ser importante para o aplicativo SAML que recebe o token.
uso_do_token_requerido Necessário Especifica como a solicitação deve ser processada. No fluxo em nome de, o valor deve ser on_behalf_of.
tipo_de_token_solicitado Necessá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 UTF8 e Base 64url.

  • SubjectConfirmationData para uma declaração SAML originada de uma chamada OBO: se o aplicativo de destino exigir um Recipient valor, SubjectConfirmationDatao valor deverá ser configurado como a primeira URL de Resposta nãowildcard na configuração do aplicativo de recurso. Como a URL de Resposta padrão não é usada para determinar o Recipient valor, talvez seja necessário reordenar as URLs de Resposta na configuração do aplicativo para garantir que a primeira URL de Resposta nãowildcard seja usada. Para obter mais informações, consulte URLs de resposta.
  • O nó SubjectConfirmationData: o nó não pode conter um InResponseTo atributo, 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 /.default escopo do aplicativo SAML.
  • Consentimento: o consentimento deve ser concedido para receber um token SAML contendo dados do usuário em um fluxo OAuth. Para obter informações, consulte Obter consentimento para o aplicativo de camada intermediária.

Resposta com declaração SAML

Parâmetro Descrição
tipo_de_token Indica o valor do tipo de token. O único tipo compatível com a ID do Microsoft Entra é o Portador. Para obter mais informações sobre tokens de portador, consulte OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750).
âmbito O escopo do acesso concedido no token.
expira_em O período de tempo pelo qual o token de acesso é válido (em segundos).
expira_em A hora em que o token de acesso expira. 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).
token_de_acesso O parâmetro que retorna a declaração SAML.
token de atualização 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
  • recurso: 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, você deve considerar 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 um prompt de consentimento for disparado pelo cliente, o fluxo de consentimento será tanto para si mesmo 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 cliente conhecidos e .default, a tela de consentimento mostra permissões para o cliente para 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 de qual API seja 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 listada na lista de permissões necessárias do cliente, que identificou o cliente como um aplicativo cliente conhecido, também estão incluídas.

Importante

Embora seja válido usar scope=openid https://resource/.default em fluxos de consentimento combinados envolvendo aplicativos cliente conhecidos, você não deve combinar .default com outros escopos delegados, como User.Read, Mail.Readprofileou User.ReadWrite.All na mesma solicitação. Isso resultará em AADSTS70011 erros porque .default representa permissões estáticas previamente consentidas, enquanto as outras exigem consentimento dinâmico do usuário no runtime.

offline_access às vezes é aceito para .default habilitar tokens de atualização, mas não deve ser combinado com quaisquer escopos delegados adicionais. Em caso de dúvida, divida as solicitações de token para evitar conflitos de tipo de escopo.

Aplicativos pré-autenticados

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é-autenticados (preAuthorizedApplications) em seu 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, consulte a documentação de consentimento e permissões.

Uso de um único aplicativo

Em alguns cenários, você só poderia ter um único emparelhamento de cliente de camada intermediária e front-end. Nesse cenário, você pode achar mais fácil tornar este um único aplicativo, negando 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.

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