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 krijgt u informatie over bereiken 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 zijn geïntegreerd met het Microsoft Identity Platform. Elk van deze resources kan ook een set machtigingen definiëren die kunnen worden gebruikt om de functionaliteit van die resource te verdelen in kleinere segmenten. Microsoft Graph heeft bijvoorbeeld machtigingen gedefinieerd voor het uitvoeren van onder andere de volgende taken:

  • 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-Verbinding maken bereiken en machtigingen op basis van resources (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 beheerders beperkt. Voor veel microsoft Graph-machtigingen met een hogere bevoegdheid is bijvoorbeeld goedkeuring van de beheerder vereist. Als voor uw app beheerdersmachtigingen zijn vereist, moet de beheerder van een organisatie namens de gebruikers van de organisatie toestemming geven voor deze bereiken. 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 stapsgewijze instructies voor 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 bereiken die ook worden gehost in Microsoft Graph: openid, email, profile en offline_access. De address en phone OpenID Connect-bereiken worden niet ondersteund.

Als u de OpenID Connect-bereiken en een token aanvraagt, krijgt u een token om het UserInfo-eindpunt 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.

Met deze machtiging kan een app een unieke id voor de gebruiker ontvangen 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.

Wanneer een gebruiker het offline_access-bereik goedkeurt, kan uw app vernieuwingstokens ontvangen van het Microsoft Identity Platform-tokeneindpunt. Vernieuwingstokens hebben een lange levensduur. Uw app kan nieuwe toegangstokens krijgen wanneer oudere verlopen.

Notitie

Deze machtiging wordt momenteel weergegeven op alle toestemmingspagina's, zelfs voor stromen die geen vernieuwingstoken bieden (zoals de impliciete stroom). Met deze installatie worden scenario's besproken waarin een client binnen de impliciete stroom kan beginnen en vervolgens naar de codestroom gaat waar een vernieuwingstoken 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 alleen een toegangstoken van het /token eindpunt.

Het toegangstoken is meestal 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 meestal een dag geldig. Zie de naslaginformatie Microsoft Identity Platform-protocol voor meer informatie over het ophalen en gebruiken van vernieuwingstokens.

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 id-URI voor de resource en .default, gescheiden door een slash (/). 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 slashes voor gevallen waarin u een tweede slash 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 stroom Namens-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 bereiken die zijn verleend voor die resource voor de aangemelde 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 en worden alle gedelegeerde machtigingen van Microsoft Graph opgenomen in het toegangstoken. Als er geen machtigingen zijn toegekend 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 bereiken 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 heeft zich geregistreerd voor de machtigingen User.Read en Contacts.Read. Deze heeft zich ook geregistreerd voor het Azure Key Vault-bereik 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 client vraagt meer bereiken aan

In dit voorbeeld heeft de gebruiker al toestemming gegeven voor Mail.Read voor de client. De client heeft zich geregistreerd voor het 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. (Als dat niet het probleem is, krijgen ze een foutbericht of het formulier voor het verzoek om toestemming van de beheerder.) Beide Contacts.Read en Mail.Read bevinden zich 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.

Deze installatie mag niet worden gebruikt door nieuwe clients die zich richten op het Microsoft Identity Platform. Zorg ervoor dat u migreert naar de Microsoft Authentication Library (MSAL) vanuit Azure AD Authentication Library (ADAL).

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.

In aanvragen voor clientreferenties 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.

Afsluitende slash 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!).

Als u in het algemeen controleert of het token wordt uitgegeven en als het token wordt geweigerd door de API die het moet accepteren, kunt u overwegen een tweede slash toe te voegen en het opnieuw te proberen.

Zie ook