Richtlijnen voor ontwikkelaars voor voorwaardelijke toegang met Microsoft Entra

  • Artikel

De functie Voorwaardelijke toegang in Microsoft Entra ID biedt een van de verschillende manieren waarop u uw app kunt beveiligen en een service kunt beveiligen. Met voorwaardelijke toegang kunnen ontwikkelaars en enterpriseklanten services op verschillende manieren beveiligen, waaronder:

  • Meervoudige verificatie
  • Alleen bij Intune geregistreerde apparaten toegang geven tot specifieke services
  • Gebruikerslocaties en IP-bereiken beperken

Zie het artikel Wat is voorwaardelijke toegang voor meer informatie over de volledige mogelijkheden van voorwaardelijke toegang.

Voor ontwikkelaars die apps bouwen voor Microsoft Entra-id, wordt in dit artikel beschreven hoe u voorwaardelijke toegang kunt gebruiken en leert u ook wat de gevolgen zijn van het openen van resources waarvoor u geen controle hebt over het beleid voor voorwaardelijke toegang. In het artikel worden ook de gevolgen besproken van voorwaardelijke toegang in de on-behalf-of-stroom, webtoepassingen, toegang tot Microsoft Graph en het aanroepen van API's.

Kennis van apps met één en meerdere tenants en algemene verificatiepatronen wordt verondersteld.

Notitie

Voor het gebruik van deze functie is een licentie voor Microsoft Entra ID P1 vereist. Zie Algemeen beschikbare functies van de edities Gratis, Basic en Premium vergelijken als u een licentie zoekt die bij uw vereisten past. Klanten met een Microsoft 365 Business-licentie hebben ook toegang tot de functies voor voorwaardelijke toegang.

Hoe heeft voorwaardelijke toegang invloed op een toepassing?

Beïnvloede toepassingstypen

In de meeste gevallen verandert voorwaardelijke toegang het gedrag van een app niet of vereist eventuele wijzigingen van de ontwikkelaar. Alleen in bepaalde gevallen wanneer een toepassing indirect of op de achtergrond een token aanvraagt voor een service, zijn codewijzigingen in de toepassing vereist om 'uitdagingen' van voorwaardelijke toegang af te handelen. Het kan zo eenvoudig zijn als het uitvoeren van een interactieve aanmeldingsaanvraag.

In de volgende scenario's is code vereist voor het afhandelen van 'uitdagingen' van voorwaardelijke toegang:

  • Toepassingen die de on-behalf-of-stroom uitvoeren
  • Toepassing die toegang hebben tot meerdere services/resources
  • Toepassingen met één pagina met MSAL.js
  • Webtoepassingen die een resource aanroepen

Beleid voor voorwaardelijke toegang kan worden toegepast op de toepassing, maar kan ook worden toegepast op een web-API die uw toepassing gebruikt. Zie de quickstart: MFA vereisen voor specifieke apps met voorwaardelijke toegang van Microsoft Entra voor meer informatie over het configureren van beleid voor voorwaardelijke toegang.

Afhankelijk van het scenario kan een enterpriseklant op elk gewenst moment beleid voor voorwaardelijke toegang toepassen en verwijderen. Implementeer de afhandeling van uitdagingen, zodat uw app blijft functioneren wanneer er een nieuw beleid wordt toegepast. De volgende voorbeelden illustreren de afhandeling van uitdagingen.

Voorbeelden van voorwaardelijke toegang

In sommige scenario's zijn codewijzigingen vereist voor het afhandelen van voorwaardelijke toegang, terwijl andere gewoon werken. Hier volgen enkele scenario's waarbij voorwaardelijke toegang wordt gebruikt om meervoudige verificatie uit te voeren waarmee u inzicht krijgt in het verschil.

  • U bouwt een iOS-toepassing met één tenant en past een beleid voor voorwaardelijke toegang toe. De toepassing meldt een gebruiker aan en vraagt geen toegang tot een API. Wanneer de gebruiker zich aanmeldt, wordt het beleid automatisch aangeroepen en moet de gebruiker meervoudige verificatie (MFA) uitvoeren.
  • U bouwt een systeemeigen app die gebruikmaakt van een service in de middelste laag voor toegang tot een downstream-API. Een enterpriseklant van het bedrijf die deze toepassing gebruikt, past een beleid toe op de downstream-API. Wanneer een eindgebruiker zich aanmeldt, vraagt de systeemeigen toepassing toegang tot de middelste laag en verzendt deze het token. De middelste laag voert de on-behalf-stroom uit om toegang tot de downstream-API aan te vragen. Op dit moment wordt een claim-'uitdaging' gepresenteerd aan de middelste laag. De middelste laag stuurt de uitdaging terug naar de systeemeigen toepassing, die moet voldoen aan het beleid voor voorwaardelijke toegang.

Microsoft Graph

Voor Microsoft Graph zijn er speciale overwegingen bij het bouwen van toepassingen in omgevingen met voorwaardelijke toegang. Over het algemeen gedragen de mechanismen van voorwaardelijke toegang zich hetzelfde, maar het beleid dat uw gebruikers zien, is gebaseerd op de onderliggende gegevens die uw toepassing aanvraagt vanuit de graaf.

In het bijzonder vertegenwoordigen alle Microsoft Graph-bereiken enkele gegevenssets waarop beleid afzonderlijk kan worden toegepast. Omdat beleid voor voorwaardelijke toegang wordt toegewezen aan de specifieke gegevenssets, dwingt Microsoft Entra-id beleid voor voorwaardelijke toegang af op basis van de gegevens achter Graph, in plaats van Graph zelf.

Als een toepassing bijvoorbeeld de volgende Microsoft Graph-bereiken aanvraagt,

scopes="ChannelMessages.Read.All Mail.Read"

Een toepassing kan verwachten dat gebruikers voldoen aan alle beleidsregels die zijn ingesteld op Teams en Exchange. Sommige bereiken kunnen worden toegewezen aan meerdere gegevenssets als deze toegang verleent.

Voldoen aan een beleid voor voorwaardelijke toegang

Voor verschillende toepassingstopologieën wordt een beleid voor voorwaardelijke toegang geëvalueerd wanneer de sessie tot stand wordt gebracht. Als beleid voor voorwaardelijke toegang werkt op de granulariteit van toepassingen en services, hangt het punt waarop het wordt aangeroepen sterk af van het scenario dat u probeert te bewerkstelligen.

Wanneer uw toepassing toegang probeert te krijgen tot een service met beleid voor voorwaardelijke toegang, kan er een uitdaging voor voorwaardelijke toegang optreden. Deze uitdaging wordt gecodeerd in de claims parameter die wordt geleverd in een antwoord van Microsoft Entra-id. Hier volgt een voorbeeld van deze uitdagingsparameter:

claims={"access_token":{"polids":{"essential":true,"Values":["<GUID>"]}}}

Ontwikkelaars kunnen deze uitdaging aannemen en deze toevoegen aan een nieuwe aanvraag voor Microsoft Entra-id. Door deze status door te geven, wordt de eindgebruiker gevraagd om een actie uit te voeren die nodig is om te voldoen aan het beleid voor voorwaardelijke toegang. In de volgende scenario's worden de specifieke details van de fout en het extraheren van de parameter uitgelegd.

Scenario's

Vereisten

Voorwaardelijke toegang van Microsoft Entra is een functie die is opgenomen in Microsoft Entra ID P1 of P2. Klanten met een Microsoft 365 Business-licentie hebben ook toegang tot de functies voor voorwaardelijke toegang.

Overwegingen voor specifieke scenario's

De volgende informatie is alleen van toepassing in deze scenario's met voorwaardelijke toegang:

  • Toepassingen die de on-behalf-of-stroom uitvoeren
  • Toepassing die toegang hebben tot meerdere services/resources
  • Toepassingen met één pagina met MSAL.js

In de volgende secties worden veelvoorkomende scenario's besproken die complexer zijn. Het belangrijkste operationele principe is dat beleid voor voorwaardelijke toegang wordt geëvalueerd op het moment dat het token wordt aangevraagd voor de service waarop een beleid voor voorwaardelijke toegang is toegepast.

Scenario: app voert de on-behalf-of-stroom uit

In dit scenario doorlopen we de case waarin een systeemeigen toepassing een webservice/-API aanroept. Op zijn beurt voert deze service de 'on-behalf-of'-stroom uit om een downstream service aan te roepen. In onze case hebben we ons beleid voor voorwaardelijke toegang toegepast op de downstream service (web-API 2) en gebruiken we een systeemeigen toepassing in plaats van een server-/daemontoepassing.

App performing the on-behalf-of flow diagram

De initiële tokenaanvraag voor Web-API 1 vraagt de eindgebruiker niet om meervoudige verificatie, omdat web-API 1 mogelijk niet altijd de downstream-API raakt. Zodra Web API 1 probeert een token namens de gebruiker voor Web API 2 aan te vragen, mislukt de aanvraag omdat de gebruiker zich niet heeft aangemeld met meervoudige verificatie.

Microsoft Entra ID retourneert een HTTP-antwoord met enkele interessante gegevens:

Notitie

In dit geval is het een beschrijving van een fout in meervoudige verificatie, maar er is een breed scala van interaction_required mogelijk met betrekking tot voorwaardelijke toegang.

HTTP 400; Bad Request
error=interaction_required
error_description=AADSTS50076: Due to a configuration change made by your administrator, or because you moved to a new location, you must use multi-factor authentication to access '<Web API 2 App/Client ID>'.
claims={"access_token":{"polids":{"essential":true,"Values":["<GUID>"]}}}

In web-API 1 vangen we de fout error=interaction_required af en sturen we de uitdaging claims terug naar de desktoptoepassing. Op dat moment kan de desktoptoepassing een nieuwe aanroep van acquireToken() doen en de claims-uitdaging toevoegen als een extra parameter in de querytekenreeks. Voor deze nieuwe aanvraag moet de gebruiker meervoudige verificatie uitvoeren en dit nieuwe token vervolgens terugsturen naar web-API 1 en de stroom namens de stroom voltooien.

Zie ons .NET-codevoorbeeld om dit scenario uit te proberen. Het laat zien hoe u de claimuitdaging van web-API 1 kunt doorgeven aan de systeemeigen toepassing en een nieuwe aanvraag maakt in de clienttoepassing.

Scenario: toepassing die toegang heeft tot meerdere services

In dit scenario doorlopen we de case waarin een webtoepassing toegang heeft tot twee services waaraan een beleid voor voorwaardelijke toegang is toegewezen. Afhankelijk van uw toepassingslogica bestaat er mogelijk een pad waarin uw toepassing geen toegang tot beide webservices vereist. In dit scenario speelt de volgorde waarin u een token aanvraagt een belangrijke rol in de ervaring van de eindgebruiker.

Stel dat we webservice A en B hebben en dat ons beleid voor voorwaardelijke toegang is toegepast op webservice B. Hoewel voor de eerste interactieve verificatieaanvraag toestemming is vereist voor beide services, is het beleid voor voorwaardelijke toegang niet vereist in alle gevallen. Als de toepassing een token aanvraagt voor webservice B, wordt het beleid aangeroepen en slagen daaropvolgende aanvragen voor webservice A ook als volgt.

App accessing multiple-services flow diagram

Als de toepassing in eerste instantie een token aanvraagt voor webservice A, roept de eindgebruiker het beleid voor voorwaardelijke toegang niet aan. Hierdoor kan de toepassingsontwikkelaar de ervaring van de eindgebruiker beheren en hoeft het beleid voor voorwaardelijke toegang niet in alle gevallen te worden aangeroepen. Het lastige geval is dat de app later een token aanvraagt voor webservice B. Op dit moment moet de eindgebruiker voldoen aan het beleid voor voorwaardelijke toegang. Wanneer de toepassing acquireToken probeert uit te voeren, kan dat de volgende fout opleveren (geïllustreerd in het volgende diagram):

HTTP 400; Bad Request
error=interaction_required
error_description=AADSTS50076: Due to a configuration change made by your administrator, or because you moved to a new location, you must use multi-factor authentication to access '<Web API App/Client ID>'.
claims={"access_token":{"polids":{"essential":true,"Values":["<GUID>"]}}}

App accessing multiple services requesting a new token

Als de toepassing gebruikmaakt van de MSAL-bibliotheek, wordt het verkrijgen van het token altijd interactief opnieuw geprobeerd. Wanneer deze interactieve aanvraag plaatsvindt, heeft de eindgebruiker de mogelijkheid om te voldoen aan de voorwaardelijke toegang. Dit geldt tenzij de aanvraag een AcquireTokenSilentAsync of PromptBehavior.Never is, in welk geval de toepassing een interactieve AcquireToken-aanvraag moet uitvoeren om de eindgebruiker de mogelijkheid te geven om te voldoen aan het beleid.

Scenario: toepassing met één pagina (SPA) die MSAL.js gebruikt

In dit scenario doorlopen we de case wanneer we een app met één pagina (SPA) hebben die MSAL.js gebruikt om een web-API met voorwaardelijke toegang aan te roepen. Dit is een eenvoudige architectuur, maar heeft enkele nuances waarmee rekening moet worden gehouden bij het ontwikkelen van voorwaardelijke toegang.

In MSAL.js zijn er enkele functies waarmee tokens worden verkregen: acquireTokenSilent(), acquireTokenPopup() en acquireTokenRedirect().

  • acquireTokenSilent() kan worden gebruikt om op de achtergrond een toegangstoken te verkrijgen, wat betekent dat de gebruikersinterface in geen geval wordt weergegeven.
  • acquireTokenPopup() en acquireTokenRedirect() worden beide gebruikt om interactief een token aan te vragen voor een resource, wat betekent dat de aanmeldingsgebruikersinterface altijd wordt weergeven.

Wanneer een toepassing een toegangstoken nodig heeft om een web-API aan te roepen, probeert deze een acquireTokenSilent() uit te voeren. Als het token is verlopen of als we moeten voldoen aan een beleid voor voorwaardelijke toegang, mislukt de functie acquireToken en gebruikt de toepassing acquireTokenPopup() of acquireTokenRedirect().

Single-page app using MSAL flow diagram

Laten we een voorbeeld bekijken met ons scenario voor voorwaardelijke toegang. De eindgebruiker is net op de site terechtgekomen en heeft geen sessie. We voeren een loginPopup() aanroep uit, halen een id-token op zonder meervoudige verificatie. Vervolgens drukt de gebruiker op een knop waardoor de app gegevens moet aanvragen bij een web-API. De app probeert een acquireTokenSilent() aanroep uit te voeren, maar mislukt omdat de gebruiker nog geen meervoudige verificatie heeft uitgevoerd en moet voldoen aan het beleid voor voorwaardelijke toegang.

Microsoft Entra-id stuurt het volgende HTTP-antwoord terug:

HTTP 400; Bad Request
error=interaction_required
error_description=AADSTS50076: Due to a configuration change made by your administrator, or because you moved to a new location, you must use multi-factor authentication to access '<Web API App/Client ID>'.

Onze toepassing moet de error=interaction_required cachen. De toepassing kan vervolgens acquireTokenPopup() of acquireTokenRedirect() gebruiken voor dezelfde resource. De gebruiker wordt gedwongen om meervoudige verificatie uit te voeren. Nadat de gebruiker de meervoudige verificatie heeft voltooid, krijgt de app een nieuw toegangstoken voor de aangevraagde resource.

Als u dit scenario wilt uitproberen, raadpleegt u onze React SPA die Node.js web-API aanroept met behulp van een voorbeeld van stroomcode . In dit codevoorbeeld wordt gebruikgemaakt van het beleid voor voorwaardelijke toegang en de web-API die u eerder hebt geregistreerd bij een React SPA om dit scenario te demonstreren. Het laat zien hoe u de claimuitdaging goed kunt afhandelen en een toegangstoken kunt ophalen dat kan worden gebruikt voor uw web-API.

Zie ook