Plataforma de identidade da Microsoft e fluxo OAuth 2.0 em nome de

  • Artigo

O fluxo on-behalf-of (OBO) descreve o cenário de uma API da Web usando uma identidade diferente da sua própria para chamar outra API da Web. Conhecida como delegação no OAuth, a intenção é passar a identidade e as permissões de um usuário pela 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 ao principal (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 para recursos aos quais não deveria ter acesso.

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. Consulte também os aplicativos de exemplo que usam o MSAL para obter exemplos.

Limitações do cliente

Se uma entidade de serviço solicitasse um token somente de aplicativo e o enviasse para uma API, essa API trocaria 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 de aplicativos de página única (SPAs), eles devem passar um token de acesso para um cliente confidencial de camada intermediária para executar fluxos OBO.

Se um cliente usa o fluxo implícito para obter um id_token e também tem curingas 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 o URL de resposta, o id_token não pode ser usado porque não é específico o suficiente para identificar o cliente. Isso impediria que o token fosse emitido. No entanto, os tokens de acesso adquiridos por meio do fluxo de concessão implícito 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. O cliente confidencial pode usar o token de acesso para adquirir um novo token de acesso para a API downstream.

Além disso, aplicativos com chaves de assinatura personalizadas não podem ser usados como APIs de camada intermediária no fluxo OBO. Isso inclui aplicativos corporativos 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 ela. 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 do usuário e consentimento para acessar a API da Web de camada intermediária (API A). Agora, a API A precisa fazer uma solicitação autenticada para a API da Web downstream (API B).

Os passos que se seguem constituem o fluxo OBO e são explicados com a ajuda do diagrama seguinte.

Mostra o fluxo OAuth2.0 On-Behalf-Of

  1. O aplicativo cliente faz uma solicitação à API A com o token A (com uma aud declaração de API A).
  2. A API A 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 junto 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 interação do usuário para obter o consentimento do usuário para acessar a API downstream. Portanto, a opção de conceder 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, faça um HTTP POST para o ponto de extremidade de token da plataforma de identidade Microsoft específico do locatário com os seguintes parâmetros.

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 do token. Os tokens de acesso emitidos para a camada intermediária destinam-se a ser usados apenas por essa camada intermediária para se comunicar com o ponto de extremidade do público-alvo.

Os riscos de segurança de retransmitir 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 intercetação de tokens em canais SSL/TLS comprometidos.
  • Incapacidade de satisfazer cenários de vinculação de token e Acesso Condicional que exijam aumento de declaração (por exemplo, MFA, Frequência de Entrada).
  • Incompatibilidade com políticas baseadas em dispositivos configuradas pelo administrador (por exemplo, MDM, políticas baseadas em localização).

Há dois casos, dependendo se o aplicativo cliente escolhe ser protegido por um segredo compartilhado ou 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 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 Necessário A ID do aplicativo (cliente) que a página Centro de administração do Microsoft Entra - Registros de aplicativos atribuiu ao seu aplicativo.
client_secret Necessário O segredo do cliente que você gerou para seu aplicativo na página Centro de administração do Microsoft Entra - Registros de aplicativos. O padrão de autenticação básica de fornecer credenciais no cabeçalho de autorização, de acordo com RFC 6749 , também é suportado.
assertion Necessário O token de acesso que foi enviado para a API de camada intermediária. Esse token deve ter uma reivindicação de audiência (aud) do aplicativo que faz essa solicitação OBO (o aplicativo indicado pelo client-id campo). Os aplicativos não podem resgatar um token para um aplicativo diferente (por exemplo, se um cliente envia a uma API um token destinado ao Microsoft Graph, a API não pode resgatá-lo usando OBO. Em vez disso, deve rejeitar o token).
scope Necessário Uma lista separada por espaço de escopos para a solicitação de token. Para obter mais informações, consulte escopos.
requested_token_use Necessário Especifica como a solicitação deve ser processada. No fluxo OBO, o valor deve ser definido como on_behalf_of.

Exemplo

O HTTP POST a seguir solicita um token de acesso e um token de atualização com user.read escopo para a API da https://graph.microsoft.com Web. O pedido é assinado com o segredo do cliente e é feito 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 Necessário A ID do aplicativo (cliente) que a página Centro de administração do Microsoft Entra - Registros de aplicativos atribuiu ao seu aplicativo.
client_assertion_type Necessário O valor deve ser urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion Necessário Uma asserção (um token da Web JSON) que você precisa criar e assinar com o certificado registrado como credenciais para seu aplicativo. Para saber como registrar seu certificado e o formato da declaração, consulte credenciais de certificado.
assertion Necessário O token de acesso que foi enviado para a API de camada intermediária. Esse token deve ter uma reivindicação de audiência (aud) do aplicativo que faz essa solicitação OBO (o aplicativo indicado pelo client-id campo). Os aplicativos não podem resgatar um token para um aplicativo diferente (por exemplo, se um cliente envia a uma API um token destinado ao MS Graph, a API não pode resgatá-lo usando OBO. Em vez disso, deve rejeitar o token).
requested_token_use Necessário Especifica como a solicitação deve ser processada. No fluxo OBO, o valor deve ser definido como on_behalf_of.
scope Necessário Uma lista separada por espaços de escopos 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 client_assertion_type parâmetro é definido como urn:ietf:params:oauth:client-assertion-type:jwt-bearer e o client_assertion parâmetro é definido como o token JWT que é assinado com a chave privada do certificado.

Exemplo

O HTTP POST a seguir solicita um token de acesso com user.read escopo para a https://graph.microsoft.com API da Web com um certificado. O pedido é assinado com o segredo do cliente e é feito 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 sucesso é uma resposta JSON OAuth 2.0 com os seguintes parâmetros.

Parâmetro Description
token_type Indica o valor do tipo de token. O único tipo suportado pela plataforma de identidade da Microsoft é Bearero . Para obter mais informações sobre tokens de portador, consulte o OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750).
scope O escopo do acesso concedido no token.
expires_in O período de tempo, em segundos, em que o token de acesso é válido.
access_token O token de acesso solicitado. O serviço de chamada pode usar esse token para autenticar o serviço de recebimento.
refresh_token O token de atualização para o token de acesso solicitado. O serviço de chamada pode usar esse token para solicitar outro token de acesso depois que o token de acesso atual expirar. O token de atualização só é fornecido se o offline_access escopo foi solicitado.

Exemplo de resposta bem-sucedida

O exemplo a seguir mostra uma resposta bem-sucedida a uma solicitação de um token de acesso para a https://graph.microsoft.com API da Web. 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}"
}

Este token de acesso é um token formatado em v1.0 para o Microsoft Graph. Isso ocorre porque o formato de 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 podem indicar que querem tokens no formato v2.0, tokens no 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. Desta forma, o recurso pode sempre obter o formato certo de 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. Os tokens para 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 consumidores (conta da Microsoft). Embora a leitura de tokens seja uma ferramenta útil de depuração e aprendizagem, não dependa disso em seu código ou assuma especificidades 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 do 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) definida. O serviço de camada intermediária deve exibir esse erro ao aplicativo cliente para que o aplicativo cliente 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 existir. Os clientes não devem tentar acessar novamente o serviço de camada intermediária usando um token de acesso 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\"]}}}"
}

Use o token de acesso para acessar o recurso seguro

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

Exemplo

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

Asserções SAML obtidas com um fluxo OAuth2.0 OBO

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

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

Gorjeta

Ao chamar um serviço Web protegido por SAML a partir de um aplicativo Web front-end, você pode simplesmente chamar a API e iniciar um fluxo de autenticação interativo 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 requer um token SAML para fornecer 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 uma asserção SAML contém os seguintes parâmetros:

Parâmetro Tipo Description
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 O ID do aplicativo atribuído 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é Registros do aplicativo Identity>Applications>e selecione o nome do aplicativo.
client_secret obrigatório A chave registrada para o serviço de chamada no Microsoft Entra ID. Este valor deve ser anotado no momento da inscrição. O padrão de autenticação básica de fornecer credenciais no cabeçalho de autorização, de acordo com RFC 6749 , também é suportado.
âmbito obrigatório Uma lista separada por espaços de escopos 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 deve ser sempre o ID de entidade SAML com /.default anexado. Por exemplo, caso o ID de 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 , o Microsoft Entra prefixa a ID da Entidade com spn:. Nesse caso, você deve solicitar o escopo spn:<EntityID>/.default, por exemplo spn:testapp/.default , no caso de o ID da entidade ser testapp. O valor de escopo solicitado aqui determina o elemento resultante Audience no token SAML, que pode ser importante para o aplicativo SAML que recebe o token.
requested_token_use obrigatório Especifica como a solicitação deve ser processada. No fluxo On-Behalf-Of, 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 UTF8 e Base 64url.

  • SubjectConfirmationData para uma asserção SAML originada de uma chamada OBO: Se o aplicativo de destino exigir um Recipient valor no SubjectConfirmationData, o valor deverá ser configurado como a primeira URL de resposta não curinga 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ão curinga 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 deve ser capaz de aceitar a asserção SAML sem um InResponseTo atributo.
  • 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 Obtendo consentimento para o aplicativo de camada intermediária.

Resposta com asserção SAML

Parâmetro Description
token_type Indica o valor do tipo de token. O único tipo que o Microsoft Entra ID suporta é Bearer. 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.
expires_in O período de tempo em que o token de acesso é válido (em segundos).
expires_on 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é o tempo de expiração. Esse valor é usado para determinar o tempo de vida dos tokens armazenados em cache.
recurso O URI do ID do aplicativo do serviço de recebimento (recurso seguro).
access_token O parâmetro que retorna a asserção SAML.
refresh_token O token de atualização. O serviço de chamada pode usar esse token para solicitar outro token de acesso depois que a asserção SAML atual expirar.
  • token_type: Portador
  • expires_in: 3296
  • ext_expires_in: 0
  • expires_on: 1529627844
  • Recurso: https://api.contoso.com
  • access_token: <Asserção SAML>
  • issued_token_type: urn:ietf:params:oauth:token-type:saml2
  • refresh_token: <Atualizar token>

O objetivo do fluxo OBO é garantir que o consentimento adequado seja dado 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 seu 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 conhecida (knownClientApplications) em seu manifesto. Se um prompt de consentimento for acionado pelo cliente, o fluxo de consentimento será para si mesmo e para o aplicativo de camada intermediária. Na plataforma de identidade da Microsoft, isso é feito usando o .default escopo. O .default escopo é um escopo especial que é 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 a fornecer consentimento uma vez.

Ao acionar 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 quaisquer permissões exigidas pela API de camada intermediária. O usuário fornece 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 assume como padrão o Microsoft Graph).

Independentemente de qual 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 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.

Aplicações pré-autorizadas

Os recursos podem indicar que um determinado aplicativo sempre tem permissão para receber determinados escopos. Isso é útil para tornar as conexões entre um cliente front-end e um recurso back-end mais perfeitas. Um recurso pode declarar vários aplicativos pré-autorizados (preAuthorizedApplications) em seu manifesto. Qualquer aplicativo desse tipo pode solicitar essas permissões em um fluxo OBO e recebê-las sem o consentimento do usuário.

Um administrador de locatário pode garantir que os aplicativos tenham permissão para chamar suas APIs necessárias fornecendo consentimento de administrador para o aplicativo de camada intermediária. Para fazer isso, o administrador pode encontrar 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 para o aplicativo. Para saber mais sobre o consentimento do administrador, consulte a documentação de consentimento e permissões.

Utilização de uma única aplicação

Em alguns cenários, você só poderia ter um único emparelhamento de cliente intermediário e front-end. Nesse cenário, você pode achar mais fácil tornar esse um único aplicativo, negando completamente a necessidade de um aplicativo de camada intermediária. Para autenticar entre o front-end e a API da Web, você pode usar cookies, um id_token ou um token de acesso solicitado para o próprio aplicativo. 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 a autenticação de serviço usando credenciais de cliente.