Bereiken en machtigingen in het Microsoft Identity Platform
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.
.default
wanneer de gebruiker toestemming geeft
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.