Delen via

Bereiken en machtigingen in het Microsoft Identity Platform

  • Artikel

Het Microsoft Identity Platform implementeert het OAuth 2.0-autorisatieprotocol. OAuth 2.0 is een methode waarmee een app van derden namens een gebruiker toegang heeft tot door het web gehoste resources. Elke door het web gehoste resource die kan worden geïntegreerd met het Microsoft Identity Platform heeft een resource-id of toepassings-id-URI.

In dit artikel leert u over scopes en machtigingen in het identiteitsplatform.

In de volgende lijst ziet u enkele voorbeelden van door microsoft gehoste resources:

  • Microsoft Graph: https://graph.microsoft.com
  • Microsoft 365 Mail API: https://outlook.office.com
  • Azure Key Vault: https://vault.azure.net

Hetzelfde geldt voor alle resources van derden die kunnen worden geïntegreerd met het Microsoft Identity Platform. Elk van deze resources kan ook een set machtigingen definiëren waarmee de functionaliteit van die resource in kleinere segmenten wordt verdeeld. Als voorbeeld definieert Microsoft Graph machtigingen voor het uitvoeren van de volgende taken, onder andere:

  • De agenda van een gebruiker lezen
  • Schrijven naar de agenda van een gebruiker
  • E-mail verzenden als een gebruiker

Vanwege deze typen machtigingsdefinities heeft de resource gedetailleerde controle over de gegevens en hoe API-functionaliteit beschikbaar wordt gesteld. Een app van derden kan deze machtigingen aanvragen van gebruikers en beheerders die de aanvraag moeten goedkeuren voordat de app toegang heeft tot gegevens of namens een gebruiker actie kan ondernemen.

Wanneer de functionaliteit van een resource is onderverdeeld in kleine machtigingensets, kunnen apps van derden worden gebouwd om alleen de machtigingen aan te vragen die ze nodig hebben om hun functie uit te voeren. Gebruikers en beheerders kunnen weten tot welke gegevens de app toegang heeft. En ze kunnen er meer vertrouwen in hebben dat de app niet werkt met schadelijke bedoelingen. Ontwikkelaars moeten zich altijd houden aan het principe van minimale bevoegdheden en vragen om alleen de machtigingen die ze nodig hebben om hun toepassingen te laten functioneren.

In OAuth 2.0 worden deze typen machtigingensets bereiken genoemd. Ze worden ook wel machtigingen genoemd. In het Microsoft Identity Platform wordt een machtiging weergegeven als een tekenreekswaarde. Een app vraagt de benodigde machtigingen aan door de machtiging op te geven in de scope-queryparameter. Identiteitsplatform ondersteunt verschillende goed gedefinieerde OpenID Connect-bereiken en op resources gebaseerde machtigingen (elke machtiging wordt aangegeven door de machtigingswaarde toe te voegen aan de id of toepassings-id-URI van de resource). De machtigingstekenreeks https://graph.microsoft.com/Calendars.Read wordt bijvoorbeeld gebruikt om toestemming te vragen voor het lezen van agenda's van gebruikers in Microsoft Graph.

In aanvragen naar de autorisatieserver, voor het Microsoft Identity Platform, als de resource-id wordt weggelaten in de bereikparameter, wordt ervan uitgegaan dat de resource Microsoft Graph is. scope=User.Read is bijvoorbeeld gelijk aan https://graph.microsoft.com/User.Read.

Door beheerder beperkte machtigingen

Machtigingen in het Microsoft Identity Platform kunnen worden ingesteld op beperkingen voor beheerders. Voor veel microsoft Graph-machtigingen met een hogere bevoegdheid is bijvoorbeeld goedkeuring van de beheerder vereist. Als voor uw app beheerdersbeperkingen zijn vereist, moet de beheerder van een organisatie namens de gebruikers van de organisatie toestemming geven voor deze rechten. De volgende sectie bevat voorbeelden van dit soort machtigingen:

  • User.Read.All: Alle volledige profielen van de gebruiker lezen
  • Directory.ReadWrite.All: Gegevens schrijven naar de adreslijst van een organisatie
  • Groups.Read.All: Alle groepen lezen in de adreslijst van een organisatie

Notitie

In aanvragen voor de autorisatie-, token- of toestemmingseindpunten voor het Microsoft Identity Platform, als de resource-id wordt weggelaten in de bereikparameter, wordt ervan uitgegaan dat de resource Microsoft Graph is. scope=User.Read is bijvoorbeeld gelijk aan https://graph.microsoft.com/User.Read.

Hoewel een consumentgebruiker een toepassing toegang kan toekennen tot dit soort gegevens, kunnen organisatiegebruikers geen toegang toekennen tot dezelfde set gevoelige bedrijfsgegevens. Als uw toepassing toegang vraagt tot een van deze machtigingen van een organisatiegebruiker, ontvangt de gebruiker een foutbericht met de mededeling dat deze niet gemachtigd is om toestemming te geven voor de machtigingen van uw app.

Als de toepassing toepassingsmachtigingen aanvraagt en een beheerder deze machtigingen verleent, wordt deze toekenning niet namens een specifieke gebruiker uitgevoerd. In plaats daarvan krijgt de clienttoepassing rechtstreeks machtigingen. Deze typen machtigingen mogen alleen worden gebruikt door daemon-services en andere niet-interactieve toepassingen die op de achtergrond worden uitgevoerd. Zie Access-scenario's in het Microsoft Identity Platform voor meer informatie over het scenario voor directe toegang.

Zie Een toepassing configureren om een web-API beschikbaar te maken voor een stapsgewijze handleiding over het beschikbaar maken van bereiken in een web-API.

OpenID Connect-bereiken

De Microsoft Identity Platform-implementatie van OpenID Connect heeft een aantal goed gedefinieerde scopes die ook worden gehost in Microsoft Graph: openid, email, profile en offline_access. De address en phone OpenID Connect-bereiken worden niet ondersteund. Deze scopes zijn soms optioneel en worden gebruikt voor het verrijken van ID-tokens. Deze scopes worden niet altijd in afzonderlijke regels weergegeven in een toestemmingsprompt aan de gebruiker.

Als u de OpenID Connect-bereiken en een token aanvraagt, krijgt u een token om het eindpunt UserInfo aan te roepen.

Het openid bereik

Als een app zich aanmeldt met behulp van OpenID Connect, moet deze het openid-bereik aanvragen. Het openid-bereik wordt weergegeven op de toestemmingspagina van het werkaccount als de machtiging Aanmelden.

Een app gebruikt deze machtiging om een unieke id te ontvangen voor de gebruiker in de vorm van de sub claim. De machtiging geeft de app ook toegang tot het UserInfo-eindpunt. Het openid-bereik kan worden gebruikt op het Microsoft Identity Platform-tokeneindpunt om id-tokens te verkrijgen. De app kan deze tokens gebruiken voor verificatie.

Het email bereik

Het email-bereik kan worden gebruikt met het openid-bereik en eventuele andere bereiken. Hiermee krijgt de app toegang tot het primaire e-mailadres van de gebruiker in de vorm van de email-claim.

De email-claim is alleen opgenomen in een token als een e-mailadres is gekoppeld aan het gebruikersaccount, wat niet altijd het geval is. Als uw app het email-bereik gebruikt, moet de app een case kunnen afhandelen waarin geen email-claim in het token bestaat.

Het profile bereik

Het profile-bereik kan worden gebruikt met het openid-bereik en een eventueel ander bereik. Hiermee krijgt de app toegang tot een grote hoeveelheid informatie over de gebruiker. De informatie waartoe deze toegang heeft, omvat, maar niet beperkt tot, de opgegeven naam, achternaam, voorkeursnaam en object-id van de gebruiker.

Voor een volledige lijst van de profile-claims die beschikbaar zijn in de id_tokens-parameter voor een specifieke gebruiker, raadpleegt u de id_tokens-referentie.

Het offline_access bereik

Het offline_access-bereik geeft uw app gedurende langere tijd toegang tot resources namens de gebruiker. Op de toestemmingspagina wordt dit bereik weergegeven als de machtiging Toegang behouden tot gegevens waartoe u toegang hebt verleend.

Als een van de aangevraagde gedelegeerde machtigingen van de parameter scope (met uitzondering van openid, profile, email) wordt verleend, is dit voldoende voor de app om een vernieuwingstoken aan te vragen met behulp van offline_access. Als bijvoorbeeld User.Read voor Microsoft wordt verleend, ontvangt de app alleen een toegangstoken. Dat gezegd hebbende, als de app vervolgens een refresh-token zou aanvragen, is het feit dat User.Read is verleend voldoende om een refresh-token te verstrekken. Refresh tokens, oftewel vernieuwingstokens, hebben een lange levensduur. Uw app kan nieuwe toegangstokens krijgen wanneer de oude verlopen.

Notitie

Deze toestemming wordt momenteel weergegeven op alle toestemmingspagina's, zelfs voor processen die geen verversingstoken verstrekken (zoals de impliciete stroom). Met deze configuratie worden scenario's behandeld waarin een client kan beginnen binnen de impliciete flow en vervolgens doorgaat naar de code flow, waar een refresh token wordt verwacht.

Op het Microsoft Identity Platform (aanvragen ingediend voor het v2.0-eindpunt) moet uw app expliciet het offline_access-bereik aanvragen om vernieuwingstokens te ontvangen. Dus wanneer u een autorisatiecode inwisselt in de OAuth 2.0-autorisatiecodestroom, ontvangt u een toegangstoken van het /token-eindpunt.

Het toegangstoken is ongeveer één uur geldig. Op dat moment moet uw app de gebruiker omleiden naar het /authorize eindpunt om een nieuwe autorisatiecode aan te vragen. Tijdens deze omleiding en afhankelijk van het app-type moet de gebruiker mogelijk opnieuw referenties invoeren of opnieuw toestemming geven voor machtigingen.

Het vernieuwingstoken heeft een langere vervaldatum dan het toegangstoken en is doorgaans 90 dagen geldig. Zie de Microsoft identity platform protocolreferentie voor informatie over het verkrijgen en gebruiken van refresh tokens.

De inclusie van het refresh-token in het antwoord kan afhankelijk zijn van verschillende factoren, waaronder de specifieke configuratie van uw toepassing en de scopes die tijdens het autorisatieproces zijn aangevraagd. Als u verwacht een vernieuwingstoken in het antwoord te ontvangen, maar dit niet lukt, moet u rekening houden met de volgende factoren:

  • Scopevereisten: Zorg ervoor dat u de offline_access scopes aanvraagt samen met alle andere benodigde scopes.
  • autorisatietoekenningstype: het vernieuwingstoken wordt opgegeven bij het gebruik van het type autorisatiecodetoekenning. Als uw stroom verschilt, kan dit van invloed zijn op het antwoord.
  • Clientconfiguratie: Controleer de instellingen van uw toepassing in het identiteitsplatform. Bepaalde configuraties kunnen de uitgifte van refresh_tokens beperken.

Het .default bereik

Het bereik .default wordt gebruikt om algemeen te verwijzen naar een resourceservice (API) in een aanvraag, zonder specifieke machtigingen te identificeren. Als toestemming nodig is, zorgt het gebruik van .default ervoor dat toestemming moet worden gevraagd voor alle vereiste machtigingen die worden vermeld in de registratie van de toepassing (voor alle API's in de lijst).

De waarde van de bereikparameter wordt samengesteld met behulp van de identificatie-URI voor de resource en .default, gescheiden door een schuine streep (/). Als de id-URI van de resource bijvoorbeeld is https://contoso.com, is https://contoso.com/.default het bereik dat moet worden aangevraagd. Zie de sectie over afsluitende schuine strepen voor situaties waarin u een tweede schuine streep moet opnemen om het token correct aan te vragen.

Het gebruik van scope={resource-identifier}/.default is functioneel hetzelfde als resource={resource-identifier} op het v1.0-eindpunt (waarbij {resource-identifier} de id-URI voor de API is, bijvoorbeeld https://graph.microsoft.com voor Microsoft Graph).

Het bereik .default kan worden gebruikt in elke OAuth 2.0-stroom en om beheerderstoestemming te initiëren. Het gebruik ervan is vereist in de On-Behalf-Of-stroom en clientreferentiestroom.

Clients kunnen geen statische (.default) toestemming en dynamische toestemming combineren in één aanvraag. scope=https://graph.microsoft.com/.default Mail.Read resulteert in een fout omdat het bereiktypen combineert.

De .default bereikparameter activeert alleen een toestemmingsprompt als er geen toestemming is verleend voor gedelegeerde machtigingen tussen de client en de resource, namens de aangemelde gebruiker.

Als er toestemming bestaat, bevat het geretourneerde token alle scopes die zijn verleend voor die resource voor de ingelogde gebruiker. Als er echter geen machtiging is verleend voor de aangevraagde resource (of als de parameter prompt=consent is opgegeven), wordt er een toestemmingsprompt weergegeven voor alle vereiste machtigingen die zijn geconfigureerd voor de registratie van de clienttoepassing, voor alle API's in de lijst.

Als het bereik https://graph.microsoft.com/.default bijvoorbeeld wordt aangevraagd, vraagt uw toepassing een toegangstoken aan voor de Microsoft Graph API. Als ten minste één gedelegeerde machtiging is verleend voor Microsoft Graph namens de aangemelde gebruiker, wordt de aanmelding voortgezet. Alle gedelegeerde Microsoft Graph-machtigingen die zijn verleend voor die gebruiker, worden opgenomen in het toegangstoken. Als er geen machtigingen zijn verleend voor de aangevraagde resource (Microsoft Graph in dit voorbeeld), wordt er een toestemmingsprompt weergegeven voor alle vereiste machtigingen die zijn geconfigureerd voor de toepassing, voor alle API's in de lijst.

Voorbeeld 1: De gebruiker of tenantbeheerder heeft machtigingen toegekend

In dit voorbeeld heeft de gebruiker of een tenantbeheerder de Mail.Read en User.Read Microsoft Graph-machtigingen aan de client toegekend.

Als de client scope=https://graph.microsoft.com/.default aanvraagt, wordt er geen toestemmingsprompt weergegeven, ongeacht de inhoud van de geregistreerde machtigingen van de clienttoepassing voor Microsoft Graph. Het geretourneerde token bevat de scopes Mail.Read en User.Read.

Voorbeeld 2: De gebruiker heeft geen machtigingen toegekend tussen de client en de resource

In dit voorbeeld heeft de gebruiker geen toestemming toegekend tussen de client en Microsoft Graph, en een beheerder ook niet. De client registreerde zich voor de machtigingen User.Read en Contacts.Read en voor het bereik van Azure Key Vault https://vault.azure.net/user_impersonation.

Wanneer de client een token voor scope=https://graph.microsoft.com/.default aanvraagt, ziet de gebruiker een toestemmingspagina voor de Microsoft Graph-bereiken User.Read en Contacts.Read en voor het Azure Key Vault-bereik user_impersonation. Het geretourneerde token bevat alleen de bereiken User.Read en Contacts.Read en kan alleen worden gebruikt voor Microsoft Graph.

Voorbeeld 3: De gebruiker heeft toestemming gegeven en de applicatie vraagt om meer toestemmingen

In dit voorbeeld heeft de gebruiker al toestemming gegeven voor Mail.Read voor de client. De klant heeft zich geregistreerd voor bereik Contacts.Read.

De client voert eerst een aanmelding uit met scope=https://graph.microsoft.com/.default. Op basis van de parameter scopes van het antwoord detecteert de code van de toepassing dat alleen Mail.Read is verleend. De client initieert vervolgens een tweede aanmelding met behulp van scope=https://graph.microsoft.com/.default, en dwingt deze keer toestemming af met behulp van prompt=consent. Als de gebruiker toestemming mag geven voor alle machtigingen die de toepassing heeft geregistreerd, wordt de toestemmingsprompt weergegeven. (Zo niet, wordt een foutbericht weergegeven of het beheerderstoestemmingsaanvraag formulier.) Zowel Contacts.Read als Mail.Read staan in de toestemmingsprompt. Als toestemming wordt toegekend en de aanmelding wordt voortgezet, wordt het token geretourneerd voor Microsoft Graph en bevat het Mail.Read en Contacts.Read.

.default Het bereik gebruiken met de client

In sommige gevallen kan een client een eigen .default-bereik aanvragen. In het volgende voorbeeld wordt dit scenario gedemonstreerd.

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
    ?response_type=token            //Code or a hybrid flow is also possible here
    &client_id=00001111-aaaa-2222-bbbb-3333cccc4444
    &scope=9ada6f8a-6d83-41bc-b169-a306c21527a5/.default
    &redirect_uri=https%3A%2F%2Flocalhost
    &state=1234

Dit codevoorbeeld produceert een toestemmingspagina voor alle geregistreerde machtigingen als de voorgaande beschrijvingen van toestemming en .default van toepassing zijn op het scenario. Vervolgens retourneert de code een id_token, in plaats van een toegangstoken.

Nieuwe clients die gericht zijn op het Microsoft Identity Platform mogen deze installatie niet gebruiken. Zorg ervoor dat u van de Azure AD Authentication Library (ADAL) migreert naar de Microsoft Authentication Library (MSAL).

Stroom voor het verlenen van clientreferenties en .default

Een ander gebruik van .default is het aanvragen van app-rollen (ook wel toepassingsmachtigingen genoemd) in een niet-interactieve toepassing, zoals een daemon-app die gebruikmaakt van de toekenningsstroom voor clientreferenties om een web-API aan te roepen.

Zie App-rollen toevoegen in uw toepassing om app-rollen (toepassingsmachtigingen) voor een web-API te definiëren.

Bij aanvragen voor klantgegevens in uw clientservice moetscope={resource}/.default zijn opgenomen. Hier is {resource} de web-API die uw app wil aanroepen en waarvoor u een toegangstoken wilt verkrijgen. Het uitgeven van een aanvraag voor clientreferenties met behulp van afzonderlijke toepassingsmachtigingen (rollen) wordt niet ondersteund. Alle app-rollen (toepassingsmachtigingen) die zijn verleend voor die web-API, worden opgenomen in het geretourneerde toegangstoken.

Zie Een clienttoepassing configureren voor toegang tot een web-API om toegang toe te kennen voor de app-rollen die u definieert, inclusief het verlenen van beheerderstoestemming voor de toepassing.

Slash aan het einde en .default

Sommige resource-URI's hebben bijvoorbeeld een afsluitende schuine slash, https://contoso.com/ in plaats van https://contoso.com. De afsluitende slash kan problemen veroorzaken met tokenvalidatie. Er treden voornamelijk problemen op wanneer een token wordt aangevraagd voor Azure Resource Manager (https://management.azure.com/).

In dit geval betekent een afsluitende slash op de resource-URI dat de slash aanwezig moet zijn wanneer het token wordt aangevraagd. Dus wanneer u een token aanvraagt voor https://management.azure.com/ en .default gebruikt, moet u een aanvraag indienen https://management.azure.com//.default (let op de dubbele slash!).

Over het algemeen, als u controleert of het token wordt uitgegeven en het token wordt geweigerd door de API die het zou moeten accepteren, kunt u overwegen een tweede schuine streep toe te voegen en het opnieuw te proberen.

Zie ook