Como usar APIs habilitadas para Avaliação Contínua de Acesso em seus aplicativos

A Avaliação Contínua de Acesso (CAE) é um recurso do Microsoft Entra que permite que os tokens de acesso sejam revogados com base em eventos críticos e avaliação de políticas, em vez de depender da expiração do token com base no tempo de vida. Para algumas APIs de recursos, como o risco e a política são avaliados em tempo real, isso pode aumentar a vida útil do token em até 28 horas. Esses tokens de longa duração são atualizados proativamente pela Biblioteca de Autenticação da Microsoft (MSAL), aumentando a resiliência de seus aplicativos.

Este artigo mostra como usar APIs habilitadas para CAE em seus aplicativos. As aplicações que não utilizem a MSAL podem adicionar suporte para desafios de afirmações, pedidos de afirmação e capacidades do cliente para utilização da CAE.

Considerações de implementação

Para usar o CAE, seu aplicativo e a API de recurso que ele está acessando devem estar habilitados para CAE. No entanto, preparar seu código para usar um recurso habilitado para CAE não impedirá que você use APIs que não estejam habilitadas para CAE.

Se uma API de recurso implementar CAE e seu aplicativo declarar que pode lidar com CAE, seu aplicativo receberá tokens CAE para esse recurso. Por esse motivo, se você declarar seu aplicativo CAE pronto, seu aplicativo deverá lidar com o desafio de declaração CAE para todas as APIs de recursos que aceitam tokens de acesso do Microsoft Identity. Se você não lidar com respostas CAE nessas chamadas de API, seu aplicativo pode acabar em um loop repetindo uma chamada de API com um token que ainda está na vida útil retornada do token, mas foi revogado devido ao CAE.

O código

A primeira etapa é adicionar código para manipular uma resposta da API de recurso rejeitando a chamada devido ao CAE. Com o CAE, as APIs retornarão um status 401 e um cabeçalho WWW-Authenticate quando o token de acesso for revogado ou a API detetar uma alteração no endereço IP usado. O cabeçalho WWW-Authenticate contém um Desafio de Declarações que o aplicativo pode usar para adquirir um novo token de acesso.

Por exemplo:

// Line breaks for legibility only

HTTP 401; Unauthorized

Bearer authorization_uri="https://login.windows.net/common/oauth2/authorize",
  error="insufficient_claims",
  claims="eyJhY2Nlc3NfdG9rZW4iOnsibmJmIjp7ImVzc2VudGlhbCI6dHJ1ZSwgInZhbHVlIjoiMTYwNDEwNjY1MSJ9fX0="

Seu aplicativo verificaria:

• a chamada de API retornando o status 401
• a existência de um cabeçalho WWW-Authenticate contendo:
  • um parâmetro "error" com o valor "insufficient_claims"
  • um parâmetro "claims"

.NET

Quando essas condições são atendidas, o aplicativo pode extrair e decodificar o desafio de declarações usando MSAL.NET WwwAuthenticateParameters classe.

if (APIresponse.IsSuccessStatusCode)
{
    // ...
}
else
{
    if (APIresponse.StatusCode == System.Net.HttpStatusCode.Unauthorized
        && APIresponse.Headers.WwwAuthenticate.Any())
    {
        string claimChallenge = WwwAuthenticateParameters.GetClaimChallengeFromResponseHeaders(APIresponse.Headers);

Seu aplicativo usaria o desafio de declarações para adquirir um novo token de acesso para o recurso.

try
{
    authResult = await _clientApp.AcquireTokenSilent(scopes, firstAccount)
        .WithClaims(claimChallenge)
        .ExecuteAsync()
        .ConfigureAwait(false);
}
catch (MsalUiRequiredException)
{
    try
    {
        authResult = await _clientApp.AcquireTokenInteractive(scopes)
            .WithClaims(claimChallenge)
            .WithAccount(firstAccount)
            .ExecuteAsync()
            .ConfigureAwait(false);
    }
    // ...

Quando seu aplicativo estiver pronto para lidar com o desafio de declaração retornado por um recurso habilitado para CAE, você poderá dizer ao Microsoft Identity que seu aplicativo está pronto para CAE. Para fazer isso em seu aplicativo MSAL, crie seu cliente público usando os recursos de cliente de "cp1".

_clientApp = PublicClientApplicationBuilder.Create(App.ClientId)
    .WithDefaultRedirectUri()
    .WithAuthority(authority)
    .WithClientCapabilities(new [] {"cp1"})
    .Build();

Você pode testar seu aplicativo entrando em um usuário no aplicativo e usando o portal do Azure para revogar as sessões do usuário. Da próxima vez que o aplicativo chamar a API habilitada para CAE, o usuário será solicitado a se autenticar novamente.

JavaScript

Quando essas condições são atendidas, o aplicativo pode extrair o desafio de declarações do cabeçalho de resposta da API da seguinte maneira:

try {
  const response = await fetch(apiEndpoint, options);

  if (response.status === 401 && response.headers.get('www-authenticate')) {
    const authenticateHeader = response.headers.get('www-authenticate');
    const claimsChallenge = parseChallenges(authenticateHeader).claims;
    
    // use the claims challenge to acquire a new access token...
  }
} catch(error) {
  // ...
}

// helper function to parse the www-authenticate header
function parseChallenges(header) {
    const schemeSeparator = header.indexOf(' ');
    const challenges = header.substring(schemeSeparator + 1).split(',');
    const challengeMap = {};

    challenges.forEach((challenge) => {
        const [key, value] = challenge.split('=');
        challengeMap[key.trim()] = window.decodeURI(value.replace(/['"]+/g, ''));
    });

    return challengeMap;
}

Seu aplicativo usaria o desafio de declarações para adquirir um novo token de acesso para o recurso.

const tokenRequest = {
    claims: window.atob(claimsChallenge), // decode the base64 string
    scopes: ['User.Read'],
    account: msalInstance.getActiveAccount()
};

let tokenResponse;

try {
    tokenResponse = await msalInstance.acquireTokenSilent(tokenRequest);
} catch (error) {
     if (error instanceof InteractionRequiredAuthError) {
        tokenResponse = await msalInstance.acquireTokenPopup(tokenRequest);
    }
}

Quando seu aplicativo estiver pronto para lidar com o desafio de declaração retornado por um recurso habilitado para CAE, você poderá dizer ao Microsoft Identity que seu aplicativo está pronto para CAE adicionando uma clientCapabilities propriedade na configuração MSAL.

const msalConfig = {
    auth: {
        clientId: 'Enter_the_Application_Id_Here', 
        clientCapabilities: ["CP1"]
        // remaining settings...
    }
}

const msalInstance = new PublicClientApplication(msalConfig);

Você pode testar seu aplicativo entrando em um usuário e, em seguida, usando o portal do Azure para revogar a sessão do usuário. Na próxima vez que o aplicativo chamar a API habilitada para CAE, o usuário será solicitado a se autenticar novamente.

Amostras de código

• Habilite seu aplicativo de página única Angular para entrar em usuários e chamar o Microsoft Graph
• Habilite seu aplicativo de página única React para entrar em usuários e chamar o Microsoft Graph
• Habilite seu aplicativo Web ASP.NET Core para entrar em usuários e chamar o Microsoft Graph

Próximos passos

• Visão geral conceitual da avaliação de acesso contínuo
• Desafios de afirmações, pedidos de afirmações e capacidades do cliente