Ontwikkelaarshandleiding voor verificatiecontext voor voorwaardelijke toegang

Van toepassing op: Werknemerstenants Externe tenants (meer informatie)

Conditional Access is het Zero Trust-control plane 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 binnen die apps toepassen.

Met de authenticatiecontext voor voorwaardelijke toegang (authenticatiecontext) 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 rechten, terwijl u de wrijving van gebruikers minimaliseert en gebruikers productiever en uw resources veiliger houdt. Tegenwoordig wordt het gebruikt door toepassingen die door uw bedrijf zijn ontwikkeld en OpenId Connect gebruiken voor verificatie om gevoelige resources te beveiligen, zoals transacties met hoge waarde of het weergeven van persoonlijke gegevens van werknemers.

Als u step-up-authenticatie 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 selectief sterkere authenticatie 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 om het vragen aan gebruikers om extra authenticatiefactoren af te wegen tegen 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?

Veelvoorkomende scenario’s

Hoewel gebruikers zich bijvoorbeeld kunnen aanmelden bij SharePoint met multifactorauthenticatie, kan een siteverzameling in SharePoint met gevoelige documenten een conform apparaat vereisen en alleen toegankelijk zijn vanuit vertrouwde IP-bereiken.

Vereisten

Ten eerste moet uw app worden geïntegreerd met het Microsoft-identiteitsplatform met gebruik van de protocollen OpenID Connect/ OAuth 2.0 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 industriestandaardprotocol OpenID Connect. Ontwikkelaars gebruiken een referentiewaarde voor verificatiecontext voor voorwaardelijke toegang met de parameter Claims Request om apps een manier te geven om beleid te activeren en eraan te voldoen.

Ten tweede, Conditional Access vereist 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 waarbij gebruikers zich kunnen aanmelden. Toepassingen die als zichzelf verifiëren, worden niet ondersteund. Gebruik de handleiding voor authenticatiestromen en toepassingsscenario's voor meer informatie over de ondersteunde typen en stromen van authenticatie-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.

Eerst, definieer en maak de verificatiecontexten beschikbaar in uw tenant. Zie authenticatiecontexten 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 authenticatie 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. Voorbeeldbeleidsregels 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.

Ten tweede: de ontwikkelaars van een toepassing die Conditional Access-authcontext willen gebruiken, worden aangeraden eerst de toepassingsbeheerders of IT-beheerders een middel te bieden om potentiële gevoelige acties toe te wijzen aan authcontext-id's. De stappen zijn ongeveer als volgt:

1. Identiteitsacties in de code die beschikbaar kunnen worden gesteld om toe te wijzen aan auth-context-ID's.
2. Bouw een scherm in de beheerportal van de app (of een equivalente functionaliteit) die IT-beheerders kunnen gebruiken om gevoelige acties te koppelen 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 grofweg uit

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

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

1. In een gevoelige, door auth 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 Claims Challenge 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.

   

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

   • Controleert of de actie van de toepassing die wordt aangeroepen, step-up-authenticatie vereist. Dit doet het door de database te controleren op een opgeslagen toewijzing voor deze methode
   • Als deze actie inderdaad een verhoogde authenticatiecontext vereist, controleert deze de acrs-claim op een bestaande, overeenkomende Auth Context ID.
   • Als een overeenkomende Auth Context ID niet wordt gevonden, wordt er een claims challenge gegenereerd.

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

   Opmerking

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

3. In de clienttoepassing onderschept u de claims-uitdaging en stuurt u de gebruiker terug naar Microsoft Entra ID voor verdere beleidsevaluatie. Het volgende codefragment is afkomstig uit het codevoorbeeld, Gebruik de verificatiecontext voor voorwaardelijke toegang om step-up-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;
   }
   

   Verwerk de uitzondering in de aanroep naar de web-API; als er een claims challenge wordt weergegeven, leid de gebruiker dan terug 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) Clientcapaciteit 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 in gevallen waarin niet alle API-clients claimuitdagingen kunnen afhandelen en sommige oudere clients nog steeds een ander antwoord verwachten. Zie de sectie Clientmogelijkheden voor meer informatie.

Kanttekeningen en aanbevelingen

Codeer geen Auth Context-waarden in uw app. Apps moeten de authenticatiecontext 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 auth-context 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 hoger verificatieniveau voldoet.

Codevoorbeelden

• De auth-context voor voorwaardelijke toegang gebruiken om step-up-verificatie uit te voeren voor bewerkingen met hoge bevoegdheden in een web-app
• De auth-context voor voorwaardelijke toegang gebruiken om step-up-verificatie uit te voeren voor bewerkingen met hoge bevoegdheden in een web-API
• De auth-context voor voorwaardelijke toegang gebruiken om step-up-authenticatie uit te voeren voor bewerkingen met hoge bevoegdheden in een React-toepassing met één pagina en een Express-web-API

Authenticatiecontext [ACRs] in Voorwaardelijke toegang: verwacht gedrag

Expliciete voldoening aan de authenticatiecontext in verzoeken

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 authenticatiecontext niet wordt beveiligd door Conditional Access 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 worden aangevraagd

Voldoen aan impliciete authenticatiecontext 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 extra aanvragen te voorkomen voor het verkrijgen van nieuwe tokens van Microsoft Entra ID. In deze evaluatie controleert voorwaardelijke toegang of al wordt voldaan aan het beleid dat Auth Context-uitdagingen beveiligt en wordt de ACRS toegevoegd aan de tokenclaims als dat het geval is.

Verwacht gedrag met authenticatiecontext en sessiecontroles voor impliciete opportunistische ACRS-evaluatie

Aanmeldingsfrequentie per interval

Conditional Access beschouwt 'aanmeldingsfrequentie per interval' als voldaan voor opportunistische evaluatie van ACRS wanneer de auth-instants van de aanwezige verificatiefactoren allemaal 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 Conditional Access-beleid bevat dat de verificatiecontext beschermt

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", bij het aanvragen van "c1" ACRs. Beleid B: alle gebruikers blokkeren, met uitzondering van de gebruiker 'Jay', wanneer om 'c2' of 'c3' acrs wordt gevraagd.

Volgende stappen

• Gedetailleerde voorwaardelijke toegang voor gevoelige gegevens en acties (blog)
• Zero Trust met het Microsoft Identity Platform
• Zero Trust-klare apps bouwen met het Microsoft Identity Platform
• Verificatiecontext voor voorwaardelijke toegang
• resourcetype authenticationContextClassReference - MS Graph
• claims-uitdaging, claimaanvraag en clientmogelijkheden in het Microsoft-identiteitsplatform
• Verificatiecontext gebruiken met Microsoft Purview Informatiebeveiliging en SharePoint
• API's met Continuous Access Evaluation gebruiken in uw toepassingen