Delen via

Ontwikkelaarshandleiding voor het aanvragen van machtigingen en toestemming in Microsoft Identity Platform

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. Als u de beste methode kiest om toestemming te geven voor uw app, kan de app succesvoller 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.

Opmerking

Voor toepassingen binnen externe tenants kunnen klanten niet zelf toestemming geven voor machtigingen. Een beheerder moet toestemming verlenen voor de toepassing om namens hen toegang te krijgen tot resources. Voor meer informatie, zie Beheerderstoestemming verlenen.

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 verleent voor deze app, vraagt Het Microsoft Identity Platform de gebruiker op dit moment 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. Deze instelling 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 dynamisch machtigingen aanvragen vanuit de code van de toepassing. U kunt beginnen met het vragen om een minimale set machtigingen vooraf en anderen in de loop van de tijd vragen naarmate de klant meer toepassingsfuncties gebruikt. Hiervoor kunt u op elk gewenst moment de bereiken opgeven die uw toepassing nodig heeft door de bereiken in de parameter op te slaan bij het scopeaanvragen van een toegangstoken , zonder dat u deze vooraf hoeft te bepalen in de registratiegegevens van de toepassing.

Als de gebruiker geen toestemming heeft gegeven voor een van de toestemmingen in de aanvraag, krijgt de gebruiker een melding om toestemming te verlenen voor alle machtigingen in die aanvraag. Deze worden verleend naast eventuele andere machtigingen die al zijn verleend voor die app (bijvoorbeeld incrementeel). Incrementele toestemming, geldt alleen voor gedelegeerde machtigingen en niet voor toepassingsmachtigingen.

Het toestaan van een toepassing om machtigingen dynamisch aan te vragen via de scope parameter biedt ontwikkelaars volledige controle over de gebruikerservaring. U behandelt de toestemmingsprocedure vooraf en vraagt om alle toestemmingen in één eerste autorisatieverzoek. 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 biedt een aanzienlijke uitdaging voor machtigingen waarvoor beheerderstoestemming is vereist. De beheerderstoestemmingsproces in de blades App-registraties en Bedrijfstoepassingen in de portal is zich niet bewust van deze dynamische permissies tijdens de toestemmingsprocedure. Het is raadzaam dat een ontwikkelaar alle machtigingen met beheerdersbevoegdheden vermeldt die de toepassing nodig heeft in de portal.

Hierdoor kunnen tenantbeheerders eenmaal toestemming geven namens alle gebruikers in de portal. Gebruikers hoeven de toestemmingservaring niet te doorlopen voor deze machtigingen bij het aanmelden. Het alternatief is om dynamische toestemming te gebruiken voor deze machtigingen. Als u beheerderstoestemming wilt verlenen, meldt een afzonderlijke beheerder zich aan bij de app, activeert u een toestemmingsprompt voor de juiste machtigingen en selecteert u toestemming voor mijn hele organisatie in de toestemmingsdialoog.

In een OpenID Connect- 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.

Na aanmelding controleert het Microsoft Identity Platform op bestaande gebruikerstoestemming. Als de gebruiker de aangevraagde machtigingen niet goedkeurt en een beheerder deze ook niet goedkeurt, vraagt het platform de gebruiker toestemming te geven.

In het volgende voorbeeld wordt de offline_access machtiging 'Toegang behouden tot gegevens waarnaar u toegang verleent') en User.Read 'Meld u aan en lees uw profiel') 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 User.Read machtiging 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.

Voorbeeld van een schermafbeelding die de toestemming voor werkaccounts toont.

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

Voor het aanvragen van toestemming voor een hele tenant is beheerderstoestemming vereist. Beheerderstoestemming die namens een organisatie wordt uitgevoerd, vereist de statische machtigingen die 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 app gedelegeerde machtigingen aanvraagt waarvoor beheerderstoestemming is vereist, zien gebruikers de foutmelding 'niet gemachtigd om toestemming te geven' en moeten ze een beheerder om toegang vragen. Zodra een beheerder toestemming verleent voor de hele tenant, worden gebruikers niet opnieuw gevraagd, tenzij toestemming wordt ingetrokken of nieuwe machtigingen worden toegevoegd.

Beheerders die dezelfde toepassing gebruiken, zien de beheerderstoestemmingsprompt. 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

Zie de naslaginformatie over Microsoft Graph-machtigingen om de volledige lijst met Microsoft Graph-machtigingen weer te geven.

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 wanneer deze niet standaard is vereist. Zie App-toestemmingsbeleid beheren voor meer informatie over hoe beheerders toestemmingsbeleid voor toepassingen beheren.

Opmerking

In autorisatie-, token- of toestemmingsaanvragen van het Microsoft identity platform resulteert het weglaten van de resource-id in de scope-parameter in een standaardinstelling voor Microsoft Graph. Wordt bijvoorbeeld scope=User.Read behandeld als 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 krijgt de clienttoepassing rechtstreeks machtigingen. Deze typen machtigingen worden alleen gebruikt door daemon-services en andere niet-interactieve toepassingen die op de achtergrond worden uitgevoerd. Beheerders moeten de machtigingen vooraf configureren en beheerders toestemming verlenen via het Microsoft Entra-beheercentrum.

Als de toepassing die de machtiging aanvraagt een multitenant-toepassing 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 zelf aanmelden bij de toepassing, zodat de aanmeldingservaring voor beheerderstoestemming wordt geactiveerd. Zie Multitenant-aanmeldingen inschakelen voor meer informatie over het instellen van de ervaring voor beheerderstoestemming voor multitenant-toepassingen

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:

  • Onderdeel van de registratiestroom van de app.
  • Onderdeel van de instellingen van de app.
  • Een speciaal ontworpen verbindingsproces.

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

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 creëren voor uw gebruikers van uw organisatie.

Volg de stappen voor het Microsoft identity platform-protocol 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.

Opmerking

Toepassingsmachtigingen kunnen alleen worden aangevraagd met behulp 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 cloudtoepassingsbeheerder.
  2. Blader naar Entra ID>App-registraties>Alle toepassingen.
  3. Selecteer een toepassing of maak een app als u dat nog niet hebt gedaan.
  4. Selecteer op de overzichtspagina van de toepassing onder Beheren de optie API-machtigingen>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
Kenmerk Beschrijving
tenant De directory-tenant die uw applicatie de machtigingen die het heeft aangevraagd heeft verleend, in GUID-formaat.
state Een waarde die is opgenomen in de aanvraag die is 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 Is ingesteld op True.

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

Foutreactie

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
Kenmerk Beschrijving
error Een foutcodetekenreeks die kan worden gebruikt voor het classificeren van typen fouten die optreden. Het 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 krijgt. 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 in HTTP-aanvragen voor de resource gebruiken. Het geeft op betrouwbare wijze aan dat uw toepassing over de juiste machtiging beschikt om een specifieke taak uit te voeren.

Voor meer informatie over het OAuth 2.0-protocol en het verkrijgen van toegangstokens raadpleegt u de naslaginformatie over het eindpuntprotocol van het Microsoft Identity Platform.

Verwante inhoud

  • Last updated on