Share via

Ontwikkelaarshandleiding voor verificatiecontext voor voorwaardelijke toegang

Van toepassing op: Groene cirkel met een wit vinkje dat aangeeft dat de volgende inhoud van toepassing is op werknemerstenants. Werknemerstenants Groene cirkel met een wit vinkje dat aangeeft dat de volgende inhoud van toepassing is op externe tenants. Externe tenants (meer informatie)

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 OpenId Connect gebruiken 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 hebben vaak moeite met het verdelen van vragen aan gebruikers met extra verificatiefactoren en het bereiken van adequate naleving van beveiliging en beleid voor toepassingen. Het kan een keuze zijn tussen een sterk beleid dat van invloed is op de productiviteit van gebruikers of een beleid dat niet sterk genoeg is voor gevoelige resources.

Wat als apps beide konden combineren? Werken met een lager beveiligingsniveau en minder prompts voor de meeste scenario's. Voorwaardelijke uitbreiding van de beveiligingsvereisten wanneer er meer gevoelige gegevens worden geopend?

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 Connect/ 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 Connect-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

U kunt deze functie in uw toepassingen gaan integreren zodra deze is geïntegreerd met behulp van de ondersteunde verificatieprotocollen en geregistreerd in een Microsoft Entra-tenant waarvoor de functie voor voorwaardelijke toegang beschikbaar is.

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

Als u de verificatiecontexten voor voorwaardelijke toegang wilt gebruiken, maakt of wijzigt u uw beleid voor voorwaardelijke toegang. Voorbeelden van beleidsregels kunnen zijn:

  • Alle gebruikers die zich aanmelden bij deze webtoepassing, moeten 2FA voltooien voor verificatiecontext-id C1.
  • Alle gebruikers die zich aanmelden bij deze webtoepassing moeten 2FA voltooien en ook toegang hebben tot de app vanuit een gedefinieerd 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. IT-beheerders maken meestal beleidsregels voor voorwaardelijke toegang, omdat ze meer inzicht hebben in de beschikbare resources. 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 voorwaardelijke toegangsauthcontext om stapsgewijze authenticatie uit te voeren voor een voorbeeld.

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 om te detecteren of de 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 waarden voor verificatiecontext verschillen per Microsoft Entra-tenant 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.

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 in de claims van een token uitgeven wanneer aan alle voorwaardelijke toegang beleid die aan de ACRS-waarde zijn toegewezen 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 wordt voldaan.

Samenvattingstabel voor verwacht gedrag wanneer ACRS expliciet wordt aangevraagd

ACRS aangevraagd Toegepast beleid Besturingselement tevreden ACRS toegevoegd aan claims
Ja Nee. Ja Ja
Ja Ja Nee. Nee.
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 te krijgen door hier expliciet om te vragen in een tokenaanvraag. Het krijgt niet de voordelen van de opportunistische evaluatie, dus telkens wanneer de vereiste ACRS ontbreekt in de tokenclaims, daagt de resource provider de client uit om een nieuw token te verkrijgen dat het 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. Als een van de verificatiefactoren verouderd is, kan de aanmeldingsfrequentie per interval niet worden gehaald en zal de ACRS niet conditioneel worden uitgegeven in het token.

Cloud App Security (CAS)

Voorwaardelijke toegang beschouwt CAS-sessiebeheer als voldaan voor opportunistische ACRS-evaluatie, wanneer er tijdens dat verzoek een CAS-sessie tot stand is gebracht. Wanneer bijvoorbeeld een aanvraag binnenkomt en er een beleid voor voorwaardelijke toegang wordt toegepast en afgedwongen tot een CAS-sessie, en er is bovendien een beleid voor voorwaardelijke toegang dat ook een CAS-sessie vereist, dan wordt er voldaan aan het beheer van de CAS-sessie voor de opportunistische evaluatie doordat de CAS-sessie wordt afgedwongen.

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

In de onderstaande tabel ziet u alle randgevallen waarin ACRS wordt toegevoegd aan de claims van het token door 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

  • Last updated on