Richtlijnen voor ontwikkelaars voor voorwaardelijke toegang van Microsoft Entra

Van toepassing op: Werknemerstenants (meer informatie)

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 zakelijke klanten services op verschillende manieren beveiligen, waaronder:

• Meervoudige verificatie
• Alleen door Intune ingeschreven 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 dit artikel worden ook de gevolgen van voorwaardelijke toegang in de on-behalf-of-flow, webapps, toegang tot Microsoft Graph en het aanroepen van API's besproken.

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

Hoe heeft voorwaardelijke toegang invloed op een app?

App-typen beïnvloed

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 app indirect of op de achtergrond een token aanvraagt voor een service, vereist een app codewijzigingen om problemen met voorwaardelijke toegang af te handelen. Het kan net zo eenvoudig zijn als het uitvoeren van een interactieve aanmeldingsaanvraag.

Voor de volgende scenario's is code vereist om problemen met voorwaardelijke toegang af te handelen:

• Apps die de stroom op naam van anderen uitvoeren
• Apps die toegang hebben tot meerdere services/resources
• Apps met één pagina met MSAL.js
• Web Apps die een resource aanroepen

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

Afhankelijk van het scenario kan een enterprise-klant op elk gewenst moment beleid voor voorwaardelijke toegang toepassen en verwijderen. Implementeer de verwerking van uitdagingen zodat uw app blijft functioneren wanneer er een nieuw beleid wordt toegepast. In de volgende voorbeelden ziet u de verwerking van uitdagingen.

Voorbeelden van voorwaardelijke toegang

Voor sommige scenario's zijn codewijzigingen vereist voor het afhandelen van voorwaardelijke toegang, terwijl andere scenario's werken zoals dat wel het geval is. 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-app met één tenant en past een beleid voor voorwaardelijke toegang toe. De app meldt zich aan bij een gebruiker 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 zakelijke klant in het bedrijf die deze app gebruikt, past een beleid toe op de downstream-API. Wanneer een eindgebruiker zich aanmeldt, vraagt de systeemeigen app toegang tot de middelste laag en verzendt het token. De middelste laag voert namens de stroom uit om toegang tot de downstream-API aan te vragen. Op dit punt wordt een claimuitdaging gepresenteerd aan de middenlaag. De middelste laag stuurt de uitdaging terug naar de systeemeigen app, die moet voldoen aan het beleid voor voorwaardelijke toegang.

Microsoft Graph

Microsoft Graph heeft speciale overwegingen bij het bouwen van apps in omgevingen voor voorwaardelijke toegang. Over het algemeen gedragen de mechanismen van voorwaardelijke toegang zich hetzelfde, maar het beleid dat uw gebruikers zien, zijn gebaseerd op de onderliggende gegevens die uw app aanvraagt vanuit de grafiek.

In het bijzonder vertegenwoordigen alle Microsoft Graph-bereiken enkele gegevenssets die afzonderlijk beleidsregels kunnen toepassen. 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 app bijvoorbeeld de volgende Microsoft Graph-bereiken aanvraagt,

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

Een app kan verwachten dat hun gebruikers voldoen aan alle beleidsregels die zijn ingesteld in Teams en Exchange. Bepaalde scopes kunnen worden toegewezen aan meerdere datasets als ze toegang verlenen.

Voldoen aan een beleid voor voorwaardelijke toegang

Voor verschillende app-topologieën wordt een beleid voor voorwaardelijke toegang geëvalueerd wanneer de sessie tot stand is gebracht. Als beleid voor voorwaardelijke toegang werkt op de granulariteit van apps en services, is het punt waarop het wordt aangeroepen sterk afhankelijk van het scenario dat u probeert uit te voeren.

Wanneer uw app 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. Als deze status wordt doorgegeven, 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 details van de fout beschreven en wordt uitgelegd hoe u de parameter kunt extraheren.

Scenariën

Vereiste voorwaarden

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 voor voorwaardelijke toegang:

• Apps die de stroom op naam van anderen uitvoeren
• Apps die toegang hebben tot meerdere services/resources
• Apps 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 beleid voor voorwaardelijke toegang is toegepast.

Scenario: De app die de namens-andere uitvoeringsstroom uitvoert

In dit scenario doorlopen we de case waarin een systeemeigen app een webservice/API aanroept. Op zijn beurt voert deze service het "namens iemand anders"-proces uit om een downstreamservice aan te roepen. In ons geval hebben we ons beleid voor voorwaardelijke toegang toegepast op de downstreamservice (web-API 2) en gebruiken we een systeemeigen app in plaats van een server-/daemon-app.

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:

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 multifactor 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_requiredop en sturen we de claims uitdaging terug naar de bureaublad-app. Op dat moment kan de desktop-applicatie een nieuwe acquireToken() aanroep maken en de claimsuitdaging toevoegen als een extra parameter van de queryreeks. Voor deze nieuwe aanvraag moet de gebruiker multifactorauthenticatie uitvoeren en dit nieuwe token vervolgens terugsturen naar Web-API 1 en de on-behalf-of-stroom voltooien.

Als u dit scenario wilt uitproberen, raadpleegt u ons .NET-codevoorbeeld. Het laat zien hoe u de claimvraag teruggeeft van Web API 1 naar de systeemeigen app en hoe u een nieuwe aanvraag in de client-app maakt.

Scenario: App die toegang heeft tot meerdere services

In dit scenario doorlopen we het geval waarin een web-app toegang heeft tot twee services waaraan een beleid voor voorwaardelijke toegang is toegewezen. Afhankelijk van uw app-logica bestaat er mogelijk een pad waarin uw app geen toegang tot beide webservices vereist. In dit scenario speelt de volgorde waarin u een token aanvraagt een belangrijke rol in de eindgebruikerservaring.

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 in alle gevallen niet vereist. Als de app een token aanvraagt voor webservice B, wordt het beleid aangeroepen en slagen de volgende aanvragen voor webservice A ook.

Als de app in eerste instantie een token aanvraagt voor webservice A, roept de eindgebruiker het beleid voor voorwaardelijke toegang niet aan. Hierdoor kan de app-ontwikkelaar de eindgebruikerservaring beheren en kan het beleid voor voorwaardelijke toegang niet in alle gevallen 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 app probeert de acquireToken te gebruiken, kan deze de volgende fout genereren (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 multifactor authentication to access '<Web API App/Client ID>'.
claims={"access_token":{"polids":{"essential":true,"Values":["<GUID>"]}}}

Als de app 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 het verzoek een AcquireTokenSilentAsync of PromptBehavior.Never is, in welk geval de app een interactief AcquireToken verzoek moet uitvoeren om de eindgebruiker de mogelijkheid te geven om aan het beleid te voldoen.

Scenario: app met één pagina (SPA) met behulp van MSAL.js

In dit scenario bespreken we het geval waarin we een single-page application (SPA) hebben die een web-API met Voorwaardelijke Toegang aanroept met behulp van MSAL.js. Dit is een eenvoudige architectuur, maar heeft enkele nuances waarmee rekening moet worden gehouden bij het ontwikkelen van voorwaardelijke toegang.

In MSAL.jszijn er enkele functies die tokens verkrijgen: 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 ze altijd de aanmeldingsgebruikersinterface weergeven.

Wanneer een app een toegangstoken nodig heeft om een web-API aan te roepen, probeert het een acquireTokenSilent(). Als het token is verlopen of als we aan een voorwaardelijk toegangsbeleid moeten voldoen, dan mislukt de acquireToken functie en gebruikt de app acquireTokenPopup() of acquireTokenRedirect().

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 raakt de gebruiker een knop waarvoor de app gegevens van een web-API moet aanvragen. 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 multifactor authentication to access '<Web API App/Client ID>'.

Onze app moet de error=interaction_required opvangen. De toepassing kan vervolgens of acquireTokenPopup() of acquireTokenRedirect() op dezelfde bron gebruiken. 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 de Node.js web-API aanroept met gebruik van de on-behalf-of flow voorbeeldcode. 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 claimvraag correct kunt afhandelen en een toegangstoken kunt ophalen dat kan worden gebruikt voor uw web-API.

Zie ook

• Zie Voorwaardelijke toegang in Microsoft Entra ID voor meer informatie over de mogelijkheden.
• Zie voorbeelden voor meer Microsoft Entra-codevoorbeelden.
• Zie het overzicht van de Microsoft Authentication Library voor meer informatie over de MSAL SDK's en toegang tot de referentiedocumentatie.
• Zie Gebruikers aanmelden met behulp van het multitenant-patroon voor meer informatie over scenario's met meerdere tenants.
• Meer informatie over voorwaardelijke toegang en het beveiligen van toegang tot IoT-apps.