Diretrizes para desenvolvedores relativas ao Acesso Condicional ao Microsoft Entra

  • Artigo

O recurso Acesso Condicional no Microsoft Entra ID oferece uma das várias maneiras com as quais você pode tornar seu aplicativo seguro e proteger um serviço. O acesso condicional permite que desenvolvedores e clientes corporativos protejam serviços de diversas maneiras, incluindo:

  • Autenticação multifator
  • Permissão para que somente dispositivos inscritos no Intune acessem serviços específicos
  • Restrição de locais de usuário e intervalos de IP

Para saber mais sobre os recursos completos do Acesso Condicional, confira o artigo O que é o Acesso Condicional.

Se você for um desenvolvedor que cria aplicativos para o Microsoft Entra ID, esse artigo mostra como você pode usar o Acesso Condicional. Você também aprenderá sobre o impacto resultante de acessar recursos que você não controla e que podem ter políticas de Acesso Condicional aplicadas. Este artigo também explora as implicações do Acesso Condicional no fluxo On-Behalf-Of, nos aplicativos Web, no acesso ao Microsoft Graph e nas chamadas a APIs.

O conhecimento de aplicativos de único locatário e multilocatário, além de padrões comuns de autenticação é pressuposto.

Observação

O uso desse recurso requer uma licença de P1 do Microsoft Entra ID. Para localizar a licença correta para os requisitos, consulte Comparar recursos geralmente disponíveis nas edições Gratuita, Básica e Premium. Os clientes com licenças do Microsoft 365 Business também têm acesso a recursos de Acesso Condicional.

Como o Acesso Condicional afeta um aplicativo?

Tipos de aplicativo afetados

Na maioria dos casos comuns, o acesso condicional não altera o comportamento do aplicativo nem exige alterações do desenvolvedor. Somente em determinados casos, quando um aplicativo solicita de modo indireto ou silencioso um token para executar um serviço, um aplicativo exige alterações de código para lidar com os desafios do Acesso Condicional. O que pode ser tão simples quanto executar uma solicitação de entrada interativa.

Os seguintes cenários exigem obter o código de modo específico para lidar com os desafios do Acesso Condicional:

  • Aplicativos executando o fluxo em nome de
  • Aplicativos acessando vários serviços/recursos
  • Aplicativos de página única que usam MSAL.js
  • Aplicativos Web chamando um recurso

As políticas de Acesso Condicional podem ser aplicadas ao aplicativo, mas também podem ser aplicadas a uma API Web acessada pelo seu aplicativo. Para saber mais sobre como configurar uma política de Acesso Condicional, confira Guia de Início Rápido: requerer MFA para aplicativos específicos com o Acesso Condicional do Microsoft Entra.

Dependendo do cenário, um cliente empresarial pode aplicar e remover políticas de Acesso Condicional a qualquer momento. Implemente o tratamento de desafio para que seu aplicativo continue funcionando quando uma nova política for aplicada. Os exemplos a seguir ilustram o tratamento de desafio.

Exemplos de Acesso Condicional

Alguns cenários exigem alterações de código para tratar do Acesso Condicional, enquanto outros funcionam como estão. Veja alguns cenários de uso do acesso condicional para fazer a autenticação multifator, que mostram algumas informações sobre a diferença.

  • Você está criando um aplicativo iOS de único locatário e aplica uma política de acesso condicional. O aplicativo conecta um usuário e não solicita acesso a uma API. Quando o usuário entra, a política é invocada automaticamente e o usuário precisa realizar a MFA (autenticação multifator).
  • Você está criando um aplicativo nativo que usa um serviço de camada intermediária para acessar a API downstream. Um cliente empresarial na empresa usando esse aplicativo aplica uma política à API downstream. Quando um usuário final se conecta, o aplicativo nativo solicita acesso à camada intermediária e envia o token. A camada intermediária executa o fluxo “em nome de” para solicitar acesso à API downstream. Nesse momento, um "desafio" claims é apresentado à camada intermediária. A camada intermediária envia o desafio de volta ao aplicativo nativo, que precisa estar em conformidade com a política de acesso condicional.

Microsoft Graph

O Microsoft Graph tem considerações especiais ao criar aplicativos em ambientes de Acesso Condicional. Em geral, a mecânica do Acesso Condicional se comporta da mesma forma, mas as políticas que os usuários veem serão baseadas nos dados subjacentes que seu aplicativo está solicitando do grafo.

Especificamente, todos os escopos do Microsoft Graph representam algum conjunto de dados que pode ter políticas aplicadas somente a ele. Como as políticas de acesso condicional são atribuídas a conjuntos de dados específicos, o Microsoft Entra ID aplica as políticas de acesso condicional com base nos dados por trás do Graph, e não no Graph em si.

Por exemplo, se um aplicativo solicitar os seguintes escopos do Microsoft Graph,

scopes="ChannelMessages.Read.All Mail.Read"

Um aplicativo pode esperar que os usuários atendam a todas as políticas definidas no Teams e no Exchange. Alguns escopos poderão ser mapeados para vários conjuntos de dados se concederem acesso.

Estabelecendo conformidade com uma política de acesso condicional

Para várias topologias diferentes de aplicativo, uma política de acesso condicional é avaliada quando a sessão é estabelecida. Como uma política de acesso condicional funciona na granularidade de aplicativos e serviços, o ponto em que ela é invocada depende totalmente do cenário que você está tentando executar.

Quando o aplicativo tenta acessar um serviço com uma política de acesso condicional, ele pode encontrar um desafio de Acesso Condicional. Esse desafio é codificado no parâmetro claims que é apresentado em uma resposta do Microsoft Entra ID. Veja um exemplo desse parâmetro de desafio:

claims={"access_token":{"polids":{"essential":true,"Values":["<GUID>"]}}}

Os desenvolvedores podem pegar esse desafio e anexá-lo a uma nova solicitação no Microsoft Entra ID. Para passar por esse estado, o usuário final é solicitado a executar qualquer ação necessária para cumprir a política de acesso condicional. Nos cenários a seguir, são explicadas as especificações do erro e como extrair o parâmetro.

Cenários

Pré-requisitos

O Acesso Condicional do Microsoft Entra é um recurso incluído nas licenças P1 ou P2 do Microsoft Entra ID. Os clientes com licenças do Microsoft 365 Business também têm acesso a recursos de Acesso Condicional.

Considerações para cenários específicos

As seguintes informações se aplicam apenas nestes cenários de Acesso Condicional:

  • Aplicativos executando o fluxo em nome de
  • Aplicativos acessando vários serviços/recursos
  • Aplicativos de página única que usam MSAL.js

As seções a seguir discutem cenários comuns que são mais complexos. O princípio operacional básico é que as políticas de acesso condicional são avaliadas no momento em que o token é solicitado para o serviço que tem uma política de acesso condicional aplicada.

Cenário: aplicativo executando o fluxo "em nome de"

Nesse cenário, vamos acompanhar o caso em que um aplicativo nativo chama um serviço/API Web. Por sua vez, esse serviço faz o fluxo On-Behalf-Of chamar um serviço downstream. Em nosso caso, aplicamos a política de acesso condicional ao serviço downstream (API Web 2) e estamos usando um aplicativo nativo em vez um aplicativo de servidor/daemon.

App performing the on-behalf-of flow diagram

A solicitação de token inicial para a API Web 1 não solicita ao usuário final a autenticação multifator, pois a API Web 1 nem sempre pode acessar a API downstream. Depois que a API Web 1 tenta solicitar um token em nome do usuário para a API Web 2, a solicitação falha, uma vez que o usuário não se conectou com a autenticação multifator.

O Microsoft Entra ID retorna uma resposta HTTP com alguns dados interessantes:

Observação

Nessa instância, trata-se de uma descrição do erro da autenticação multifator, mas há uma ampla variedade de interaction_required possíveis relacionados ao Acesso Condicional.

HTTP 400; Bad Request
error=interaction_required
error_description=AADSTS50076: Due to a configuration change made by your administrator, or because you moved to a new location, you must use multi-factor authentication to access '<Web API 2 App/Client ID>'.
claims={"access_token":{"polids":{"essential":true,"Values":["<GUID>"]}}}

Na API Web 1, capturamos o erro error=interaction_required e enviamos de volta o desafio claims ao aplicativo da área de trabalho. Nesse ponto, o aplicativo da área de trabalho pode fazer uma nova chamada acquireToken() e acrescentar o desafio claims como um parâmetro extra de cadeia de consulta. Essa nova solicitação requer que o usuário faça a autenticação multifator e envie esse novo token de volta à API Web 1 e complete o fluxo on-behalf-of.

Para testar esse cenário, veja nosso exemplo de código .NET. Ele demonstra como passar o desafio claims de volta da API Web 1 para o aplicativo nativo e construir uma nova solicitação dentro do aplicativo cliente.

Cenário: aplicativo acessando vários serviços

Nesse cenário, vamos acompanhar o caso em que um aplicativo Web acessa dois serviços e um deles tem uma política de acesso condicional atribuída. Dependendo da lógica do seu aplicativo, pode existir um caminho no qual seu aplicativo não exige acesso a ambos os serviços Web. Nesse cenário, a ordem na qual você solicita um token tem um papel importante na experiência do usuário final.

Imagine que você tem o serviço Web A e B. O serviço Web B tem a política de acesso condicional aplicada. Enquanto a solicitação de autenticação interativa inicial exige consentimento para ambos os serviços, a política de acesso condicional não é exigida em todos os casos. Se o aplicativo solicitar um token para o serviço Web B, a política será invocada e as solicitações subsequentes para o serviço Web A também serão bem-sucedidas, como se segue.

App accessing multiple-services flow diagram

Como alternativa, se o aplicativo inicialmente solicitar um token para o serviço Web A, o usuário final não invocará a política de acesso condicional. Isso permite que o desenvolvedor do aplicativo controle a experiência do usuário final e não force a política de acesso condicional a ser invocada em todos os casos. A complicação é se o aplicativo solicitar depois um token para o serviço Web B. Nesse momento, o usuário final precisará cumprir a política de acesso condicional. Quando o aplicativo tenta acquireToken, ele pode gerar o seguinte erro (ilustrado no diagrama a seguir):

HTTP 400; Bad Request
error=interaction_required
error_description=AADSTS50076: Due to a configuration change made by your administrator, or because you moved to a new location, you must use multi-factor authentication to access '<Web API App/Client ID>'.
claims={"access_token":{"polids":{"essential":true,"Values":["<GUID>"]}}}

App accessing multiple services requesting a new token

Se o aplicativo estiver usando a biblioteca MSAL, uma falha ao adquirir o token será sempre repetida interativamente. Quando essa solicitação interativa ocorre, o usuário final tem a oportunidade de cumprir o Acesso Condicional. Isso não se aplica quando a solicitação é AcquireTokenSilentAsync ou PromptBehavior.Never, caso em que o aplicativo precisa executar uma solicitação AcquireToken interativa para dar ao usuário final a oportunidade de cumprir a política.

Cenário: SPA (aplicativo de página única) que usa MSAL.js

Nesse tipo de cenário, vamos demonstrar um caso em que temos um SPA (aplicativo de página única) usando MSAL.js para executar uma chamada à API Web protegida pelo Acesso Condicional. É uma arquitetura simples, mas tem alguns detalhes que precisam ser considerados no desenvolvimento do Acesso Condicional.

Em MSAL.js, há funções que obtêm estes tokens: acquireTokenSilent(), acquireTokenPopup() e acquireTokenRedirect().

  • O acquireTokenSilent() pode ser usado para obter um token de acesso de modo silencioso. Isso significa que ele não mostrará a interface do usuário em nenhuma circunstância.
  • acquireTokenPopup()e acquireTokenRedirect() são usadas para solicitar interativamente um token para um recurso, o que significa que elas sempre mostram a interface do usuário de entrada.

Quando um aplicativo precisa de um token de acesso para chamar uma API Web, ele tenta um acquireTokenSilent(). Caso o token tenha expirado ou seja preciso cumprir uma política de Acesso Condicional, haverá falha na função acquireToken e o aplicativo usará acquireTokenPopup() ou acquireTokenRedirect().

Single-page app using MSAL flow diagram

Veja um exemplo com nosso cenário de Acesso Condicional. O usuário final apenas aterrissou no site e não tem uma sessão. Realizamos uma chamada loginPopup(), obtemos um token de ID sem autenticação multifator. Em seguida, o usuário pressiona um botão que requer que o aplicativo solicite dados de uma API Web. O aplicativo tenta fazer uma chamada acquireTokenSilent(), mas falha porque o usuário ainda não executou a autenticação multifator e precisa cumprir a política de acesso condicional.

O Microsoft Entra ID envia de volta a seguinte resposta HTTP:

HTTP 400; Bad Request
error=interaction_required
error_description=AADSTS50076: Due to a configuration change made by your administrator, or because you moved to a new location, you must use multi-factor authentication to access '<Web API App/Client ID>'.

Nosso aplicativo precisa capturar error=interaction_required. O aplicativo pode usar acquireTokenPopup() ou acquireTokenRedirect() no mesmo recurso. O usuário é forçado a fazer uma autenticação multifator. Depois que o usuário conclui a autenticação multifator, o aplicativo recebe um novo token de acesso para o recurso solicitado.

Para testar esse tipo de cenário, confira a nossa amostra de código de SPA do React com uma chamada à API web do Node.js usando um fluxo on-behalf-of. Essa amostra de código usa a política de Acesso Condicional e a API web que você registrou anteriormente com um SPA do React para demonstrar esse cenário. Ele mostra como tratar corretamente o desafio de declaração e obter um token de acesso que pode ser usado na API Web.

Confira também