Ontwikkelaarsrichtlijnen voor de functie Azure Active Directory voorwaardelijke toegang

Waarschuwing

Deze inhoud is voor het oudere Azure AD v1.0-eindpunt. Gebruik het Microsoft Identity Platform voor nieuwe projecten.

Notitie

Zie de ontwikkelaarsrichtlijnen voor Azure Active Directory voorwaardelijke toegang voor de Microsoft identity platform versie van dit artikel.

De functie voor voorwaardelijke toegang in Azure Active Directory (Azure AD) 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 Intune ingeschreven apparaten toegang geven tot specifieke services
  • Gebruikerslocaties en IP-bereiken beperken

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

Voor ontwikkelaars die apps bouwen voor Azure AD, ziet u in dit artikel hoe u voorwaardelijke toegang kunt gebruiken en krijgt u ook informatie over de gevolgen van het openen van resources waarvoor u geen controle hebt over het beleid voor voorwaardelijke toegang. In het artikel worden ook de gevolgen van voorwaardelijke toegang in de on-behalf-of-flow, web-apps, toegang tot Microsoft Graph en het aanroepen van API's besproken.

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

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 voor een service aanvraagt, vereist een app codewijzigingen voor het afhandelen van problemen met voorwaardelijke toegang. Het kan net zo eenvoudig zijn als het uitvoeren van een interactieve aanmeldingsaanvraag.

Voor de volgende scenario's is code vereist voor het afhandelen van problemen met voorwaardelijke toegang:

  • Apps die de on-behalf-of-flow uitvoeren
  • Apps die toegang hebben tot meerdere services/resources
  • Apps met één pagina met ADAL.js
  • Web Apps 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 opent. Zie Algemene beleidsregels voor voorwaardelijke toegang voor meer informatie over het configureren van beleid voor voorwaardelijke toegang.

Afhankelijk van het scenario kan een zakelijke klant op elk gewenst moment beleid voor voorwaardelijke toegang toepassen en verwijderen. Als u wilt dat uw app blijft functioneren wanneer er een nieuw beleid wordt toegepast, moet u de afhandeling van de uitdaging implementeren. In de volgende voorbeelden ziet u de verwerking van uitdagingen.

Voorbeelden van voorwaardelijke toegang

Voor sommige scenario's zijn codewijzigingen vereist om voorwaardelijke toegang af te handelen, terwijl andere werken. Hier volgen enkele scenario's waarbij voorwaardelijke toegang wordt gebruikt om meervoudige verificatie uit te voeren die inzicht geeft 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 van 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 on-behalf-of-flow 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 app, die moet voldoen aan het beleid voor voorwaardelijke toegang.

Microsoft Graph

Microsoft Graph heeft speciale overwegingen bij het bouwen van apps in omgevingen met 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 waarop beleid afzonderlijk kan worden toegepast. Omdat beleid voor voorwaardelijke toegang wordt toegewezen aan de specifieke gegevenssets, dwingt Azure AD 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="Bookings.Read.All Mail.Read"

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

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 te bereiken.

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 reactie van Azure AD. Hier volgt een voorbeeld van deze uitdagingsparameter:

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

Ontwikkelaars kunnen deze uitdaging overnemen en toevoegen aan een nieuwe aanvraag in Azure AD. 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.

Scenario's

Vereisten

Voorwaardelijke toegang van Azure AD is een functie die is opgenomen in Azure AD Premium. Meer informatie over licentievereisten vindt u in het rapport gebruik zonder licentie. Ontwikkelaars kunnen deelnemen aan het Microsoft Developer Network, dat een gratis abonnement op enterprise Mobility Suite bevat, waaronder Azure AD Premium.

Overwegingen voor specifieke scenario's

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

  • Apps die de on-behalf-of-flow uitvoeren
  • Apps die toegang hebben tot meerdere services/resources
  • Apps met één pagina met ADAL.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: app voert de on-behalf-of-stroom uit

In dit scenario doorlopen we de case waarin een systeemeigen app een webservice/API aanroept. Op zijn beurt voert deze service de stroom 'namens' 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.

App performing the on-behalf-of flow diagram

De eerste 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 een token namens de gebruiker voor Web API 2 probeert aan te vragen, mislukt de aanvraag omdat de gebruiker zich niet heeft aangemeld met meervoudige verificatie.

Azure AD retourneert een HTTP-antwoord met enkele interessante gegevens:

Notitie

In dit geval is het een beschrijving van een meervoudige verificatiefout, maar er is een breed scala aan 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 wordt de fout error=interaction_requiredonderscheppen en wordt de claims uitdaging teruggestuurd naar de bureaublad-app. Op dat moment kan de bureaublad-app een nieuwe acquireToken() aanroep maken en de claimsuitdaging toevoegen als een extra queryreeksparameter. Voor deze nieuwe aanvraag moet de gebruiker meervoudige verificatie 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 een nieuwe aanvraag maakt in de client-app.

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 nodig heeft tot beide webservices. In dit scenario speelt de volgorde waarin u een token aanvraagt een belangrijke rol in de eindgebruikerservaring.

We gaan ervan uit dat we webservice A en B en webservice B hebben toegepast op ons beleid voor voorwaardelijke toegang. 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 voor webservice B aanvraagt, wordt het beleid aangeroepen en slaagt de volgende aanvragen voor webservice A ook als volgt.

App accessing multiple-services flow diagram

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 ervaring van de eindgebruiker beheren en niet afdwingen dat het beleid voor voorwaardelijke toegang in alle gevallen wordt aangeroepen. Het lastige geval is als de app vervolgens een token voor webservice B aanvraagt. Op dit moment moet de eindgebruiker voldoen aan het beleid voor voorwaardelijke toegang. Wanneer de app probeert te acquireTokenproberen, 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 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 app de ADAL-bibliotheek gebruikt, 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 in welk geval de app een interactieve AcquireToken aanvraag moet uitvoeren om de eindgebruiker de mogelijkheid te geven om te voldoen aan het beleid.

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

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

In ADAL.js zijn er enkele functies die tokens verkrijgen: login(), acquireToken(...), acquireTokenPopup(…), en acquireTokenRedirect(…).

  • login() haalt een id-token op via een interactieve aanmeldingsaanvraag, maar verkrijgt geen toegangstokens voor een service (inclusief een web-API die met voorwaardelijke toegang is beveiligd).
  • acquireToken(…) kan vervolgens 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 deze een acquireToken(…). Als de tokensessie is verlopen of we moeten voldoen aan een beleid voor voorwaardelijke toegang, mislukt de functie acquireToken en gebruikt de app acquireTokenPopup() of acquireTokenRedirect().

Single-page app using ADAL 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 login() aanroep uit en 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 acquireToken() aanroep uit te voeren, maar mislukt omdat de gebruiker nog geen meervoudige verificatie heeft uitgevoerd en moet voldoen aan het beleid voor voorwaardelijke toegang.

Azure AD 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 app moet de error=interaction_required. De toepassing kan vervolgens een acquireTokenPopup() of acquireTokenRedirect() dezelfde resource 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 ons JS SPA-voorbeeld namens code. In dit codevoorbeeld wordt gebruikgemaakt van het beleid voor voorwaardelijke toegang en de web-API die u eerder hebt geregistreerd bij een JS-BEVEILIGD-WACHTWOORDVERIFICATIE om dit scenario te demonstreren. Het laat zien hoe u de claimuitdaging correct kunt afhandelen en een toegangstoken kunt ophalen dat kan worden gebruikt voor uw web-API. U kunt ook het algemene codevoorbeeld voorAngular.js uitchecken voor hulp bij een Angular-BEVEILIGD-WACHTWOORDVERIFICATIE

Zie ook