Microsoft Identity Platform en de OAuth 2.0-clientreferentiestroom
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. De toekenning die is opgegeven in RFC 6749, ook wel tweebenige OAuth genoemd, kan worden gebruikt voor toegang tot door het web gehoste resources met behulp van de identiteit van een toepassing. Dit type wordt vaak gebruikt voor server-naar-server-interacties die op de achtergrond moeten worden uitgevoerd, zonder directe interactie met een gebruiker en wordt vaak daemons of serviceaccounts genoemd.
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. In dit artikel worden de volgende stappen beschreven:
- Een toepassing machtigen om een API aan te roepen
- De tokens ophalen die nodig zijn om die API aan te roepen.
In dit artikel wordt beschreven hoe u rechtstreeks kunt programmeren op basis van het protocol in uw toepassing. Indien mogelijk raden we u aan om in plaats daarvan de ondersteunde Microsoft Authentication Libraries (MSAL) te gebruiken om tokens te verkrijgen en beveiligde web-API's aan te roepen. U kunt ook verwijzen naar 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.
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 worden bewaard. Publiceer deze referentie nooit in uw broncode, sluit deze in op webpagina's of gebruik deze in een algemeen gedistribueerde systeemeigen toepassing.
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.
Directe autorisatie ophalen
Een app ontvangt doorgaans op twee manieren directe autorisatie voor toegang tot een bron:
- Via een toegangsbeheerlijst (ACL) bij de bron
- Via toepassingsmachtigingstoewijzing in Microsoft Entra-id
Deze twee methoden zijn de meest voorkomende in Microsoft Entra-id en we raden ze aan voor clients en resources die de clientreferentiestroom 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 end-to-end-tests wilt uitvoeren op de API, kunt u een testclient maken die tokens verkrijgt van het Microsoft Identity Platform en deze vervolgens naar de API verzendt. 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, is voor Microsoft Entra ID niet vereist dat toepassingen worden geautoriseerd voor het ophalen van tokens voor een andere toepassing. 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.
Toepassingstoestemming
In plaats van ACL's te gebruiken, kunt u API's gebruiken om een set toepassingsmachtigingen beschikbaar te maken. Deze worden verleend aan een toepassing door de beheerder van een organisatie en kunnen alleen worden gebruikt voor toegang tot gegevens die eigendom zijn van die organisatie en zijn 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 plaats van Microsoft Graph), moet u eerst de app-rollen beschikbaar maken in de app-registratie van de API in het Microsoft Entra-beheercentrum. 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 het Microsoft Entra-beheercentrum.
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.
Aanbevolen: meld de beheerder aan bij uw app om app-rollen toe te kunnen wijzen
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, onderdeel van de instellingen van de app of een toegewezen verbindingsstroom . Het is vaak logisch dat de app deze weergave voor verbinding alleen weergeeft nadat een gebruiker zich heeft aangemeld met een werk- of schoolaccount van Microsoft.
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=00001111-aaaa-2222-bbbb-3333cccc4444
&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=00001111-aaaa-2222-bbbb-3333cccc4444&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 door het Microsoft Entra-beheercentrum wordt App-registraties ervaring 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 Microsoft Entra-id af dat alleen een tenantbeheerder zich kan aanmelden om de aanvraag te voltooien. 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.
Succesvolle respons
Als de beheerder de machtigingen voor uw toepassing 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 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. |
Foutrespons
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 | Description |
|---|---|
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 behulp van de toekenning van clientreferenties, verzendt u een POST-aanvraag naar het /token Microsoft Identity Platform. Er zijn enkele verschillende gevallen:
- Toegangstokenaanvraag met een gedeeld geheim
- Toegangstokenaanvraag met een certificaat
- Toegangstokenaanvraag met een federatieve referentie
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:443
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=sampleCredentials
&grant_type=client_credentials
# Replace {tenant} with your tenant!
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'client_id=00001111-aaaa-2222-bbbb-3333cccc4444&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default&client_secret=A1bC2dE3f...&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. Alle bereiken die zijn opgenomen, moeten voor één resource zijn. Als u bereiken voor meerdere resources opneemt, treedt er een fout op. 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:443
Content-Type: application/x-www-form-urlencoded
scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=11112222-bbbb-3333-cccc-4444dddd5555
&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. Alle bereiken die zijn opgenomen, moeten voor één resource zijn. Als u bereiken voor meerdere resources opneemt, treedt er een fout op. 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_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:443
Content-Type: application/x-www-form-urlencoded
scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=11112222-bbbb-3333-cccc-4444dddd5555&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 stroom op basis van certificaten, met de cruciale uitzondering van 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 workloadidentiteitsfederatie 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.
Succesvolle respons
Een geslaagd antwoord van een methode ziet er als volgt uit:
{
"token_type": "Bearer",
"expires_in": 3599,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}
| Parameter | Description |
|---|---|
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.
Foutrespons
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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
"error_codes": [
70011
],
"timestamp": "YYYY-MM-DD HH:MM:SSZ",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Parameter | Description |
|---|---|
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/users HTTP/1.1
Host: graph.microsoft.com:443
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
Probeer de volgende opdracht in uw terminal om ervoor te zorgen dat u het token vervangt door uw eigen token.
curl -X GET -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...." 'https://graph.microsoft.com/v1.0/users'
Codevoorbeelden en andere documentatie
Lees de overzichtsdocumentatie voor clientreferenties uit de Microsoft Authentication Library
| Voorbeeld | Platform | Beschrijving |
|---|---|---|
| active-directory-dotnetcore-daemon-v2 | .NET 6.0+ | Een ASP.NET Core-toepassing die de gebruikers van een tenant weergeeft die een query uitvoert op Microsoft Graph met behulp van 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 Node.js-toepassing die de gebruikers van een tenant weergeeft door een query uit te voeren op Microsoft Graph met behulp van de identiteit van de toepassing |