Condividi tramite

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

Si applica a: Cerchio verde con un simbolo di spunta bianco che indica che il contenuto seguente si applica ai tenant della forza lavoro. I tenant della forza lavoro Cerchio verde con un simbolo di spunta bianco che indica che il contenuto seguente si applica ai tenant esterni. I tenant esterni (Altre informazioni)

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 faticano a bilanciare la richiesta degli utenti con fattori aggiuntivi di autenticazione e di ottenere una conformità adeguata alla sicurezza e ai criteri per le applicazioni. Può essere una scelta tra un criterio sicuro che influisce sulla produttività degli utenti o su un criterio che non è abbastanza forte per le risorse sensibili.

E se le app fossero in grado di combinare entrambe? Funzionamento con un livello di sicurezza inferiore e meno richieste per la maggior parte degli scenari. Quindi aumentare in modo condizionale i requisiti di sicurezza quando si accede a dati 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 riferimentocontesto 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

È possibile avviare l'integrazione di questa funzionalità nelle applicazioni dopo l'integrazione usando i protocolli di autenticazione supportati e registrati in un tenant di Microsoft Entra con la funzionalità di accesso condizionale disponibile.

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

Per usare i contesti di autenticazione dell'accesso condizionale, creare o modificare i criteri di accesso condizionale. I criteri di esempio possono essere:

  • Tutti gli utenti che accedono a questa applicazione Web devono completare correttamente 2FA per l'ID contesto di autenticazione C1.
  • Tutti gli utenti che accedono a questa applicazione Web devono completare correttamente 2FA e accedere anche all'app da un intervallo di indirizzi IP definito per l'ID 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. Gli amministratori IT in genere costruiscono i criteri di accesso condizionale in quanto hanno una migliore comprensione delle risorse disponibili. 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 il codice di esempio Usare il contesto di autenticazione dell'accesso condizionale per eseguire l'autenticazione avanzata per un esempio.

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.

Flusso di installazione per la creazione di un contesto di autenticazione

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.

    Diagramma che mostra l'interazione dell'utente, dell'app Web, dell'API e di Microsoft Entra ID

    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 di rilevare se l'applicazione client riconosce 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 sono disponibili nell'edizione Microsoft Entra ID Free. Per altre informazioni su come un'app deve eseguire query, impostare e usare il contesto di autenticazione nel codice, vedere l'esempio di codice Usare il contesto di autenticazione dell'accesso condizionale per eseguire l'autenticazione dettagliata.

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

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 consente di emettere il token con l'ACRS richiesto se sono stati completati tutti i requisiti.

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

Il servizio di accesso condizionale può emettere un ACRS nelle dichiarazioni di un token quando vengono soddisfatti tutti i criteri di accesso condizionale assegnati al valore ACRS. Se non viene assegnato alcun criterio di accesso condizionale a un valore ACRS, l'attestazione potrebbe essere ancora rilasciata, perché tutti i requisiti dei criteri vengono soddisfatti.

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 deve essere scelto singolarmente (token ID, token di accesso).

Se un fornitore di risorse non sceglie di utilizzare il claim facoltativo 'acrs', l'unico modo per ottenere un ACRS nel token è richiederlo esplicitamente in una richiesta di token. Non otterrà i vantaggi della valutazione opportunistica, quindi ogni volta che l'ACRS richiesto manca dalle attestazioni del token, il provider di risorse sfida il client ad acquisire un nuovo token che lo contenga 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 uno dei fattori di autenticazione sia obsoleto, la frequenza di accesso per intervallo non verrà rispettata e l'ACRS non verrà emesso nel token in modo opportunistico.

Cloud App Security (CAS)

L'accesso condizionale considera il controllo della sessione CAS soddisfatto per la valutazione opportunistica di ACRS, quando una sessione CAS è stata stabilita durante quella richiesta. Ad esempio, quando arriva una richiesta e vengono applicati dei criteri di accesso condizionale che impongono una sessione CAS, e in aggiunta è presente un criterio di accesso condizionale che richiede anche una sessione CAS, poiché la sessione CAS sarà applicata, ciò soddisfa 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 mostra tutti i casi limite in cui l'ACRS viene aggiunto ai claim 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".

Flusso ACRS richiesto Criterio applicato Controllo soddisfatto ACRS aggiunto alle attestazioni
Richieste di autorizzazione per un token di accesso c1 Nessuno 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 Nessuno
Richieste di autorizzazione per un token di accesso Nessuno Nessuno 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 Nessuno
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 Nessuno 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 Nessuno 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) Nessuno Nessuno Sì per "c1", "c2" e "c3" "c1", "c2", "c3" tutti aggiunti opportunisticamente
Jay richiede un token di accesso (senza MFA) Nessuno Nessuno Sì per "c2" e "c3". No per "c1" "c2", "c3" tutti aggiunti opportunisticamente

Passaggi successivi

  • Last updated on