Come usare le API abilitate per la valutazione dell'accesso continuo nelle applicazioni

La valutazione dell'accesso continuo (CAE) è una funzionalità di Microsoft Entra che consente di revocare i token di accesso in base a eventi critici e valutazione dei criteri anziché basarsi sulla scadenza del token in base alla durata. Per alcune API delle risorse, poiché i rischi e i criteri vengono valutati in tempo reale, questo può aumentare la durata dei token fino a 28 ore. Questi token di lunga durata vengono aggiornati in modo proattivo da Microsoft Authentication Library (MSAL), aumentando la resilienza delle applicazioni.

Questo articolo illustra come usare le API abilitate per CAE nelle applicazioni. Le applicazioni che non usano MSAL possono aggiungere il supporto per problematiche delle attestazioni, richieste di attestazioni e funzionalità client per usare Valutazione continua dell'accesso.

Considerazioni sull'implementazione

Per usare CAE, sia l'app che l'API delle risorse a cui accede devono essere abilitate per CAE. Tuttavia, la preparazione del codice per l'uso di una risorsa abilitata per CAE non impedisce l'uso di API non abilitate per CAE.

Se un'API della risorsa implementa CAE e l'applicazione lo dichiara in grado di gestire l'ambiente di certificazione, l'app riceve i token CAE per tale risorsa. Per questo motivo, se dichiari l'app CAE pronta, l'applicazione deve gestire la richiesta di attestazione CAE per tutte le API di risorsa che accettano token di accesso a Microsoft Identity. Se non gestisci le risposte CAE in queste chiamate API, l'app potrebbe finire in un ciclo che ritenta una chiamata API con un token ancora nella durata restituita del token, ma che è stato revocato a causa dell'autorità di certificazione.

Codice

Il primo passaggio consiste nell'aggiungere codice per gestire una risposta dall'API della risorsa che rifiuta la chiamata a causa di CAE. Con CAE, le API restituiscono uno stato 401 e un'intestazione WWW-Authenticate quando il token di accesso è stato revocato o l'API rileva una modifica nell'indirizzo IP usato. L'intestazione WWW-Authenticate contiene una richiesta di attestazioni che l'applicazione può usare per acquisire un nuovo token di accesso.

Ad esempio:

// Line breaks for legibility only

HTTP 401; Unauthorized

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

L'app verificherà la presenza di:

• chiamata API che restituisce lo stato 401
• esistenza di un'intestazione WWW-Authenticate contenente:
  • parametro "error" con il valore "insufficient_claims"
  • un parametro "claims"

.NET

Quando queste condizioni vengono soddisfatte, l'app può estrarre e decodificare la richiesta di attestazioni 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);

L'app userà quindi la richiesta di attestazioni per acquisire un nuovo token di accesso per la risorsa.

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 l'applicazione è pronta per gestire la richiesta di attestazione restituita da una risorsa abilitata per CAE, è possibile indicare che l'app è pronta per l'identità Microsoft. A tale scopo nell'applicazione MSAL, compilare il client pubblico usando le funzionalità client di "cp1".

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

È possibile testare l'applicazione accedendo a un utente all'applicazione e quindi usando il portale di Azure per revocare le sessioni dell'utente. La volta successiva che l'app chiama l'API abilitata per CAE, all'utente verrà chiesto di ripetere l'autenticazione.

JavaScript

Quando vengono soddisfatte queste condizioni, l'app può estrarre la richiesta di attestazioni dall'intestazione della risposta API come indicato di seguito:

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

L'app userà quindi la richiesta di attestazioni per acquisire un nuovo token di accesso per la risorsa.

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

Una volta che l'applicazione è pronta per gestire la richiesta di attestazione restituita da una risorsa abilitata per CAE, è possibile indicare a Microsoft Identity che l'app è pronta per l'aggiunta di una clientCapabilities proprietà nella configurazione MSAL.

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

const msalInstance = new PublicClientApplication(msalConfig);

È possibile testare l'applicazione accedendo a un utente e quindi usando il portale di Azure per revocare la sessione dell'utente. La volta successiva che l'app chiama l'API abilitata per CAE, all'utente verrà chiesto di ripetere l'autenticazione.

Esempi di codice

• Abilitare l'applicazione a pagina singola Angular per accedere agli utenti e chiamare Microsoft Graph
• Abilitare l'applicazione a pagina singola React per accedere agli utenti e chiamare Microsoft Graph
• Abilitare l'app Web ASP.NET Core per accedere agli utenti e chiamare Microsoft Graph

Passaggi successivi

• Panoramica concettuale della valutazione dell'accesso continuo
• Problematiche delle attestazioni, richieste di attestazioni e funzionalità client