Microsoft Identity Platform en de OAuth 2.0-clientreferentiestroom
Met de OAuth 2.0-clientverificatiestroom kan een webservice (vertrouwelijke client) gebruik maken van zijn eigen referenties in plaats van een gebruiker te vertegenwoordigen, om zich te verifiëren wanneer een andere webservice wordt aangeroepen. 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 stroom met clientreferenties worden machtigingen rechtstreeks aan de toepassing zelf verleend door een beheerder. Wanneer de app een token aan een resource presenteert, dwingt de resource af dat de app zelf autorisatie heeft om een actie uit te voeren, omdat er 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 programma's kunt uitvoeren 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 worden vernieuwingstokens nooit met deze stroom verleend als client_id en client_secret (die vereist zijn om een vernieuwingstoken te verkrijgen) kunnen worden gebruikt om in plaats daarvan een toegangstoken te verkrijgen.
Voor een hoger niveau van zekerheid kan het Microsoft Identity Platform de aanroepende service ook verifiëren met behulp van 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.
Protocolschema
De volledige stroom voor clientreferenties ziet er ongeveer als volgt uit. We beschrijven elk van de stappen verderop in dit artikel.
Directe autorisatie ophalen
Een app ontvangt doorgaans directe autorisatie voor toegang tot een resource op een van de volgende twee manieren:
- Via een toegangsbeheerlijst (ACL) bij de resource
- 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 resource kan er ook voor kiezen om de clients op andere manieren te autoriseren. Elke resourceserver 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 resource een token van het Microsoft Identity Platform ontvangt, kan het token worden gedecodeerd en de toepassings-id van de client worden geëxtraheerd 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 resources.
Een veelvoorkomende use-case is het gebruik van een ACL om tests uit te voeren voor een webtoepassing of voor een web-API. De web-API kan slechts een subset van volledige machtigingen verlenen 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 op de toepassings-id van de testclient voor volledige toegang tot de volledige functionaliteit van de API. Als u dit type ACL gebruikt, moet u niet alleen de waarde van appid de aanroeper valideren, maar ook valideren dat de iss waarde van het token wordt vertrouwd.
Dit type autorisatie is gebruikelijk voor daemons en serviceaccounts die toegang nodig hebben tot gegevens die eigendom zijn van consumentengebruikers die persoonlijke Microsoft-accounts hebben. Voor gegevens die eigendom zijn van organisaties, raden we u aan om de benodigde autorisatie te krijgen 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. Zo kunnen alleen app-tokens worden uitgegeven zonder roles claim. Toepassingen die API's beschikbaar maken, moeten machtigingscontroles implementeren om tokens te accepteren.
Als u wilt voorkomen dat toepassingen alleen-rolloze toegangstokens voor uw toepassing krijgen, moet u ervoor 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 om het volgende te doen:
- E-mail lezen in alle postvakken
- E-mail lezen en schrijven in alle postvakken
- E-mail verzenden als elke gebruiker
- Adreslijstgegevens 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 plaats van met een gebruiker), kunt u geen gedelegeerde machtigingen gebruiken omdat er geen gebruiker is voor uw app om namens hen 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 Machtigingen en toestemming voor meer informatie over toepassingsmachtigingen.
Aanbevolen: Meld de beheerder aan bij uw app om app-rollen toe te wijzen
Wanneer u een toepassing bouwt die gebruikmaakt van toepassingsmachtigingen, vereist de app doorgaans een pagina of weergave waarvoor 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, kan het u helpen om een intuïtievere ervaring voor uw gebruikers te creëren. Volg de zelfstudies voor het Microsoft Identity Platform-protocol 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 microsoft identity platform-beheerderstoestemmingseindpunt.
// 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: Probeer de volgende aanvraag in een browser te plakken.
https://login.microsoftonline.com/common/adminconsent?client_id=00001111-aaaa-2222-bbbb-3333cccc4444&state=12345&redirect_uri=http://localhost/myapp/permissions
| Maatstaf | Conditie | Beschrijving |
|---|---|---|
tenant |
Verplicht | De directorytenant waaruit u toestemming wilt aanvragen. Dit 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 commonu . |
client_id |
Verplicht | De toepassings-id (client) die door de Microsoft Entra beheerderscentrum – App-registraties interface aan uw app is toegewezen. |
redirect_uri |
Verplicht | De URI voor omleiding waar u wilt dat het antwoord wordt verzonden voor uw app. Deze moet exact overeenkomen met een van de omleidings-URI's die u hebt geregistreerd in de portal, behalve dat deze URL-gecodeerd moet zijn en dat deze extra padsegmenten kan bevatten. |
state |
Aanbevolen | Een waarde die is opgenomen in de aanvraag die ook wordt geretourneerd in het tokenantwoord. Het kan een tekenreeks zijn van elke gewenste inhoud. De status wordt gebruikt om informatie over de status van de gebruiker in de app te coderen 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
| Maatstaf | Beschrijving |
|---|---|
tenant |
De maptenant die uw toepassing de machtigingen heeft verleend die zijn aangevraagd, in GUID-indeling. |
state |
Een waarde die is opgenomen in de aanvraag die ook wordt geretourneerd in het tokenantwoord. Het kan een tekenreeks zijn van elke gewenste inhoud. De status wordt gebruikt om informatie over de status van de gebruiker in de app te coderen voordat de verificatieaanvraag is opgetreden, zoals de pagina of weergave waarop ze zich bevonden. |
admin_consent |
Ingesteld op Waar. |
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
| Maatstaf | Beschrijving |
|---|---|
error |
Een tekenreeks met foutcodes die u kunt gebruiken om typen fouten te classificeren en die u kunt gebruiken om te reageren op fouten. |
error_description |
Een specifiek foutbericht waarmee u de hoofdoorzaak van een fout kunt identificeren. |
Nadat u een geslaagd antwoord hebt ontvangen van het eindpunt voor het inrichten van apps, heeft uw app de directe toepassingsmachtigingen gekregen die door de app zijn aangevraagd. U kunt nu een token aanvragen voor de gewenste resource.
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: Toegangstokenaanvraag 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=qWgdYAmab0YSkuL1qKv5bPX
&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'
| Maatstaf | Conditie | Beschrijving |
|---|---|---|
tenant |
Verplicht | De directorytenant waarop de toepassing van plan is te werken, in GUID- of domeinnaamindeling. |
client_id |
Verplicht | De toepassings-id die is toegewezen aan uw app. U vindt deze informatie in de portal waar u uw app hebt geregistreerd. |
scope |
Verplicht | De waarde die is doorgegeven voor de scope parameter in deze aanvraag, moet de resource-id (toepassings-id-URI) van de gewenste resource zijn, achtervoegsel met .default. 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 vertelt het Microsoft Identity Platform dat van alle directe toepassingsmachtigingen die u hebt geconfigureerd voor uw app, het eindpunt een token moet uitgeven voor de machtigingen die zijn gekoppeld aan de resource die u wilt gebruiken. Zie de documentatie voor toestemming voor meer informatie over het /.default bereik. |
client_secret |
Verplicht | Het clientgeheim dat u hebt gegenereerd voor uw app in de portal voor app-registratie. Het clientgeheim moet 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 |
Verplicht | Moet worden ingesteld op client_credentials. |
Tweede geval: Toegangstokenaanvraag 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
| Maatstaf | Conditie | Beschrijving |
|---|---|---|
tenant |
Verplicht | De directorytenant waarop de toepassing van plan is te werken, in GUID- of domeinnaamindeling. |
client_id |
Verplicht | De toepassings-id (client) die is toegewezen aan uw app. |
scope |
Verplicht | De waarde die is doorgegeven voor de scope parameter in deze aanvraag, moet de resource-id (toepassings-id-URI) van de gewenste resource zijn, achtervoegsel met .default. 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 vertelt het Microsoft Identity Platform dat van alle directe toepassingsmachtigingen die u hebt geconfigureerd voor uw app, het eindpunt een token moet uitgeven voor de machtigingen die zijn gekoppeld aan de resource die u wilt gebruiken. Zie de documentatie voor toestemming voor meer informatie over het /.default bereik. |
client_assertion_type |
Verplicht | De waarde moet worden ingesteld op urn:ietf:params:oauth:client-assertion-type:jwt-bearer. |
client_assertion |
Verplicht | 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 |
Verplicht | Moet worden ingesteld op client_credentials. |
De parameters voor de aanvraag op basis van certificaten verschillen op slechts één manier van de gedeelde op geheim gebaseerde aanvraag: de client_secret parameter wordt vervangen door de client_assertion_type en client_assertion parameters.
Derde geval: Toegangstokenaanvraag met een 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
| Maatstaf | Conditie | Beschrijving |
|---|---|---|
client_assertion |
Verplicht | Een assertie (een JWT- of JSON-webtoken) die uw toepassing ontvangt van een andere id-provider buiten het Microsoft Identity Platform, zoals Kubernetes. De specifieke kenmerken van deze JWT moeten als federatieve identiteitsreferentie in uw toepassing worden geregistreerd. Lees meer over federatie van workloadidentiteiten voor 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..."
}
| Maatstaf | Beschrijving |
|---|---|
access_token |
Het aangevraagde toegangstoken. De app kan dit token gebruiken om te verifiëren bij de beveiligde resource, zoals bij 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 gebruikmaken van een speciale indeling die niet als JWT wordt gevalideerd en die ook kan 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: 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"
}
| Maatstaf | Beschrijving |
|---|---|
error |
Een tekenreeks met foutcodes die u kunt gebruiken om typen fouten te classificeren die optreden en om te reageren op fouten. |
error_description |
Een specifiek foutbericht waarmee u de hoofdoorzaak van een verificatiefout kunt 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 voor hulp bij diagnostische gegevens over onderdelen. |
Een token gebruiken
Nu u een token hebt verkregen, gebruikt u het token om aanvragen naar de resource 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 eyJ0eXAiOiJKV1QiLCJhbG...
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 | Platvorm | 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 behulp van certificaten voor verificatie. |
| active-directory-dotnet-daemon-v2 | ASP.NET MVC | Een webtoepassing die gegevens uit Microsoft Graph synchroniseert met behulp van 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 |