Delen via

Bereiken en machtigingen in het Microsoft Identity Platform

The Microsoft identity platform implements the OAuth 2.0 authorization protocol. 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 een URI voor de toepassings-id.

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-grafiek: 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. As an example, Microsoft Graph defines permissions to do the following tasks, among others:

  • 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, these types of permission sets are called scopes. They're also often referred to as permissions. 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.

Admin-restricted permissions

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

Note

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. Instead, the client application is granted permissions directly. 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 voor een stapsgewijze handleiding over het beschikbaar maken van bereiken in een web-API Een toepassing configureren om een web-API beschikbaar te maken.

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.

If you request the OpenID Connect scopes and a token, you get a token to call the UserInfo endpoint.

Het openid bereik

If an app signs in by using OpenID Connect, it must request the openid scope. Het toepassingsgebied openid verschijnt op de toestemmingspagina van het werkprofiel 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.

Zie de profile voor een volledige lijst met de id_tokens claims die beschikbaar zijn in de id_tokens parameter voor een specifieke gebruiker.

Het offline_access bereik

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

Als een gedelegeerde machtiging wordt verleend, wordt impliciet offline_access verleend. U kunt ervan uitgaan dat de toepassing offline_access heeft als er gedelegeerde machtigingen zijn verleend. Refresh tokens, oftewel vernieuwingstokens, hebben een lange levensduur. Uw app kan nieuwe toegangstokens krijgen wanneer de oude verlopen.

Note

This permission currently appears on all consent pages, even for flows that don't provide a refresh token (such as the implicit flow). 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 naslaginformatie over het Microsoft Identity Platform-protocol voor meer informatie over het ophalen en gebruiken van vernieuwingstokens.

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:

  • Scope requirements: Ensure that you're requesting the offline_access scopes along with any other necessary 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.
  • Client configuration: Check your application's settings in the identity platform. 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 slash's 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).

The .default scope can be used in any OAuth 2.0 flow and to initiate admin consent. Its use is required in the On-Behalf-Of flow and client credentials flow.

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. (Als dat niet het probleem is, worden er een foutbericht of het aanvraagformulier voor beheerderstoestemming weergegeven.) 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.

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

Another use of .default is to request app roles (also known as application permissions) in a non-interactive application like a daemon app that uses the client credentials grant flow to call a web API.

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

Client credentials requests in your client service must include scope={resource}/.default. Hier is {resource} de web-API die uw app wil aanroepen en waarvoor u een toegangstoken wilt verkrijgen. Issuing a client credentials request by using individual application permissions (roles) is not supported. Alle app-rollen (toepassingsmachtigingen) die zijn verleend voor die web-API, worden opgenomen in het geretourneerde toegangstoken.

Als u toegang wilt verlenen tot de app-rollen die u definieert, inclusief het verlenen van beheerderstoestemming voor de toepassing, raadpleegt u Een clienttoepassing configureren voor toegang tot een web-API.

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.

See also

  • Last updated on