Microsoft Identity Platform en de OAuth 2.0-clientreferentiestroom

U kunt de toekenning van OAuth 2.0-clientreferenties gebruiken die is opgegeven in RFC 6749, soms two-legged OAuth genoemd, voor toegang tot op het web gehoste bronnen met de identiteit van een toepassing. Dit type toekenning wordt meestal gebruikt voor server-naar-server-interacties die op de achtergrond moeten worden uitgevoerd, zonder directe interactie met een gebruiker. Deze typen toepassingen worden vaak daemons of serviceaccounts genoemd.

In dit artikel wordt beschreven hoe u rechtstreeks kunt programmeren op basis van het protocol in uw toepassing. Gebruik indien mogelijk in plaats daarvan de ondersteunde Microsoft Authentication Libraries (MSAL) om tokens te verkrijgen en beveiligde web-API's aan te roepen. Bekijk ook de voorbeeld-apps die gebruikmaken van MSAL. Als kanttekening: vernieuwingstokens worden nooit met deze stroom verleend als client_id en client_secret (die nodig zijn om een vernieuwingstoken te verkrijgen) kan worden gebruikt om in plaats daarvan een toegangstoken te verkrijgen.

Met de stroom voor het verlenen van OAuth 2.0-clientreferenties kan een webservice (vertrouwelijke client) eigen referenties gebruiken, in plaats van zich voor te doen als een gebruiker, om te verifiëren bij het aanroepen van een andere webservice. Voor een hoger niveau van zekerheid stelt het Microsoft Identity-platform de aanroepende service ook in staat om te verifiëren met een certificaat of federatieve referentie in plaats van een gedeeld geheim. Omdat de eigen referenties van de toepassing worden gebruikt, moeten deze referenties veilig blijven. Publiceer deze referenties nooit in uw broncode, sluit deze in op webpagina's of gebruik deze in een algemeen gedistribueerde, systeemeigen toepassing.

In de clientreferentiestroom worden machtigingen rechtstreeks aan de toepassing zelf verleend door een beheerder. Wanneer de app een token aan een bron presenteert, dwingt de bron af dat de app zelf autorisatie heeft om een actie uit te voeren, omdat geen gebruiker betrokken is bij de verificatie. Dit artikel behandelt zowel de stappen die nodig zijn om een toepassing te autoriseren om een API aan te roepen, als hoe u de tokens kunt verkrijgen die nodig zijn om die API aan te roepen.

Tip

Voer deze aanvraag uit in Postman
Voer deze aanvraag en meer uit in Postman, en vergeet niet om tokens en id's te vervangen.

Protocoldiagram

De volledige stroom voor clientreferenties ziet er ongeveer uit als in het volgende diagram. We beschrijven elk van de stappen verderop in dit artikel.

Diagram met de stroom voor de clientreferenties

Directe autorisatie ophalen

Een app ontvangt doorgaans op twee manieren directe autorisatie voor toegang tot een bron:

Deze twee methoden zijn de meest voorkomende in Azure AD en we raden ze aan voor clients en bronnen die de stroom voor clientreferenties uitvoeren. Een bron kan er ook voor kiezen om de clients op andere manieren te autoriseren. Elke bronserver kan de methode kiezen die het meest zinvol is voor de toepassing.

Toegangsbeheerlijsten

Een resourceprovider kan een autorisatiecontrole afdwingen op basis van een lijst met toepassings-id's (client-id's) die deze kent en een specifiek toegangsniveau verleent. Wanneer de bron een token ontvangt van het Microsoft Identity-platform, kan het token decoderen en de toepassings-id van de client ophalen uit de appid en iss claims. Vervolgens wordt de toepassing vergeleken met een toegangsbeheerlijst (ACL) die wordt onderhouden. De granulariteit en methode van de ACL kunnen aanzienlijk verschillen tussen bronnen.

Een veelvoorkomend gebruik is het gebruik van een ACL om tests uit te voeren voor een webtoepassing of voor een web-API. De web-API verleent mogelijk slechts een subset van volledige machtigingen aan een specifieke client. Als u complete testen op de API wilt uitvoeren, maakt u een testclient die tokens van het Microsoft Identity-platform verkrijgt. Deze verzendt u vervolgens naar de API. De API controleert vervolgens de ACL voor de toepassings-id van de testclient voor volledige toegang tot de volledige functionaliteit van de API. Als u dit type ACL gebruikt, controleert u niet alleen de waarde van appid de aanroepende partij, maar controleert u ook of de iss waarde van het token wordt vertrouwd.

Dit type autorisatie is gebruikelijk voor daemons en serviceaccounts die toegang moeten hebben tot gegevens die eigendom zijn van consumentengebruikers met persoonlijke Microsoft-accounts. Voor gegevens die eigendom zijn van organisaties, wordt aangeraden de benodigde autorisatie te verkrijgen via toepassingsmachtigingen.

Tokens beheren zonder de roles claim

Als u dit verificatiepatroon op basis van een ACL wilt inschakelen, vereist Azure AD niet dat toepassingen zijn gemachtigd om tokens voor een andere toepassing op te halen. Daarom kunnen alleen app-tokens worden uitgegeven zonder een roles claim. Toepassingen die API's beschikbaar maken, moeten machtigingscontroles implementeren om tokens te accepteren.

Als u wilt voorkomen dat toepassingen alleen toegangstokens voor apps voor uw toepassing krijgen, moet u zorgen dat toewijzingsvereisten zijn ingeschakeld voor uw app. Hierdoor kunnen gebruikers en toepassingen zonder toegewezen rollen geen token voor deze toepassing ophalen.

Toepassingsmachtigingen

In plaats van ACL's te gebruiken, kunt u API's gebruiken om een set toepassingsmachtigingen beschikbaar te maken. Een toepassingsmachtiging wordt verleend aan een toepassing door de beheerder van een organisatie en kan alleen worden gebruikt voor toegang tot gegevens die eigendom zijn van die organisatie en diens werknemers. Microsoft Graph maakt bijvoorbeeld verschillende toepassingsmachtigingen beschikbaar voor het volgende:

  • E-mail in alle postvakken lezen
  • E-mail in alle postvakken lezen en schrijven
  • E-mail met elke willekeurige gebruiker als afzender verzenden
  • Mapgegevens lezen

Als u app-rollen (toepassingsmachtigingen) wilt gebruiken met uw eigen API (in tegenstelling tot Microsoft Graph), moet u eerst de app-rollen beschikbaar maken in de app-registratie van de API in de Azure Portal. Configureer vervolgens de vereiste app-rollen door deze machtigingen te selecteren in de app-registratie van uw clienttoepassing. Als u geen app-rollen hebt weergegeven in de app-registratie van uw API, kunt u geen toepassingsmachtigingen voor die API opgeven in de app-registratie van uw clienttoepassing in de Azure Portal.

Bij het verifiëren als een toepassing (in tegenstelling tot een gebruiker), kunt u geen gedelegeerde machtigingen gebruiken omdat er geen gebruiker is voor uw app om namens te handelen. U moet toepassingsmachtigingen, ook wel app-rollen genoemd, gebruiken die worden verleend door een beheerder of door de eigenaar van de API.

Zie voor meer informatie over toepassingsmachtigingen Machtigingen en toestemming.

Wanneer u een toepassing bouwt die gebruikmaakt van toepassingsmachtigingen, vereist de app doorgaans een pagina of weergave waarop de beheerder de machtigingen van de app goedkeurt. Deze pagina kan deel uitmaken van de aanmeldingsstroom van de app, een deel van de instellingen van de app of een toegewezen stroom voor verbinding maken. In veel gevallen is het logisch dat de app deze weergave 'verbinding maken' alleen weergeeft nadat een gebruiker zich heeft aangemeld met een Microsoft-werk- of schoolaccount.

Als u de gebruiker aanmeldt bij uw app, kunt u de organisatie identificeren waartoe de gebruiker behoort voordat u de gebruiker vraagt de toepassingsmachtigingen goed te keuren. Hoewel dit niet strikt noodzakelijk is, kunt u hiermee een intuïtievere ervaring voor uw gebruikers creëren. Volg de Microsoft Identity Platform-protocolzelfstudies om de gebruiker aan te melden.

De machtigingen aanvragen van een directorybeheerder

Wanneer u klaar bent om machtigingen aan te vragen van de beheerder van de organisatie, kunt u de gebruiker omleiden naar het eindpunt van de Microsoft Identity Platform-beheerderstoestemming.

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/adminconsent?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&state=12345
&redirect_uri=http://localhost/myapp/permissions

Pro-tip: plak de volgende aanvraag in een browser.

https://login.microsoftonline.com/common/adminconsent?client_id=6731de76-14a6-49ae-97bc-6eba6914391e&state=12345&redirect_uri=http://localhost/myapp/permissions
Parameter Voorwaarde Beschrijving
tenant Vereist De directorytenant waaruit u toestemming wilt aanvragen. Deze kan een GUID- of beschrijvende naamindeling hebben. Als u niet weet tot welke tenant de gebruiker behoort en u deze wilt laten aanmelden met een tenant, gebruikt u common.
client_id Vereist De toepassings-id (client) die de ervaring Azure Portal: app-registraties heeft toegewezen aan uw app.
redirect_uri Vereist De URI voor omleiding waar u wilt dat het antwoord wordt verzonden voor uw app. Deze moet exact overeenkomen met een van de URI's voor omleiding die u hebt geregistreerd in de portal, behalve dat deze URL-gecodeerd moet zijn en er kunnen extra padsegmenten zijn.
state Aanbevolen Een waarde die is opgenomen in de aanvraag die ook wordt geretourneerd in de tokenreactie. Het kan een tekenreeks zijn van alle gewenste inhoud. De status wordt gebruikt voor het coderen van informatie over de status van de gebruiker in de app voordat de verificatieaanvraag is opgetreden, zoals de pagina of weergave waarop ze zich bevonden.

Op dit moment dwingt Azure AD af dat alleen een tenantbeheerder zich kan aanmelden bij het voltooien van de aanvraag. De beheerder wordt gevraagd alle machtigingen voor de directe toepassing goed te keuren die u hebt aangevraagd voor uw app in de portal voor app-registratie.

Geslaagde reactie

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

GET http://localhost/myapp/permissions?tenant=a8990e1f-ff32-408a-9f8e-78d3b9139b95&state=state=12345&admin_consent=True
Parameter Beschrijving
tenant De maptenant 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 de tokenreactie. Het kan een tekenreeks zijn van alle gewenste inhoud. De status wordt gebruikt voor het coderen van informatie over de status van de gebruiker in de app voordat de verificatieaanvraag is opgetreden, zoals de pagina of weergave waarop ze zich bevonden.
admin_consent Stel in op True.
Foutreactie

Als de beheerder de machtigingen voor uw toepassing 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 Beschrijving
error Een tekenreeks met foutcodes die u kunt gebruiken om typen fouten in te delen en waarmee u kunt reageren op fouten.
error_description Een specifiek foutbericht waarmee u de hoofdoorzaak van een fout kunt identificeren.

Nadat u een geslaagd antwoord van het eindpunt voor het inrichten van apps hebt ontvangen, heeft uw app de directe toepassingsmachtigingen gekregen die door de app zijn aangevraagd. Nu kunt u een token aanvragen voor de gewenste bron.

Een token ophalen

Nadat u de benodigde autorisatie voor uw toepassing hebt verkregen, gaat u verder met het verkrijgen van toegangstokens voor API's. Als u een token wilt ophalen met toekenning van clientreferenties, stuurt u een POST-aanvraag naar het /token Microsoft Identity-platform:

Eerste geval: aanvraag voor toegangstoken met een gedeeld geheim

POST /{tenant}/oauth2/v2.0/token HTTP/1.1           //Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=sampleCredentia1s
&grant_type=client_credentials
# Replace {tenant} with your tenant!
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'client_id=535fb089-9ff3-47b6-9bfb-4f1264799865&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default&client_secret=qWgdYAmab0YSkuL1qKv5bPX&grant_type=client_credentials' 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token'
Parameter Voorwaarde Beschrijving
tenant Vereist De maptenant waarop de toepassing van plan is te werken, in GUID- of domeinnaamindeling.
client_id Vereist De toepassings-ID die aan uw app is toegewezen. U vindt deze informatie in de portal waar u uw app hebt geregistreerd.
scope Vereist De waarde die voor de scope parameter in deze aanvraag wordt doorgegeven, moet de bron-id (toepassings-id-URI) van de gewenste bron zijn, die is bevestigd met het .default achtervoegsel. Voor het Microsoft Graph-voorbeeld is https://graph.microsoft.com/.defaultde waarde.
Deze waarde geeft het Microsoft Identity-platform aan dat van alle machtigingen voor directe toepassingen die u hebt geconfigureerd voor uw app, het eindpunt een token moet uitgeven voor de machtigingen die zijn gekoppeld aan de bron die u wilt gebruiken. Zie de /.defaultdocumentatie voor toestemming voor meer informatie over het bereik.
client_secret Vereist Het clientgeheim dat u hebt gegenereerd voor uw app in de portal voor app-registratie. Het clientgeheim moet met een URL gecodeerd zijn voordat het wordt verzonden. Het basispatroon voor verificatie, per RFC 6749 wordt ook ondersteund, in plaats van referenties opgeven in de autorisatieheader.
grant_type Vereist Moet worden ingesteld op client_credentials.

Tweede geval: aanvraag van toegangstoken met een certificaat

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=97e0a5b7-d745-40b6-94fe-5f77d35c6e05
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials
Parameter Voorwaarde Beschrijving
tenant Vereist De maptenant waarop de toepassing van plan is te werken, in GUID- of domeinnaamindeling.
client_id Vereist De toepassings-ID (client) die aan uw app is toegewezen.
scope Vereist De waarde die voor de scope parameter in deze aanvraag wordt doorgegeven, moet de bron-id (toepassings-id-URI) van de gewenste bron zijn, die is bevestigd met het .default achtervoegsel. Voor het Microsoft Graph-voorbeeld is https://graph.microsoft.com/.defaultde waarde.
Deze waarde informeert het Microsoft Identity-platform dat van alle machtigingen voor directe toepassingen die u hebt geconfigureerd voor uw app, een token moet uitgeven voor de machtigingen die zijn gekoppeld aan de bron die u wilt gebruiken. Zie de /.defaultdocumentatie voor toestemming voor meer informatie over het bereik.
client_assertion_type Vereist Deze waarde moet worden ingesteld op urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion Vereist Een assertie (een JSON-webtoken) die u moet maken en ondertekenen met het certificaat dat u hebt geregistreerd als referenties voor uw toepassing. Lees meer over certificaatreferenties voor meer informatie over het registreren van uw certificaat en de indeling van de assertie.
grant_type Vereist Moet worden ingesteld op client_credentials.

De parameters voor de aanvraag op basis van certificaten verschillen op slechts één manier van de aanvraag op basis van een gedeeld geheim: de client_secret parameter wordt vervangen door de client_assertion_type en client_assertion parameters.

Derde geval: aanvraag van toegangstoken met federatieve referentie

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=97e0a5b7-d745-40b6-94fe-5f77d35c6e05
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials
Parameter Voorwaarde Beschrijving
client_assertion Vereist Een assertie (een JWT- of JSON-webtoken) die uw toepassing krijgt van een andere id-provider buiten het Microsoft Identity-platform, zoals Kubernetes. De specifieke kenmerken van deze JWT moeten in uw toepassing worden geregistreerd als federatieve identiteitsreferentie. Lees meer over federatie voor identiteit van werkbelasting voor meer informatie over het instellen en gebruiken van asserties die zijn gegenereerd door andere id-providers.

Alles in de aanvraag is hetzelfde als de bovenstaande stroom op basis van certificaten, met één cruciale uitzondering: de bron van de client_assertion. In deze stroom maakt uw toepassing de JWT-assertie zelf niet. In plaats daarvan gebruikt uw app een JWT die is gemaakt door een andere id-provider. Dit wordt 'federatie voor identiteit van werkbelasting' genoemd, waarbij uw apps-identiteit in een ander identiteitsplatform wordt gebruikt om tokens binnen het Microsoft Identity-platform te verkrijgen. Dit is het meest geschikt voor scenario's tussen clouds, zoals het hosten van uw rekenproces buiten Azure, maar het openen van API's die worden beveiligd door het Microsoft Identity-platform. Lees over de assertie-indeling voor informatie over de vereiste indeling van JWT's die zijn gemaakt door andere id-providers.

Geslaagde reactie

Een geslaagd antwoord van een methode ziet er als volgt uit:

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}
Parameter Beschrijving
access_token Het aangevraagde toegangstoken. De app kan dit token gebruiken om te verifiëren bij de beveiligde bron, zoals een web-API.
token_type Geeft de waarde van het tokentype aan. Het enige type dat door het Microsoft Identity-platform wordt ondersteund, is bearer.
expires_in De hoeveelheid tijd die een toegangstoken geldig is (in seconden).

Waarschuwing

Probeer geen tokens te valideren of te lezen voor een API waarvan u geen eigenaar bent, inclusief de tokens in dit voorbeeld, in uw code. Tokens voor Microsoft-services kunnen een speciale indeling gebruiken die niet wordt gevalideerd als een JWT, en kunnen ook worden versleuteld voor consumentengebruikers (Microsoft-account). Hoewel het lezen van tokens een handig hulpprogramma voor foutopsporing is en een leerfunctie heeft, hoeft u hier geen afhankelijkheden van te maken in uw code of uit te gaan van specifieke informatie over tokens die niet voor een API zijn die u beheert.

Foutreactie

Een foutbericht (400 Ongeldige aanvraag) ziet er als volgt uit:

{
  "error": "invalid_scope",
  "error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/.default is not valid.\r\nTrace ID: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
  "correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}
Parameter Beschrijving
error Een tekenreeks met foutcodes die u kunt gebruiken om typen fouten in te delen en waarmee u kunt reageren op fouten.
error_description Een specifiek foutbericht waarmee u de hoofdoorzaak van een verificatiefout kan identificeren.
error_codes Een lijst met STS-specifieke foutcodes die kunnen helpen bij diagnostische gegevens.
timestamp Het tijdstip waarop de fout is opgetreden.
trace_id Een unieke id voor de aanvraag om te helpen met diagnostische gegevens.
correlation_id Een unieke id voor de aanvraag om te helpen bij diagnostische gegevens over onderdelen.

Een token gebruiken

Nu u een token hebt verkregen, gebruikt u het token om aanvragen naar de bron te verzenden. Wanneer het token verloopt, herhaalt u de aanvraag naar het /token eindpunt om een nieuw toegangstoken te verkrijgen.

GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
# Pro tip: Try the following command! (Replace the token with your own.)

curl -X GET -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...." 'https://graph.microsoft.com/v1.0/me/messages'

Codevoorbeelden en andere documentatie

Lees de overzichtsdocumentatie voor clientreferenties uit de Microsoft Authentication Library

Voorbeeld Platform Beschrijving
active-directory-dotnetcore-daemon-v2 .NET Core 2.1 Console Een eenvoudige .NET Core-toepassing waarin de gebruikers van een tenant worden weergegeven die query's uitvoert op Microsoft Graph met de identiteit van de toepassing, in plaats van namens een gebruiker. Het voorbeeld illustreert ook de variatie met certificaten voor verificatie.
active-directory-dotnet-daemon-v2 ASP.NET MVC Een webtoepassing die gegevens synchroniseert vanuit Microsoft Graph met de identiteit van de toepassing, in plaats van namens een gebruiker.
ms-identity-javascript-nodejs-console Node.js Console Een eenvoudige Node.js-toepassing waarmee de gebruikers van een tenant worden weergegeven door een query uit te voeren op Microsoft Graph met de identiteit van de toepassing