Como usar APIs habilitadas para a Avaliação contínua de acesso em seus aplicativos

A CAE (Avaliação Contínua de Acesso) é um recurso do Microsoft Entra que permite que os tokens de acesso sejam revogados com base em eventos críticos e na avaliação da política, 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 o tempo de vida do token em até 28 horas. Esses tokens de vida prolongada serão atualizados de maneira proativa pela MSAL (Biblioteca de Autenticação da Microsoft), aumentando a resiliência dos aplicativos.

Este artigo mostra como usar APIs habilitadas para CAE em seus aplicativos. Os aplicativos que não usam a MSAL podem adicionar suporte para desafios de declarações, solicitações de declarações e recursos do cliente para usar a CAE.

Considerações sobre a implementação

Para usar a CAE, o aplicativo e a API do recurso que ele acessa precisam estar habilitados para CAE. No entanto, a preparação do código para usar um recurso habilitado para CAE não impedirá o uso de APIs que não sejam habilitadas para CAE.

Se uma API de recurso implementar a CAE e o aplicativo declarar que pode manipular a CAE, o aplicativo obterá tokens da CAE para esse recurso. Por esse motivo, se você declarar a CAE do seu aplicativo pronta, seu aplicativo precisará lidar com o desafio de declaração de CAE para todas as APIs de recurso que aceitam tokens de acesso de identidade da Microsoft. Se você não tratar as respostas da CAE nessas chamadas à API, o aplicativo poderá terminar em um loop que repete uma chamada à API com um token que ainda está no ciclo de vida retornado do token, mas que foi revogado devido à CAE.

O código

A primeira etapa é adicionar código para manipular uma resposta da API de recurso que rejeita a chamada devido à CAE. Com a CAE, as APIs retornarão um status 401 e um cabeçalho WWW-Authenticate quando o token de acesso tiver sido revogado ou a API detectar 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 à API retornando o status 401
• a existência de um cabeçalho WWW-Authenticate que contém:
  • 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 a classe WwwAuthenticateParameters do MSAL.NET.

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

Em seguida, 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 à Identidade da Microsoft que seu aplicativo está pronto para a CAE. Para fazer isso no seu aplicativo MSAL, crie seu cliente público usando os recursos de cliente do "cp1".

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

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

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;
}

Em seguida, 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 à Identidade da Microsoft que seu aplicativo está pronto para a CAE adicionando uma propriedade clientCapabilities 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 conectando um usuário no aplicativo e usando o portal do Azure para revogar as sessões do usuário. Na próxima vez que o aplicativo chamar a API habilitada para CAE, o usuário deverá se autenticar.

Exemplos de código

• Habilitar o aplicativo de página única Angular para conectar usuários e chamar o Microsoft Graph
• Habilitar o aplicativo de página única React para conectar usuários e chamar o Microsoft Graph
• Habilitar o aplicativo Web ASP.NET Core para conectar usuários e chamar o Microsoft Graph

Próximas etapas

• Visão geral conceitual da avaliação de acesso contínuo
• Desafios de declarações, solicitações de declarações e funcionalidades do cliente