Ontwikkelaarshandleiding voor verificatiecontext voor voorwaardelijke toegang

  • Artikel

Voorwaardelijke toegang is het besturingsvlak Zero Trust waarmee u beleid kunt instellen voor toegang tot al uw apps: oud of nieuw, privé of openbaar, on-premises of multicloud. Met de verificatiecontext voor voorwaardelijke toegang kunt u verschillende beleidsregels in deze apps toepassen.

Met de verificatiecontext voor voorwaardelijke toegang (verificatiecontext) kunt u gedetailleerde beleidsregels toepassen op gevoelige gegevens en acties in plaats van alleen op app-niveau. U kunt uw Zero Trust-beleid verfijnen voor toegang met minimale bevoegdheden, terwijl u de wrijving van gebruikers minimaliseert en gebruikers productiever en uw resources veiliger houdt. Tegenwoordig wordt het gebruikt door toepassingen die Gebruikmaken van OpenId Verbinding maken voor verificatie die door uw bedrijf is ontwikkeld om gevoelige resources te beveiligen, zoals transacties met hoge waarde of het weergeven van persoonlijke gegevens van werknemers.

Als u een stapsgewijze verificatie vanuit uw toepassingen en services wilt activeren, gebruikt u de auth-contextfunctie van de Engine voor voorwaardelijke toegang van Microsoft Entra. Ontwikkelaars hebben nu de mogelijkheid om verbeterde sterkere verificatie te eisen, zoals MFA van hun eindgebruikers vanuit hun toepassingen. Met deze functie kunnen ontwikkelaars soepelere gebruikerservaringen bouwen voor de meeste onderdelen van hun toepassing, terwijl toegang tot veiligere bewerkingen en gegevens achter sterkere verificatiecontroles blijft.

Probleemformulering

De IT-beheerders en regelgevers worstelen vaak tussen het verdelen van de vraag aan hun gebruikers met te vaak extra verificatiefactoren en het bereiken van adequate naleving van beveiliging en beleid voor toepassingen en services waar delen van hen gevoelige gegevens en bewerkingen bevatten. Het kan een keuze zijn tussen een sterk beleid dat van invloed is op de productiviteit van gebruikers wanneer ze toegang hebben tot de meeste gegevens en acties of een beleid dat niet sterk genoeg is voor gevoelige resources.

Wat als apps beide konden combineren, waar ze kunnen functioneren met een relatief lagere beveiliging en minder frequente prompts voor de meeste gebruikers en bewerkingen en toch voorwaardelijk de beveiligingsvereiste opvoeren wanneer de gebruikers toegang hebben tot gevoeligere onderdelen?

Algemene scenario's

Hoewel gebruikers zich bijvoorbeeld kunnen aanmelden bij SharePoint met meervoudige verificatie, kan het openen van een siteverzameling in SharePoint met gevoelige documenten een compatibel apparaat vereisen en alleen toegankelijk zijn vanuit vertrouwde IP-bereiken.

Vereisten

Ten eerste moet uw app worden geïntegreerd met het Microsoft Identity Platform met behulp van de OpenID Verbinding maken/ OAuth 2.0-protocollen voor verificatie en autorisatie. U wordt aangeraden Microsoft Identity Platform-verificatiebibliotheken te gebruiken om uw toepassing te integreren en te beveiligen met Microsoft Entra-id. Documentatie voor Microsoft Identity Platform is een goede plek om te leren hoe u uw apps integreert met het Microsoft Identity Platform. Ondersteuning voor Auth-context voor voorwaardelijke toegang is gebouwd op basis van protocolextensies die worden geleverd door het standaard OpenID-Verbinding maken-protocol van de industriestandaard. Ontwikkelaars gebruiken een referentiewaarde voor verificatiecontextvoor voorwaardelijke toegang met de parameter Claimaanvraag om apps een manier te geven om beleid te activeren en te voldoen.

Ten tweede vereist voorwaardelijke toegang Microsoft Entra ID P1-licenties. Meer informatie over licenties vindt u op de pagina met prijzen van Microsoft Entra.

Ten derde is het momenteel alleen beschikbaar voor toepassingen die gebruikers aanmelden. Toepassingen die als zichzelf verifiëren, worden niet ondersteund. Gebruik de handleiding voor verificatiestromen en toepassingsscenario's voor meer informatie over de ondersteunde typen en stromen van verificatie-apps in het Microsoft Identity Platform.

Integratiestappen

Zodra uw toepassing is geïntegreerd met behulp van de ondersteunde verificatieprotocollen en is geregistreerd in een Microsoft Entra-tenant met de functie voor voorwaardelijke toegang die beschikbaar is voor gebruik, kunt u het proces starten om deze functie te integreren in uw toepassingen die gebruikers aanmelden.

Notitie

Een gedetailleerd overzicht van deze functie is ook beschikbaar als een opgenomen sessie bij Auth-context voor voorwaardelijke toegang gebruiken in uw app voor stapsgewijze verificatie.

Declareer en maak eerst de verificatiecontexten beschikbaar in uw tenant. Zie Verificatiecontexten configureren voor meer informatie.

Waarden C1-C99 zijn beschikbaar voor gebruik als verificatiecontext-id's in een tenant. Voorbeelden van verificatiecontext kunnen zijn:

  • C1 - Sterke verificatie vereisen
  • C2 : compatibele apparaten vereisen
  • C3 : vertrouwde locaties vereisen

Maak of wijzig uw beleid voor voorwaardelijke toegang om de contexten voor voorwaardelijke toegang te gebruiken. Voorbeelden van beleidsregels kunnen zijn:

  • Alle gebruikers die zich aanmelden bij deze webtoepassing, moeten 2FA hebben voltooid voor de verificatiecontext-id C1.
  • Alle gebruikers die zich aanmelden bij deze webtoepassing moeten 2FA hebben voltooid en ook toegang hebben tot de web-app vanuit een bepaald IP-adresbereik voor verificatiecontext-id C3.

Notitie

De contextwaarden voor voorwaardelijke toegang worden gedeclareerd en afzonderlijk onderhouden van toepassingen. Het is niet raadzaam voor toepassingen om harde afhankelijkheid te nemen van verificatiecontext-id's. Het beleid voor voorwaardelijke toegang wordt meestal gemaakt door IT-beheerders omdat ze een beter inzicht hebben in de resources waarop beleid kan worden toegepast. Voor een Microsoft Entra-tenant hebben IT-beheerders bijvoorbeeld de kennis van het aantal gebruikers van de tenant dat is uitgerust om 2FA voor MFA te gebruiken en zo ervoor te zorgen dat beleid voor voorwaardelijke toegang waarvoor 2FA is vereist, binnen het bereik van deze gebruikers vallen. Als de toepassing in meerdere tenants wordt gebruikt, kunnen de gebruikte verificatiecontext-id's afwijken en in sommige gevallen helemaal niet beschikbaar zijn.

Ten tweede: de ontwikkelaars van een toepassing die voorwaardelijke toegangsverificatiecontext willen gebruiken, wordt aangeraden eerst de toepassingsbeheerders of IT-beheerders een middel te bieden om potentiële gevoelige acties toe te wijzen aan verificatiecontext-id's. De stappen zijn ongeveer:

  1. Identiteitsacties in de code die beschikbaar kunnen worden gesteld om toe te wijzen op verificatiecontext-id's.
  2. Bouw een scherm in de beheerportal van de app (of een equivalente functionaliteit) die IT-beheerders kunnen gebruiken om gevoelige acties toe te wijzen aan een beschikbare verificatiecontext-id.
  3. Zie het codevoorbeeld, gebruik de context voor verificatie voor voorwaardelijke toegang om stapsgewijze verificatie uit te voeren voor een voorbeeld van hoe dit wordt gedaan.

Deze stappen zijn de wijzigingen die u moet doorvoeren in uw codebasis. De stappen bestaan breed uit

  • Voer een query uit op MS Graph om alle beschikbare verificatiecontexten weer te geven.
  • Hiermee kunnen IT-beheerders gevoelige/uitgebreide bewerkingen selecteren en toewijzen aan de beschikbare verificatiecontexten met behulp van beleid voor voorwaardelijke toegang.
  • Sla deze toewijzingsgegevens op in uw database/lokale archief.

Stroom instellen voor het maken van een verificatiecontext

Ten derde: Uw toepassing, en in dit voorbeeld gaan we ervan uit dat het een web-API is. Vervolgens moeten we aanroepen evalueren op basis van de opgeslagen toewijzing en dienovereenkomstig claimuitdagingen voor de client-apps veroorzaken. Om u voor te bereiden op deze actie, moeten de volgende stappen worden uitgevoerd:

  1. In een gevoelige en beveiligde verificatiecontextbewerking evalueert u de waarden in de acrs-claim op basis van de Auth Context ID-toewijzingen die eerder zijn opgeslagen en brengt u een claimvraag in, zoals is opgegeven in het volgende codefragment.

  2. In het volgende diagram ziet u de interactie tussen de gebruiker, client-app en de web-API.

    Diagram met de interactie van gebruiker, web-app, API en Microsoft Entra-id

    Het volgende codefragment is afkomstig uit het codevoorbeeld. Gebruik de context voor verificatie voor voorwaardelijke toegang om stapsgewijze verificatie uit te voeren. De eerste methode in CheckForRequiredAuthContext() de API

    • Controleert of de actie van de toepassing die wordt aangeroepen, stapsgewijze verificatie vereist. Dit doet u door de database te controleren op een opgeslagen toewijzing voor deze methode
    • Als deze actie inderdaad een verhoogde verificatiecontext vereist, controleert deze de acrs-claim op een bestaande, overeenkomende verificatiecontext-id.
    • Als een overeenkomende verificatiecontext-id niet wordt gevonden, wordt er een claimvraag gesteld.
    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");
            }
        }
    }
}

    Notitie

    De indeling van de claimvraag wordt beschreven in het artikel Claims Challenge in het Microsoft Identity Platform.

  3. In de clienttoepassing onderschept u de claimsvraag en stuurt u de gebruiker terug naar Microsoft Entra-id voor verdere beleidsevaluatie. Het volgende codefragment is afkomstig uit het codevoorbeeld. Gebruik de context voor verificatie voor voorwaardelijke toegang om stapsgewijze verificatie uit te voeren.

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

    Verhandel de uitzondering in de aanroep naar web-API, als er een claimvraag wordt weergegeven, de gebruiker terugleiden naar Microsoft Entra-id voor verdere verwerking.

    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. (Optioneel) Clientmogelijkheid declareren. Clientmogelijkheden helpen bronnenproviders (RP) zoals onze web-API hierboven om te detecteren of de aanroepende clienttoepassing de claimvraag begrijpt en vervolgens de reactie dienovereenkomstig kan aanpassen. Deze mogelijkheid kan nuttig zijn, waarbij niet alle API-clients claimuitdagingen kunnen afhandelen en sommige oudere clients nog steeds een ander antwoord verwachten. Zie de sectie Clientmogelijkheden voor meer informatie.

Opmerkingen en aanbevelingen

Codeer geen verificatiecontextwaarden in uw app. Apps moeten de verificatiecontext lezen en toepassen met MS Graph-aanroepen. Deze procedure is essentieel voor toepassingen met meerdere tenants. De verificatiecontextwaarden variëren tussen Microsoft Entra-tenants en zijn niet beschikbaar in de gratis versie van Microsoft Entra ID. Voor meer informatie over hoe een app verificatiecontext in hun code moet opvragen, instellen en gebruiken, raadpleegt u het codevoorbeeld, de context voor verificatie voor voorwaardelijke toegang gebruiken om stapsgewijze verificatie uit te voeren als hoe een app query's moet uitvoeren op, de verificatiecontext moet instellen en gebruiken in hun code.

Gebruik geen verificatiecontext waarbij de app zelf een doel wordt van beleid voor voorwaardelijke toegang. De functie werkt het beste wanneer onderdelen van de toepassing vereisen dat de gebruiker aan een hogere verificatiebalk voldoet.

Codevoorbeelden

Verificatiecontext [ACL's] in verwacht gedrag voor voorwaardelijke toegang

Expliciete tevredenheid van verificatiecontext in aanvragen

Een client kan expliciet om een token vragen met een Auth Context (ACRS) via de claims in de hoofdtekst van de aanvraag. Als een ACRS is aangevraagd, staat voorwaardelijke toegang het verlenen van het token met de aangevraagde ACRS toe als alle uitdagingen zijn voltooid.

Verwacht gedrag wanneer een verificatiecontext niet wordt beveiligd door voorwaardelijke toegang in de tenant

Voorwaardelijke toegang kan een ACRS uitgeven in de claims van een token wanneer aan alle ACRS-waarde toegewezen beleid voor voorwaardelijke toegang is voldaan. Als er geen beleid voor voorwaardelijke toegang is toegewezen aan een ACRS-waarde, kan de claim nog steeds worden uitgegeven, omdat aan alle beleidsvereisten is voldaan.

Samenvattingstabel voor verwacht gedrag wanneer ACRS expliciet wordt aangevraagd

ACRS aangevraagd Toegepast beleid Besturingselement tevreden ACRS toegevoegd aan claims
Ja No Ja Ja
Ja Ja No No
Ja Ja Ja Ja
Ja Geen beleid geconfigureerd met ACRS Ja Ja

Tevredenheid van impliciete verificatiecontext door opportunistische evaluatie

Een resourceprovider kan zich aanmelden voor de optionele acrs-claim. Voorwaardelijke toegang probeert ACRS opportunistisch toe te voegen aan de tokenclaims om retouren te voorkomen om nieuwe tokens te verkrijgen voor Microsoft Entra-id. In deze evaluatie controleert voorwaardelijke toegang of aan het beleid voor het beveiligen van verificatiecontext al wordt voldaan en wordt de ACRS toegevoegd aan de tokenclaims.

Notitie

Elk tokentype moet afzonderlijk worden aangemeld (id-token, toegangstoken).

Als een resourceprovider zich niet aanmeldt voor de optionele acrs-claim, is de enige manier om een ACRS in het token expliciet te vragen in een tokenaanvraag. Het krijgt niet de voordelen van de opportunistische evaluatie, dus telkens wanneer de vereiste ACRS ontbreekt in de tokenclaims, zal de resourceprovider de client uitvragen om een nieuw token te verkrijgen dat deze in de claims bevat.

Verwacht gedrag met verificatiecontext en sessiebesturingselementen voor impliciete opportunistische ACRS-evaluatie

Aanmeldingsfrequentie per interval

Voorwaardelijke toegang beschouwt 'aanmeldingsfrequentie per interval' als tevreden voor opportunistische ACRS-evaluatie wanneer alle huidige verificatiefactoren verificatie-instants binnen het interval voor aanmeldingsfrequentie vallen. In het geval dat het eerste verificatie-exemplaar verouderd is, of als de tweede factor (MFA) aanwezig is en het verificatie-exemplaar verouderd is, wordt de aanmeldingsfrequentie per interval niet voldaan en wordt de ACRS niet opportunistisch in het token uitgegeven.

Cloud App Security (CAS)

Voorwaardelijke toegang beschouwt cas-sessiebeheer als tevreden voor opportunistische ACRS-evaluatie, wanneer een CAS-sessie tijdens die aanvraag tot stand is gebracht. Wanneer bijvoorbeeld een aanvraag binnenkomt en een beleid voor voorwaardelijke toegang wordt toegepast en afgedwongen, en daarnaast is er een beleid voor voorwaardelijke toegang dat ook een CAS-sessie vereist, omdat de CAS-sessie wordt afgedwongen, die voldoet aan het CAS-sessiebeheer voor de opportunistische evaluatie.

Verwacht gedrag wanneer een tenant beleid voor voorwaardelijke toegang bevat om de verificatiecontext te beveiligen

In de onderstaande tabel ziet u alle hoekcases waarin ACRS wordt toegevoegd aan de claims van het token door middel van opportunistische evaluatie.

Beleid A: MFA vereisen van alle gebruikers, met uitzondering van de gebruiker "Ariel", wanneer u om "c1" acrs vraagt. Beleid B: alle gebruikers blokkeren, met uitzondering van de gebruiker 'Jay', wanneer u om 'c2' of 'c3'-aclrs wordt gevraagd.

Stroom ACRS aangevraagd Toegepast beleid Besturingselement tevreden ACRS toegevoegd aan claims
Ariel-aanvragen voor een toegangstoken "c1" Geen Ja voor 'c1'. Nee voor "c2" en "c3" "c1" (aangevraagd)
Ariel-aanvragen voor een toegangstoken "c2" Beleid B Geblokkeerd door beleid B Geen
Ariel-aanvragen voor een toegangstoken Geen Geen Ja voor 'c1'. Nee voor "c2" en "c3" "c1" (opportunistisch toegevoegd vanuit beleid A)
Jay vraagt om een toegangstoken (zonder MFA) "c1" Beleid A Nee Geen
Jay vraagt om een toegangstoken (met MFA) "c1" Beleid A Ja "c1" (aangevraagd), "c2" (opportunistisch toegevoegd vanuit beleid B), "c3" (opportunistisch toegevoegd vanuit beleid B)
Jay vraagt om een toegangstoken (zonder MFA) "c2" Geen Ja voor 'c2' en 'c3'. Nee voor "c1" "c2" (aangevraagd), "c3" (opportunistisch toegevoegd vanuit beleid B)
Jay vraagt om een toegangstoken (met MFA) "c2" Geen Ja voor "c1", "c2" en "c3" "c1" (best effort from A), "c2" (aangevraagd), "c3" (opportunistisch toegevoegd vanuit beleid B)
Jay vraagt om een toegangstoken (met MFA) Geen Geen Ja voor "c1", "c2" en "c3" "c1", "c2", "c3" alle opportunistisch toegevoegd
Jay vraagt om een toegangstoken (zonder MFA) Geen Geen Ja voor 'c2' en 'c3'. Nee voor "c1" "c2", "c3" alle opportunistisch toegevoegd

Volgende stappen