Machtigingen aanvragen via toestemming

  • Artikel

Toepassingen in het Microsoft Identity Platform zijn afhankelijk van toestemming om toegang te krijgen tot de benodigde resources of API's. Verschillende soorten toestemming zijn beter voor verschillende toepassingsscenario's. Het kiezen van de beste methode om toestemming voor uw app te geven, helpt het om succesvoller te zijn met gebruikers en organisaties.

In dit artikel leert u meer over de verschillende soorten toestemming en hoe u machtigingen voor uw toepassing aanvraagt via toestemming.

In het scenario voor statische gebruikerstoestemming moet u alle machtigingen opgeven die nodig zijn in de configuratie van de app in het Microsoft Entra-beheercentrum. Als de gebruiker (of beheerder, indien van toepassing) geen toestemming heeft verleend voor deze app, wordt de gebruiker op dit moment gevraagd om toestemming te geven.

Met statische machtigingen kunnen beheerders ook toestemming geven namens alle gebruikers in de organisatie.

Hoewel u afhankelijk bent van statische toestemming en één lijst met machtigingen de code mooi en eenvoudig houdt, betekent dit ook dat uw app alle machtigingen aanvraagt die deze ooit nodig heeft. Dit kan gebruikers en beheerders ontmoedigen om de toegangsaanvraag van uw app goed te keuren.

Met het Microsoft Identity Platform-eindpunt kunt u de statische machtigingen negeren die zijn gedefinieerd in de registratiegegevens van de toepassing in het Microsoft Entra-beheercentrum. In plaats daarvan kunt u incrementeel machtigingen aanvragen. U kunt vooraf om een nauwelijks minimale set machtigingen vragen en meer aanvragen in de loop van de tijd, omdat de klant aanvullende toepassingsfuncties gebruikt. Hiervoor kunt u op elk gewenst moment de bereiken opgeven die uw toepassing nodig heeft door de nieuwe bereiken in de parameter op te slaan bij het scope aanvragen van een toegangstoken, zonder dat u ze vooraf hoeft te definiëren in de registratiegegevens van de toepassing. Als de gebruiker nog geen toestemming heeft gegeven voor nieuwe bereiken die aan de aanvraag zijn toegevoegd, wordt de gebruiker gevraagd alleen toestemming te geven voor de nieuwe machtigingen. Incrementele of dynamische toestemming is alleen van toepassing op gedelegeerde machtigingen en niet op toepassingsmachtigingen.

Het toestaan van een toepassing om machtigingen dynamisch aan te vragen via de scope parameter biedt ontwikkelaars volledige controle over de gebruikerservaring. U kunt uw toestemmingservaring ook vooraf laden en vragen om alle machtigingen in één eerste autorisatieaanvraag. Als uw toepassing een groot aantal machtigingen vereist, kunt u deze machtigingen incrementeel van de gebruiker verzamelen wanneer ze bepaalde functies van de toepassing in de loop van de tijd proberen te gebruiken.

Belangrijk

Dynamische toestemming kan handig zijn, maar is een grote uitdaging voor machtigingen waarvoor beheerderstoestemming vereist is. De ervaring met beheerderstoestemming in de blades App-registraties en Bedrijfstoepassingen in de portal weet niet over deze dynamische machtigingen op het moment van toestemming. Het is raadzaam dat een ontwikkelaar alle machtigingen met beheerdersbevoegdheden vermeldt die nodig zijn voor de toepassing in de portal. Hierdoor kunnen tenantbeheerders één keer toestemming geven namens alle gebruikers in de portal. Gebruikers hoeven de toestemmingservaring niet te doorlopen voor deze machtigingen bij het aanmelden. Het alternatief is het gebruik van dynamische toestemming voor deze machtigingen. Als u beheerderstoestemming wilt verlenen, meldt een individuele beheerder zich aan bij de app, activeert u een toestemmingsprompt voor de juiste machtigingen en selecteert u toestemming voor mijn hele organisatie in het toestemmingsdialoogvenster.

In een OpenID-Verbinding maken- of OAuth 2.0-autorisatieaanvraag kan een toepassing de benodigde machtigingen aanvragen met behulp van de scope queryparameter. Wanneer een gebruiker zich bijvoorbeeld aanmeldt bij een app, verzendt de toepassing een aanvraag zoals in het volgende voorbeeld. (Regeleinden worden toegevoegd voor leesbaarheid).

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=
https%3A%2F%2Fgraph.microsoft.com%2Fcalendars.read%20
https%3A%2F%2Fgraph.microsoft.com%2Fmail.send
&state=12345

De scope parameter is een door spaties gescheiden lijst met gedelegeerde machtigingen die de toepassing aanvraagt. Elke machtiging wordt aangegeven door de machtigingswaarde toe te voegen aan de id van de resource (de URI van de toepassings-id). In het aanvraagvoorbeeld heeft de toepassing toestemming nodig om de agenda van de gebruiker te lezen en e-mail te verzenden als de gebruiker.

Nadat de gebruiker zijn referenties heeft ingevoerd, controleert het Microsoft Identity Platform op een overeenkomende record met gebruikerstoestemming. Als de gebruiker geen toestemming heeft gegeven voor een van de aangevraagde machtigingen in het verleden en als de beheerder niet namens de hele organisatie toestemming heeft gegeven voor deze machtigingen, vraagt het Microsoft Identity Platform de gebruiker om de aangevraagde machtigingen toe te kennen.

In het volgende voorbeeld wordt de offline_access machtiging 'Toegang tot gegevens behouden waaraan u toegang hebt verleend') en User.Read de machtiging 'Aanmelden en uw profiel lezen' automatisch opgenomen in de eerste toestemming voor een toepassing. Deze machtigingen zijn vereist voor de juiste toepassingsfunctionaliteit. De offline_access machtiging geeft de toepassing toegang tot vernieuwingstokens die essentieel zijn voor systeemeigen apps en web-apps. De machtiging User.Read geeft toegang tot de sub-claim. Hiermee kan de client of toepassing de gebruiker na verloop van tijd correct identificeren en toegang krijgen tot elementaire gebruikersgegevens.

Voorbeeldschermopname met toestemming voor werkaccount.

Wanneer de gebruiker de machtigingsaanvraag goedkeurt, wordt toestemming vastgelegd. De gebruiker hoeft niet opnieuw toestemming te geven wanneer hij zich later aanmeldt bij de toepassing.

Voor het aanvragen van toestemming voor een hele tenant is beheerderstoestemming vereist. Beheerderstoestemming namens een organisatie vereist dat de statische machtigingen zijn geregistreerd voor de app. Stel deze machtigingen in de portal voor app-registratie in als u een beheerder nodig hebt om namens de hele organisatie toestemming te geven.

Wanneer uw toepassing gedelegeerde machtigingen aanvraagt waarvoor beheerderstoestemming is vereist, ontvangt de gebruiker een foutbericht met de melding dat deze niet gemachtigd is om toestemming te geven voor de machtigingen van uw app. De gebruiker moet de beheerder vragen om toegang tot de app. Als de beheerder toestemming verleent voor de hele tenant, zien de gebruikers van de organisatie geen toestemmingspagina voor de toepassing, tenzij de eerder verleende machtigingen worden ingetrokken of als de toepassingsaanvragen voor een nieuwe machtiging incrementeel worden ingetrokken.

Beheer istrators die dezelfde toepassing gebruiken, wordt de beheerderstoestemmingsprompt weergegeven. De beheerderstoestemmingsprompt biedt een selectievakje waarmee ze de toepassing toegang kunnen verlenen tot de aangevraagde gegevens namens de gebruikers voor de hele tenant. Zie De ervaring voor toepassingstoestemming voor meer informatie over de ervaring voor toestemming van gebruikers en beheerders.

Voorbeelden van gedelegeerde machtigingen voor Microsoft Graph waarvoor beheerderstoestemming is vereist, zijn:

  • Lees de volledige profielen van alle gebruikers met behulp van User.Read.All
  • Gegevens schrijven naar de adreslijst van een organisatie met behulp van Directory.ReadWrite.All
  • Alle groepen in de adreslijst van een organisatie lezen met behulp van Groups.Read.All

Als u de volledige lijst met Machtigingen voor Microsoft Graph wilt bekijken, raadpleegt u de referentie voor Microsoft Graph-machtigingen.

U kunt ook machtigingen voor uw eigen resources configureren om beheerderstoestemming te vereisen. Zie Een bereik toevoegen waarvoor beheerderstoestemming is vereist voor meer informatie over het toevoegen van bereiken waarvoor beheerderstoestemming is vereist.

Sommige organisaties kunnen het standaardbeleid voor gebruikerstoestemming voor de tenant wijzigen. Wanneer uw toepassing toegang vraagt tot machtigingen, worden ze geëvalueerd op basis van dit beleid. De gebruiker moet mogelijk beheerderstoestemming aanvragen, zelfs als dit niet standaard is vereist. Zie App-toestemmingsbeleid beheren voor meer informatie over hoe beheerders toestemmingsbeleid voor toepassingen beheren.

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.

Voor toepassingsmachtigingen is altijd beheerderstoestemming vereist. Toepassingsmachtigingen hebben geen gebruikerscontext en de toestemmingstoekenning wordt niet uitgevoerd namens een specifieke gebruiker. In plaats daarvan wordt de clienttoepassing rechtstreeks machtigingen verleend. Deze typen machtigingen worden alleen gebruikt door daemon-services en andere niet-interactieve toepassingen die op de achtergrond worden uitgevoerd. Beheer istrators moeten de machtigingen vooraf configureren en beheerderstoestemming verlenen via het Microsoft Entra-beheercentrum.

Als de toepassing die de machtiging aanvraagt een toepassing met meerdere tenants is, bestaat de toepassingsregistratie alleen in de tenant waar deze is gemaakt. Daarom kunnen machtigingen niet worden geconfigureerd in de lokale tenant. Als de toepassing machtigingen aanvraagt waarvoor beheerderstoestemming is vereist, moet de beheerder toestemming geven namens de gebruikers. Als u toestemming wilt geven voor deze machtigingen, moeten de beheerders zich aanmelden bij de toepassing zelf, zodat de aanmeldingservaring voor beheerderstoestemming wordt geactiveerd. Zie Log-ins met meerdere tenants inschakelen voor meer informatie over het instellen van de ervaring voor beheerderstoestemming voor toepassingen met meerdere tenants

Een beheerder kan toestemming verlenen voor een toepassing met de volgende opties.

Wanneer u een toepassing bouwt waarvoor beheerderstoestemming is vereist, heeft de toepassing een pagina of weergave nodig waarin de beheerder de machtigingen van de app kan goedkeuren. Deze pagina kan het volgende zijn:

  • Een deel van de registratiestroom van de app.
  • Deel van de instellingen van de app.
  • Een toegewezen stroom 'verbinding maken'.

In veel gevallen is het logisch dat de toepassing de weergave 'Verbinding maken' alleen weergeeft nadat een gebruiker zich heeft aangemeld met een werk-Microsoft-account of schoolaccount van Microsoft.

Wanneer u de gebruiker aanmeldt bij uw app, kunt u de organisatie identificeren waartoe de beheerder behoort voordat u hen vraagt de benodigde machtigingen goed te keuren. Hoewel deze stap niet strikt noodzakelijk is, kunt u hiermee een intuïtievere ervaring maken voor uw gebruikers van uw organisatie.

Volg de Microsoft Identity Platform-protocolzelfstudies om de gebruiker aan te melden.

De machtigingen aanvragen in de portal voor app-registratie

In de portal voor app-registratie kunnen toepassingen de machtigingen vermelden die ze nodig hebben, inclusief gedelegeerde machtigingen en toepassingsmachtigingen. Met deze instelling kan het .default bereik en de optie Beheerderstoestemming verlenen door het Microsoft Entra-beheercentrum worden gebruikt.

Over het algemeen moeten de machtigingen statisch worden gedefinieerd voor een bepaalde toepassing. Ze moeten een superset zijn van de machtigingen die de toepassing dynamisch of incrementeel aanvraagt.

Notitie

Toepassingsmachtigingen kunnen alleen worden aangevraagd via het gebruik van .default. Dus als uw toepassing toepassingsmachtigingen nodig heeft, moet u ervoor zorgen dat deze worden vermeld in de portal voor app-registratie.

De lijst met statisch aangevraagde machtigingen voor een toepassing configureren:

  1. Meld u aan bij het Microsoft Entra-beheercentrum als ten minste een cloudtoepassing Beheer istrator.
  2. Blader naar Identiteitstoepassingen>> App-registraties> Alle toepassingen.
  3. Selecteer een toepassing of maak een app als u dat nog niet hebt gedaan.
  4. Selecteer op de pagina Overzicht van de toepassing, onder Beheren, API-machtigingen>Een machtiging toevoegen.
  5. Selecteer Microsoft Graph in de lijst met beschikbare API's. Voeg vervolgens de machtigingen toe die uw toepassing nodig heeft.
  6. Selecteer Machtigingen toevoegen.

Succesvolle respons

Als de beheerder de machtigingen voor uw app goedkeurt, ziet het geslaagde antwoord er als volgt uit:

GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True
Parameter Description
tenant De directorytenant die uw toepassing de benodigde machtigingen heeft toegekend, in GUID-indeling.
state Een waarde die is opgenomen in de aanvraag die ook wordt geretourneerd in het tokenantwoord. Het kan een tekenreeks zijn van elke door u gewenste inhoud. De status wordt gebruikt om informatie over de status van de gebruiker in de toepassing te coderen voordat de verificatieaanvraag is opgetreden, zoals de pagina of weergave waarop deze zich bevonden.
admin_consent Wordt ingesteld op True.

Nadat u een geslaagd antwoord hebt ontvangen van het eindpunt voor beheerderstoestemming, heeft uw toepassing de benodigde machtigingen gekregen. Vervolgens kunt u een token aanvragen voor de gewenste resource.

Foutrespons

Als de beheerder de machtigingen voor uw app niet goedkeurt, ziet het mislukte antwoord er als volgt uit:

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
Parameter Description
error Een foutcodereeks die kan worden gebruikt voor het classificeren van typen fouten die optreden. Deze kan ook worden gebruikt om te reageren op fouten.
error_description Een specifiek foutbericht waarmee een ontwikkelaar de hoofdoorzaak van een fout kan identificeren.

Nadat de gebruiker toestemming heeft gegeven voor machtigingen voor uw app, kan uw toepassing toegangstokens verkrijgen die de machtiging van de app vertegenwoordigen voor toegang tot een resource in een bepaalde capaciteit. Een toegangstoken kan slechts voor één resource worden gebruikt. Maar gecodeerd in het toegangstoken is elke machtiging die uw toepassing voor die resource heeft gekregen. Als u een toegangstoken wilt verkrijgen, kan uw toepassing een aanvraag indienen bij het Eindpunt van het Microsoft Identity Platform-token, zoals deze:

POST common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/json

{
    "grant_type": "authorization_code",
    "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "scope": "https://microsoft.graph.com/Mail.Read https://microsoft.graph.com/mail.send",
    "code": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...",
    "redirect_uri": "https://localhost/myapp",
    "client_secret": "A1bC2dE3f..."  // NOTE: Only required for web apps
}

U kunt het resulterende toegangstoken gebruiken in HTTP-aanvragen voor de resource. Het geeft op betrouwbare wijze aan dat uw toepassing over de juiste machtiging beschikt om een specifieke taak uit te voeren.

Zie de Naslaginformatie over het Microsoft Identity Platform-eindpuntprotocol voor meer informatie over het OAuth 2.0-protocol en het verkrijgen van toegangstokens.

Zie ook