Guida per gli sviluppatori al contesto di autenticazione dell'accesso condizionale

L’Accesso condizionale è il piano di controllo Zero Trust che consente di impostare come destinazione i criteri per l'accesso a tutte le app – precedenti o nuove, private o pubbliche, locali o multi-cloud. Con il Contesto di autenticazione dell'accesso condizionale, è possibile applicare criteri diversi all'interno di tali app.

Il contesto di autenticazione dell'accesso condizionale (contesto di autenticazione) consente di applicare criteri granulari a dati e azioni sensibili anziché solo a livello di app. È possibile perfezionare i criteri Zero Trust per l'accesso con privilegi minimi riducendo al minimo l'attrito degli utenti e mantenendo gli utenti più produttivi e le risorse più sicure. Oggi viene usata dalle applicazioni che usano OpenId Connect per l'autenticazione sviluppata dall'azienda per proteggere le risorse sensibili, ad esempio transazioni ad alto valore o visualizzare i dati personali dei dipendenti.

Per attivare un'autenticazione dettagliata dall'interno delle applicazioni e dei servizi, usare la funzionalità di contesto di autenticazione del motore di autenticazione di Microsoft Entra. Gli sviluppatori ora hanno la capacità di richiedere un'autenticazione avanzata più severa, in modo selettivo, ad esempio l'autenticazione a più fattori dagli utenti finali dall'interno delle applicazioni. Questa funzionalità consente agli sviluppatori di creare esperienze utente più fluide per la maggior parte dei componenti dell'applicazione, mentre l'accesso a operazioni e dati più sicuri rimane a carico di controlli di autenticazione più avanzati.

Presentazione del problema

Gli amministratori IT e le autorità di regolamentazione spesso lottano per bilanciare la necessità di richiedere agli utenti fattori di autenticazione aggiuntivi troppo frequentemente e per ottenere un'adeguata sicurezza e aderenza ai criteri per le applicazioni e i servizi in cui parti di essi contengono dati e operazioni sensibili. Può essere una scelta tra criteri sicuri che influiscono sulla produttività degli utenti quando accedono alla maggior parte dei dati e delle azioni o a un criterio che non è abbastanza forte per le risorse sensibili.

Quindi, cosa accade se le app fossero in grado di combinarle entrambe, per funzionare con una sicurezza relativamente minore e richieste meno frequenti per la maggior parte degli utenti e delle operazioni e tuttavia aumentare in modo condizionale il requisito di sicurezza quando gli utenti hanno eseguito l'accesso a componenti più sensibili?

Scenari comuni

Ad esempio, mentre gli utenti potrebbero accedere a SharePoint usando l'autenticazione a più fattori, l'accesso alla raccolta siti in SharePoint contenente documenti sensibili può richiedere un dispositivo conforme e essere accessibile solo da intervalli IP attendibili.

Prerequisiti

Innanzitutto, l'app deve essere integrata con Microsoft Identity Platform usando protocolli OpenID Connect/ OAuth 2.0 per l'autenticazione e l'autorizzazione. È consigliabile usare librerie di autenticazione di Microsoft Identity Platform per integrare e proteggere l'applicazione con Microsoft Entra ID. Documentazione di Microsoft Identity Platform è un buon punto di partenza per iniziare a integrare le app con Microsoft Identity Platform. Il supporto della funzionalità Contesto di autenticazione dell’accesso condizionale è basato sulle estensioni del protocollo fornite dallo standard di settore protocollo OpenID Connect. Gli sviluppatori usano un valore di riferimento contesto di autenticazione condizionale con il parametro Claims Request per consentire alle app di attivare e soddisfare i criteri.

In secondo luogo, l'accesso condizionale richiede le licenze Microsoft Entra ID P1. Altre informazioni sulle licenze sono disponibili nella pagina dei prezzi di Microsoft Entra.

In terzo luogo, oggi è disponibile solo per le applicazioni a cui accedono agli utenti. Le applicazioni che si autenticano come se stesse non sono supportate. Usare la Guida ai flussi di autenticazione e agli scenari dell'applicazione per informazioni sui tipi e i flussi di app di autenticazione supportati in Microsoft Identity Platform.

Procedura di integrazione

Una volta integrata l'applicazione usando i protocolli di autenticazione supportati, e registrata in un tenant di Microsoft Entra con la funzionalità di accesso condizionale disponibile, è possibile avviare il processo di integrazione di questa funzionalità nelle applicazioni che consentono agli utenti di accedere.

Nota

Una procedura dettagliata di questa funzionalità è disponibile anche come sessione registrata in Usare il Contesto di autenticazione dell’accesso condizionale nell'app per l'autenticazione dettagliata.

Innanzitutto, dichiarare e rendere disponibili i contesti di autenticazione nel tenant. Per altre informazioni, vedere Configurare i contesti di autenticazione.

I valori C1-C99 sono disponibili per l'uso come ID del contesto di autenticazione in un tenant. Alcuni esempi di contesto di autenticazione possono essere:

• C1 - Richiedere l'autenticazione avanzata
• C2 - Richiedere dispositivi conformi
• C3 - Richiedere percorsi attendibili

Creare o modificare i criteri di accesso condizionale per usare i Contesti di autenticazione dell'accesso condizionale. I criteri di esempio possono essere:

• Tutti gli utenti che accedono a questa applicazione Web devono avere completato correttamente l’autenticazione a due fattori per l'ID del contesto di autenticazione C1.
• Tutti gli utenti che accedono a questa applicazione Web devono avere completato correttamente l’autenticazione a due fattori e accedere all'app Web da un determinato intervallo di indirizzi IP per l'ID del contesto di autenticazione C3.

Nota

I valori del Contesto di autenticazione dell’accesso condizionale vengono dichiarati e gestiti separatamente dalle applicazioni. Non è consigliabile che le applicazioni dipendano rigidamente dagli ID del contesto di autenticazione. I criteri di accesso condizionale vengono in genere creati dagli amministratori IT perché hanno una migliore comprensione delle risorse disponibili per l'applicazione dei criteri. Ad esempio, per un tenant di Microsoft Entra, gli amministratori IT dovrebbero conoscere il numero di utenti del tenant dotati di autenticazione a due fattori per l'autenticazione a più fattori e quindi garantire che i criteri di accesso condizionale che richiedono l’autenticazione a due fattori siano limitati a questi utenti. Analogamente, se l'applicazione viene usata in più tenant, gli ID del contesto di autenticazione in uso potrebbero essere diversi e, in alcuni casi, non sono disponibili affatto.

Secondo: gli sviluppatori di un'applicazione che prevede di usare il Contesto di autenticazione dell’accesso condizionale sono invitati a fornire prima agli amministratori dell'applicazione o agli amministratori IT un mezzo per eseguire il mapping di potenziali azioni sensibili agli ID del contesto di autenticazione. I passaggi sono approssimativamente:

1. Azioni di identità nel codice che possono essere rese disponibili per eseguire il mapping rispetto agli ID del contesto di autenticazione.
2. Creare una schermata nel portale di amministrazione dell'app (o una funzionalità equivalente) che gli amministratori IT possono usare per eseguire il mapping delle azioni sensibili rispetto a un ID del contesto di autenticazione disponibile.
3. Vedere l'esempio di codice Usare il Contesto di autenticazione dell’accesso condizionale per eseguire l’autenticazione dettagliata per un esempio su come viene eseguita.

Questi passaggi sono le modifiche che è necessario portare nella base del codice. I passaggi in generale comprendono

• Eseguire una query su MS Graph per elencare tutti i contesti di autenticazione disponibili.
• Consentire agli amministratori IT di selezionare operazioni sensibili/con privilegi elevati e assegnarle ai contesti di autenticazione disponibili usando i criteri di accesso condizionale.
• Salvare queste informazioni di mapping nell'archivio database/locale.

Terzo: l'applicazione e, per questo esempio, si presuppone che si tratti di un'API Web, quindi deve valutare le chiamate rispetto al mapping salvato e generare di conseguenza risposte di attestazione per le app client. Per prepararsi a questa azione, è necessario eseguire i passaggi seguenti:

1. In un'operazione sensibile e protetta dal contesto di autenticazione, valutare i valori nell'attestazione acrs (Record di controllo di accesso condizionale) rispetto ai mapping dell'ID del contesto di autenticazione salvati in precedenza e generare una Risposte di attestazioni come indicato nel frammento di codice seguente.

2. Il diagramma seguente illustra l'interazione tra l'utente, l'app client e l'API Web.

   

   Il frammento di codice seguente proviene dall'esempio di codice Usare il Contesto di autenticazione dell'accesso condizionale per eseguire l'autenticazione dettagliata. Il primo metodo, CheckForRequiredAuthContext() nell'API

   • Controlla se l'azione dell'applicazione chiamata richiede l'autenticazione dettagliata. Ciò avviene controllando il database per un mapping salvato per questo metodo
   • Se questa azione richiede effettivamente un contesto di autenticazione con privilegi elevati, controlla l'attestazione acrs per un ID del contesto di autenticazione esistente e corrispondente.
   • Se non viene trovato un ID contesto di autenticazione corrispondente, viene generata una risposta di attestazioni.

   public void CheckForRequiredAuthContext(string method)
   {
       string authType = _commonDBContext.AuthContext.FirstOrDefault(x => x.Operation == method
                   && x.TenantId == _configuration["AzureAD:TenantId"])?.AuthContextId;
   
       if (!string.IsNullOrEmpty(authType))
       {
           HttpContext context = this.HttpContext;
           string authenticationContextClassReferencesClaim = "acrs";
   
           if (context == null || context.User == null || context.User.Claims == null
               || !context.User.Claims.Any())
           {
               throw new ArgumentNullException("No Usercontext is available to pick claims from");
           }
   
           Claim acrsClaim = context.User.FindAll(authenticationContextClassReferencesClaim).FirstOrDefault(x
               => x.Value == authType);
   
           if (acrsClaim == null || acrsClaim.Value != authType)
           {
               if (IsClientCapableofClaimsChallenge(context))
               {
                   string clientId = _configuration.GetSection("AzureAd").GetSection("ClientId").Value;
                   var base64str = Convert.ToBase64String(Encoding.UTF8.GetBytes("{\"access_token\":{\"acrs\":{\"essential\":true,\"value\":\"" + authType + "\"}}}"));
   
                   context.Response.Headers.Append("WWW-Authenticate", $"Bearer realm=\"\", authorization_uri=\"https://login.microsoftonline.com/common/oauth2/authorize\", client_id=\"" + clientId + "\", error=\"insufficient_claims\", claims=\"" + base64str + "\", cc_type=\"authcontext\"");
                   context.Response.StatusCode = (int)HttpStatusCode.Unauthorized;
                   string message = string.Format(CultureInfo.InvariantCulture, "The presented access tokens had insufficient claims. Please request for claims requested in the WWW-Authentication header and try again.");
                   context.Response.WriteAsync(message);
                   context.Response.CompleteAsync();
                   throw new UnauthorizedAccessException(message);
               }
               else
               {
                   throw new UnauthorizedAccessException("The caller does not meet the authentication  bar to carry our this operation. The service cannot allow this operation");
               }
           }
       }
   }
   

   Nota

   Il formato della richiesta di attestazioni è descritto nell'articolo risposta di attestazioni in Microsoft Identity Platform.

3. Nell'applicazione client intercettare la risposta di attestazioni e reindirizzare l'utente a Microsoft Entra ID per un'ulteriore valutazione dei criteri. Il frammento di codice seguente proviene dall'esempio di codice Usare il Contesto di autenticazione dell'accesso condizionale per eseguire l'autenticazione dettagliata.

   internal static string ExtractHeaderValues(WebApiMsalUiRequiredException response)
   {
       if (response.StatusCode == System.Net.HttpStatusCode.Unauthorized && response.Headers.WwwAuthenticate.Any())
       {
           AuthenticationHeaderValue bearer = response.Headers.WwwAuthenticate.First(v => v.Scheme == "Bearer");
           IEnumerable<string> parameters = bearer.Parameter.Split(',').Select(v => v.Trim()).ToList();
           var errorValue = GetParameterValue(parameters, "error");
   
           try
           {
               // read the header and checks if it contains error with insufficient_claims value.
               if (null != errorValue && "insufficient_claims" == errorValue)
               {
                   var claimChallengeParameter = GetParameterValue(parameters, "claims");
                   if (null != claimChallengeParameter)
                   {
                       var claimChallenge = ConvertBase64String(claimChallengeParameter);
   
                       return claimChallenge;
                   }
               }
           }
           catch (Exception ex)
           {
               throw ex;
           }
       }
       return null;
   }
   

   Gestire l'eccezione nella chiamata all'API Web, se viene presentata una risposta di verifica delle attestazioni, reindirizzare l'utente a Microsoft Entra ID per un'ulteriore elaborazione.

   try
   {
       // Call the API
       await _todoListService.AddAsync(todo);
   }
   catch (WebApiMsalUiRequiredException hex)
   {
       // Challenges the user if exception is thrown from Web API.
       try
       {
           var claimChallenge =ExtractHeaderValues(hex);
           _consentHandler.ChallengeUser(new string[] { "user.read" }, claimChallenge);
   
           return new EmptyResult();
       }
       catch (Exception ex)
       {
           _consentHandler.HandleException(ex);
       }
   
       Console.WriteLine(hex.Message);
   }
   return RedirectToAction("Index");
   

4. (Facoltativo) Dichiarare la funzionalità client. Le funzionalità client consentono ai provider di risorse (RP) come l'API Web precedente di rilevare se l'applicazione client chiamante comprende la richiesta di attestazioni e può quindi personalizzarne la risposta di conseguenza. Questa funzionalità può essere utile nei casi in cui non tutti i client API sono in grado di gestire le risposte di attestazione e alcuni meno recenti prevedono ancora una risposta diversa. Per altre informazioni, vedere la sezione Funzionalità client.

Avvertenze e consigli

Non impostare i valori del contesto di autenticazione hard-coded nell'app. Le app devono leggere e applicare il contesto di autenticazione usando le chiamate MS Graph. Questa procedura è critica per le applicazioni multi-tenant. I valori del contesto di autenticazione variano tra i tenant di Microsoft Entra e non saranno disponibili nell'edizione gratuita di Microsoft Entra ID. Per altre informazioni su come un'app deve eseguire query, impostare e usare il contesto di autenticazione nel codice, vedere il codice di esempio Usare il Contesto di autenticazione dell'accesso condizionale per eseguire l'autenticazione dettagliata come un'applicazione dovrebbe eseguire query, impostare e utilizzare il contesto di autenticazione nel proprio codice.

Non usare il contesto di autenticazione in cui l'app stessa sarà una destinazione dei criteri di accesso condizionale. La funzionalità opera meglio quando i componenti dell'applicazione richiedono all'utente di soddisfare una barra di autenticazione superiore.

Esempi di codice

• Usare il Contesto di autenticazione dell'accesso condizionale per eseguire l'autenticazione dell’aggiornamento per le operazioni con privilegi elevati in un’app Web
• Usare il Contesto di autenticazione dell'accesso condizionale per eseguire l'autenticazione dell’aggiornamento per le operazioni con privilegi elevati in un’API Web
• Usare il Contesto di autenticazione dell'accesso condizionale per eseguire l'autenticazione dell’aggiornamento per le operazioni con privilegi elevati in un’applicazione a pagina singola React e un’API Web Express

Contesto di autenticazione [ACRS] nel comportamento previsto dell'accesso condizionale

Soddisfazione esplicita del contesto di autenticazione nelle richieste

Un client può richiedere in modo esplicito un token con un contesto di autenticazione (ACRS) tramite le attestazioni nel corpo della richiesta. Se è stato richiesto un ACRS, l’accesso condizionale consentirà di emettere il token con l’ACRS richiesto se sono state completate tutte le risposte.

Comportamento previsto quando un contesto di autenticazione non è protetto dall'accesso condizionale nel tenant

L'accesso condizionale può emettere un ACRS nelle attestazioni di un token quando tutti i criteri di accesso condizionale assegnati all’ACRS. Se non viene assegnato alcun criterio di accesso condizionale a un valore ACRS, l'attestazione potrebbe essere ancora rilasciata, perché sono stati soddisfatti tutti i requisiti dei criteri.

Tabella di riepilogo per il comportamento previsto quando vengono richiesti in modo esplicito gli ACRS

ACRS richiesto	Criterio applicato	Controllo soddisfatto	ACRS aggiunto alle attestazioni
Sì	No	Sì	Sì
Sì	Sì	No	No
Sì	Sì	Sì	Sì
Sì	Nessun criterio configurato con ACRS	Sì	Sì

Soddisfazione implicita del contesto di autenticazione per valutazione opportunistica

Un provider di risorse può acconsentire esplicitamente all'attestazione facoltativa "acrs". L'accesso condizionale tenta di aggiungere l’ACRS alle attestazioni di token in modo opportunistico per evitare i percorsi di andata e ritorno per acquisire nuovi token a Microsoft Entra ID. In tale valutazione, l'accesso condizionale verifica se i criteri che proteggono le risposte relative al contesto di autenticazione sono già soddisfatte e, in tal caso, aggiunge l’ACRS alle attestazioni del token.

Nota

Ogni tipo di token dovrà essere scelto singolarmente (token ID, token di accesso).

Se un provider di risorse non acconsente all'attestazione facoltativa "acrs", l'unico modo per ottenere un record di controllo di accesso nel token sarà chiederlo esplicitamente in una richiesta di token. Non otterrà i vantaggi della valutazione opportunistica, pertanto ogni volta che l'ACRS richiesto non sarà presente nelle attestazioni del token, il provider di risorse richiederà al client di acquisire un nuovo token che lo contiene nelle attestazioni.

Comportamento previsto con il contesto di autenticazione e i controlli sessione per la valutazione opportunistica implicita dell’ACRS

Frequenza di accesso per intervallo

L'accesso condizionale considera la "frequenza di accesso in base all'intervallo" come soddisfatta per la valutazione opportunistica dell’ACRS quando tutti i fattori di autenticazione presenti sono all'interno dell'intervallo di frequenza di accesso. Nel caso in cui il primo istante di autenticazione del fattore non sia aggiornato o se il secondo fattore (MFA) è presente e il relativo istante di autenticazione non è aggiornato, la frequenza di accesso per intervallo non verrà soddisfatta e l’ACRS non verrà rilasciato nel token in modo opportunistico.

Cloud App Security (CAS)

L'accesso condizionale considererà il controllo della sessione CAS soddisfatto per la valutazione opportunistica dell’ACRS, quando è stata stabilita una sessione CAS durante tale richiesta. Ad esempio, quando arriva una richiesta e qualsiasi criterio di accesso condizionale ha applicato e fatto rispettare una sessione CAS, e in aggiunta c'è un criterio di accesso condizionale che richiede anch'esso una sessione CAS, poiché la sessione CAS sarà applicata, ciò soddisferà il controllo della sessione CAS per la valutazione opportunistica.

Comportamento previsto quando un tenant contiene criteri di accesso condizionale che proteggono il contesto di autenticazione

La tabella seguente mostrerà tutti i casi di angolo in cui l’ACRS viene aggiunto alle attestazioni del token dalla valutazione opportunistica.

Criterio A: richiedere l'autenticazione a più fattori da tutti gli utenti, escluso l'utente "Ariel", quando si richiede il Record di controllo di accesso "c1". Criterio B: blocca tutti gli utenti, escluso l'utente "Jay", quando si richiede il Record di controllo di accesso "c2" o "c3".

Flow	ACRS richiesto	Criterio applicato	Controllo soddisfatto	ACRS aggiunto alle attestazioni
Richieste di autorizzazione per un token di accesso	"c1"	None	Sì per "c1". No per "c2" e "c3"	"c1" (obbligatorio)
Richieste di autorizzazione per un token di accesso	"c2"	Criterio B	Bloccato dal criterio B	None
Richieste di autorizzazione per un token di accesso	None	None	Sì per "c1". No per "c2" e "c3"	"c1" (aggiunti opportunisticamente dal criterio A)
Jay richiede un token di accesso (senza MFA)	"c1"	Criterio A	No	None
Jay richiede un token di accesso (con MFA)	"c1"	Criterio A	Sì	"c1" (obbligatorio), "c2" (aggiunti opportunisticamente dal criterio B), "c3" (aggiunti opportunisticamente dal criterio B)
Jay richiede un token di accesso (senza MFA)	"c2"	None	Sì per "c2" e "c3". No per "c1"	"c2" (obbligatorio), "c3" (aggiunti opportunisticamente dal criterio B)
Jay richiede un token di accesso (con MFA)	"c2"	None	Sì per "c1", "c2" e "c3"	"c1" (risultato migliore da A), "c2" (obbligatorio), "c3" (aggiunti opportunisticamente dal criterio B)
Jay richiede un token di accesso (con MFA)	None	None	Sì per "c1", "c2" e "c3"	"c1", "c2", "c3" tutti aggiunti opportunisticamente
Jay richiede un token di accesso (senza MFA)	None	None	Sì per "c2" e "c3". No per "c1"	"c2", "c3" tutti aggiunti opportunisticamente

Passaggi successivi

• L’Accesso condizionale granulare per i dati sensibili e le azioni (blog)
• Zero Trust con Microsoft Identity Platform
• Creazione di applicazioni pronte Zero Trust con Microsoft Identity Platform
• Contesto di autenticazione dell'accesso condizionale
• tipo di risorsa authenticationContextClassReference - MS Graph
• Risposta di attestazione, richiesta di attestazione e funzionalità client in Microsoft Identity Platform
• Uso del contesto di autenticazione con Microsoft Purview Information Protection e SharePoint
• Come usare le API abilitate per la valutazione continua dell'accesso nelle applicazioni