Microsoft Identity Platform en OAuth 2.0 Namens stroom
De stroom namens (OBO) beschrijft het scenario van een web-API met een andere identiteit dan een eigen identiteit om een andere web-API aan te roepen. De bedoeling is om de identiteit en machtigingen van een gebruiker door te geven via de aanvraagketen, ook wel delegatie genoemd in OAuth.
Voor de service in de middelste laag om geverifieerde aanvragen te kunnen indienen bij de downstreamservice, moet er een toegangstoken worden beveiligd vanuit het Microsoft Identity Platform. Het maakt alleen gebruik van gedelegeerde bereiken en niet van toepassingsrollen. Rollen blijven gekoppeld aan de principal (de gebruiker) en nooit aan de toepassing die namens de gebruiker werkt. Dit gebeurt om te voorkomen dat de gebruiker machtigingen krijgt voor resources waar ze geen toegang toe hebben.
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. Raadpleeg ook de voorbeeld-apps die MSAL gebruiken voor voorbeelden.
Clientbeperkingen
Als een service-principal een token voor alleen apps heeft aangevraagd en naar een API heeft verzonden, zou die API vervolgens een token uitwisselen dat niet de oorspronkelijke service-principal vertegenwoordigt. Dit komt doordat de OBO-stroom alleen werkt voor gebruikersprinciplen. In plaats daarvan moet de clientreferentiestroom worden gebruikt om een app-token op te halen. In het geval van APPS met één pagina (SPA's) moeten ze een toegangstoken doorgeven aan een vertrouwelijke client in de middelste laag om in plaats daarvan OBO-stromen uit te voeren.
Als een client de impliciete stroom gebruikt om een id_token op te halen en ook jokertekens in een antwoord-URL heeft, kan de id_token niet worden gebruikt voor een OBO-stroom. Een jokerteken is een URL die eindigt op een * teken. Als de antwoord-URL bijvoorbeeld https://myapp.com/* is, kan de id_token niet worden gebruikt omdat deze niet specifiek genoeg is om de client te identificeren. Dit voorkomt dat het token wordt uitgegeven. Toegangstokens die zijn verkregen via de impliciete toekenningsstroom, worden echter ingewisseld door een vertrouwelijke client, zelfs als de initiërende client een antwoord-URL met jokertekens heeft geregistreerd. Dit komt doordat de vertrouwelijke client de client kan identificeren die het toegangstoken heeft verkregen. De vertrouwelijke client kan vervolgens het toegangstoken gebruiken om een nieuw toegangstoken voor de downstream-API te verkrijgen.
Bovendien kunnen toepassingen met aangepaste ondertekeningssleutels niet worden gebruikt als API's in de middelste laag in de OBO-stroom. Dit omvat bedrijfstoepassingen die zijn geconfigureerd voor eenmalige aanmelding. Als de API voor de middelste laag een aangepaste ondertekeningssleutel gebruikt, valideert de downstream-API de handtekening van het toegangstoken dat eraan wordt doorgegeven, niet. Dit resulteert in een fout omdat tokens die zijn ondertekend met een sleutel die door de client wordt beheerd, niet veilig kunnen worden geaccepteerd.
Protocoldiagram
Stel dat de gebruiker een toepassing heeft geverifieerd met behulp van de OAuth 2.0-autorisatiecodestroom of een andere aanmeldingsstroom. Op dit moment heeft de toepassing een toegangstoken voor API A (token A ) met de claims van de gebruiker en toestemming voor toegang tot de web-API (API A) in de middelste laag. API A moet nu een geverifieerde aanvraag indienen bij de downstream web-API (API B).
De volgende stappen vormen de OBO-stroom en worden uitgelegd met behulp van het volgende diagram.
- De clienttoepassing doet een aanvraag naar API A met token A (met een
audclaim van API A). - API A wordt geverifieerd bij het eindpunt voor uitgifte van tokens van het Microsoft Identity Platform en vraagt een token aan om toegang te krijgen tot API B.
- Het eindpunt voor tokenuitgifte van het Microsoft Identity Platform valideert de referenties van API A, samen met token A en geeft het toegangstoken voor API B (token B) naar API A uit.
- Token B wordt ingesteld door API A in de autorisatieheader van de aanvraag naar API B.
- Gegevens van de beveiligde resource worden geretourneerd door API B naar API A en vervolgens naar de client.
In dit scenario heeft de service in de middelste laag geen gebruikersinteractie om de toestemming van de gebruiker te krijgen voor toegang tot de downstream-API. Daarom wordt de optie voor het verlenen van toegang tot de downstream-API vooraf weergegeven als onderdeel van de toestemmingsstap tijdens verificatie. Zie Toestemming verkrijgen voor de toepassing in de middelste laag voor meer informatie over het implementeren hiervan in uw app.
Aanvraag voor toegangstoken in de middelste laag
Als u een toegangstoken wilt aanvragen, maakt u een HTTP POST naar het tenantspecifieke Microsoft Identity Platform-tokeneindpunt met de volgende parameters.
https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
Waarschuwing
VERZEND GEEN toegangstokens die zijn uitgegeven aan de middelste laag naar een willekeurige plaats behalve de beoogde doelgroep voor het token. Toegangstokens die zijn uitgegeven aan de middelste laag, zijn alleen bedoeld voor gebruik door die middelste laag om te communiceren met het beoogde doelgroepeindpunt.
Beveiligingsrisico's voor het doorgeven van toegangstokens van een middelste laag aan een client (in plaats van de client die de toegangstokens zelf krijgt) zijn onder andere:
- Verhoogd risico op tokenonderschepping via gecompromitteerde SSL/TLS-kanalen.
- Het is niet mogelijk om te voldoen aan tokenbindings- en voorwaardelijke toegangsscenario's waarvoor een claimstap is vereist (bijvoorbeeld MFA, aanmeldingsfrequentie).
- Incompatibiliteit met door de beheerder geconfigureerde beleidsregels op basis van apparaten (bijvoorbeeld MDM, beleid op basis van locatie).
Er zijn twee gevallen, afhankelijk van of de clienttoepassing ervoor kiest om te worden beveiligd door een gedeeld geheim of een certificaat.
Eerste geval: aanvraag voor toegangstoken met een gedeeld geheim
Wanneer u een gedeeld geheim gebruikt, bevat een service-naar-service-toegangstoken-aanvraag de volgende parameters:
| Parameter | Type | Beschrijving |
|---|---|---|
grant_type |
Vereist | Het type tokenaanvraag. Voor een aanvraag met behulp van een JWT moet de waarde zijn urn:ietf:params:oauth:grant-type:jwt-bearer. |
client_id |
Vereist | De toepassings-id (client) die het Microsoft Entra-beheercentrum - App-registraties pagina die is toegewezen aan uw app. |
client_secret |
Vereist | Het clientgeheim dat u hebt gegenereerd voor uw app in het Microsoft Entra-beheercentrum - App-registraties pagina. Het basispatroon voor verificatie, per RFC 6749 wordt ook ondersteund, in plaats van referenties opgeven in de autorisatieheader. |
assertion |
Vereist | Het toegangstoken dat is verzonden naar de API voor de middelste laag. Dit token moet een doelgroep (aud) claim hebben van de app die deze OBO-aanvraag doet (de app aangeduid door het client-id veld). Toepassingen kunnen een token niet inwisselen voor een andere app (bijvoorbeeld als een client een API verzendt die is bedoeld voor Microsoft Graph, kan de API het niet inwisselen met behulp van OBO. In plaats daarvan moet het token worden geweigerd). |
scope |
Vereist | Een door spaties gescheiden lijst met bereiken voor de tokenaanvraag. Zie bereiken voor meer informatie. |
requested_token_use |
Vereist | Hiermee geeft u aan hoe de aanvraag moet worden verwerkt. In de OBO-stroom moet de waarde worden ingesteld op on_behalf_of. |
Opmerking
De volgende HTTP POST vraagt een toegangstoken en vernieuwingstoken aan met user.read het bereik voor de https://graph.microsoft.com web-API. De aanvraag wordt ondertekend met het clientgeheim en wordt gedaan door een vertrouwelijke client.
//line breaks for legibility only
POST /oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com/<tenant>
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&client_secret=sampleCredentia1s
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCJ9.eyJhdWQiOiIyO{a lot of characters here}
&scope=https://graph.microsoft.com/user.read+offline_access
&requested_token_use=on_behalf_of
Tweede geval: aanvraag van toegangstoken met een certificaat
Een service-to-service-toegangstokenaanvraag met een certificaat bevat de volgende parameters naast de parameters uit het vorige voorbeeld:
| Parameter | Type | Beschrijving |
|---|---|---|
grant_type |
Vereist | Het type tokenaanvraag. Voor een aanvraag met behulp van een JWT moet de waarde zijn urn:ietf:params:oauth:grant-type:jwt-bearer. |
client_id |
Vereist | De toepassings-id (client) die het Microsoft Entra-beheercentrum - App-registraties pagina die is toegewezen aan uw app. |
client_assertion_type |
Vereist | De waarde moet zijn 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. Zie de certificaatreferenties voor meer informatie over het registreren van uw certificaat en de indeling van de assertie. |
assertion |
Vereist | Het toegangstoken dat is verzonden naar de API voor de middelste laag. Dit token moet een doelgroep (aud) claim hebben van de app die deze OBO-aanvraag doet (de app aangeduid door het client-id veld). Toepassingen kunnen een token niet inwisselen voor een andere app (bijvoorbeeld als een client een API verzendt die is bedoeld voor MS Graph, kan de API het niet inwisselen met behulp van OBO. In plaats daarvan moet het token worden geweigerd). |
requested_token_use |
Vereist | Hiermee geeft u aan hoe de aanvraag moet worden verwerkt. In de OBO-stroom moet de waarde worden ingesteld op on_behalf_of. |
scope |
Vereist | Een door spaties gescheiden lijst met bereiken voor de tokenaanvraag. Zie bereiken voor meer informatie. |
U ziet dat de parameters bijna hetzelfde zijn als in het geval van de aanvraag door een gedeeld geheim, behalve dat de client_secret parameter wordt vervangen door twee parameters: a client_assertion_type en client_assertion. De client_assertion_type parameter wordt ingesteld urn:ietf:params:oauth:client-assertion-type:jwt-bearer op en de client_assertion parameter wordt ingesteld op het JWT-token dat is ondertekend met de persoonlijke sleutel van het certificaat.
Opmerking
De volgende HTTP POST vraagt een toegangstoken aan met user.read het bereik voor de https://graph.microsoft.com web-API met een certificaat. De aanvraag wordt ondertekend met het clientgeheim en wordt gedaan door een vertrouwelijke client.
// line breaks for legibility only
POST /oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com/<tenant>
Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&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}
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCIsImtpZCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCJ9.eyJhdWQiO{a lot of characters here}
&requested_token_use=on_behalf_of
&scope=https://graph.microsoft.com/user.read+offline_access
Antwoord op het toegangstoken in de middelste laag
Een geslaagd antwoord is een JSON OAuth 2.0-antwoord met de volgende parameters.
| Parameter | Description |
|---|---|
token_type |
Geeft de waarde van het tokentype aan. Het enige type dat door het Microsoft Identity-platform wordt ondersteund, is Bearer. Zie het OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750) voor meer informatie over bearer-tokens. |
scope |
Het toegangsbereik dat in het token wordt verleend. |
expires_in |
De tijdsduur, in seconden, dat het toegangstoken geldig is. |
access_token |
Het aangevraagde toegangstoken. De aanroepende service kan dit token gebruiken om te verifiëren bij de ontvangende service. |
refresh_token |
Het vernieuwingstoken voor het aangevraagde toegangstoken. De aanroepende service kan dit token gebruiken om een ander toegangstoken aan te vragen nadat het huidige toegangstoken is verlopen. Het vernieuwingstoken wordt alleen verstrekt als het offline_access bereik is aangevraagd. |
Voorbeeld van geslaagd antwoord
In het volgende voorbeeld ziet u een geslaagd antwoord op een aanvraag voor een toegangstoken voor de https://graph.microsoft.com web-API. Het antwoord bevat een toegangstoken en een vernieuwingstoken en is ondertekend met de persoonlijke sleutel van het certificaat.
{
"token_type": "Bearer",
"scope": "https://graph.microsoft.com/user.read",
"expires_in": 3269,
"ext_expires_in": 0,
"access_token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1tQTZOVGFlN0NkV1c3UWZkQ0NDYy0tY0hGa18wZE50MVEtc2loVzRMd2RwQVZISGpnTVdQZ0tQeVJIaGlDbUN2NkdyMEpmYmRfY1RmMUFxU21TcFJkVXVydVJqX3Nqd0JoN211eHlBQSIsImFsZyI6IlJTMjU2IiwieDV0IjoiejAzOXpkc0Z1aXpwQmZCVksxVG4yNVFIWU8wIiwia2lkIjoiejAzOXpkc0Z1aXpwQmZCVksxVG4yNVFIWU8wIn0.eyJhdWQiOiJodHRwczovL2dyYXBoLm1pY3Jvc29mdC5jb20iLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMWRiNDcvIiwiaWF0IjoxNDkzOTMwMzA1LCJuYmYiOjE0OTM5MzAzMDUsImV4cCI6MTQ5MzkzMzg3NSwiYWNyIjoiMCIsImFpbyI6IkFTUUEyLzhEQUFBQU9KYnFFWlRNTnEyZFcxYXpKN1RZMDlYeDdOT29EMkJEUlRWMXJ3b2ZRc1k9IiwiYW1yIjpbInB3ZCJdLCJhcHBfZGlzcGxheW5hbWUiOiJUb2RvRG90bmV0T2JvIiwiYXBwaWQiOiIyODQ2ZjcxYi1hN2E0LTQ5ODctYmFiMy03NjAwMzViMmYzODkiLCJhcHBpZGFjciI6IjEiLCJmYW1pbHlfbmFtZSI6IkNhbnVtYWxsYSIsImdpdmVuX25hbWUiOiJOYXZ5YSIsImlwYWRkciI6IjE2Ny4yMjAuMC4xOTkiLCJuYW1lIjoiTmF2eWEgQ2FudW1hbGxhIiwib2lkIjoiZDVlOTc5YzctM2QyZC00MmFmLThmMzAtNzI3ZGQ0YzJkMzgzIiwib25wcmVtX3NpZCI6IlMtMS01LTIxLTIxMjc1MjExODQtMTYwNDAxMjkyMC0xODg3OTI3NTI3LTI2MTE4NDg0IiwicGxhdGYiOiIxNCIsInB1aWQiOiIxMDAzM0ZGRkEwNkQxN0M5Iiwic2NwIjoiVXNlci5SZWFkIiwic3ViIjoibWtMMHBiLXlpMXQ1ckRGd2JTZ1JvTWxrZE52b3UzSjNWNm84UFE3alVCRSIsInRpZCI6IjcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0NyIsInVuaXF1ZV9uYW1lIjoibmFjYW51bWFAbWljcm9zb2Z0LmNvbSIsInVwbiI6Im5hY2FudW1hQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJWR1ItdmtEZlBFQ2M1dWFDaENRSkFBIiwidmVyIjoiMS4wIn0.cubh1L2VtruiiwF8ut1m9uNBmnUJeYx4x0G30F7CqSpzHj1Sv5DCgNZXyUz3pEiz77G8IfOF0_U5A_02k-xzwdYvtJUYGH3bFISzdqymiEGmdfCIRKl9KMeoo2llGv0ScCniIhr2U1yxTIkIpp092xcdaDt-2_2q_ql1Ha_HtjvTV1f9XR3t7_Id9bR5BqwVX5zPO7JMYDVhUZRx08eqZcC-F3wi0xd_5ND_mavMuxe2wrpF-EZviO3yg0QVRr59tE3AoWl8lSGpVc97vvRCnp4WVRk26jJhYXFPsdk4yWqOKZqzr3IFGyD08WizD_vPSrXcCPbZP3XWaoTUKZSNJg",
"refresh_token": "OAQABAAAAAABnfiG-mA6NTae7CdWW7QfdAALzDWjw6qSn4GUDfxWzJDZ6lk9qRw4An{a lot of characters here}"
}
Dit toegangstoken is een v1.0-geformatteerd token voor Microsoft Graph. Dit komt doordat de tokenindeling is gebaseerd op de resource die wordt geopend en niet is gerelateerd aan de eindpunten die worden gebruikt om deze aan te vragen. Microsoft Graph is ingesteld om v1.0-tokens te accepteren, zodat het Microsoft Identity Platform v1.0-toegangstokens produceert wanneer een client tokens aanvraagt voor Microsoft Graph. Andere apps kunnen aangeven dat ze v2.0-format tokens, v1.0-format tokens of zelfs eigen of versleutelde tokenindelingen willen. Zowel de v1.0- als v2.0-eindpunten kunnen beide indelingen van het token verzenden. Op deze manier kan de resource altijd de juiste indeling van het token krijgen, ongeacht hoe of waar het token wordt aangevraagd door de client.
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.
Voorbeeld van fout antwoord
Er wordt een foutbericht geretourneerd door het tokeneindpunt bij het verkrijgen van een toegangstoken voor de downstream-API, als de downstream-API een beleid voor voorwaardelijke toegang (zoals meervoudige verificatie) heeft ingesteld. De service in de middelste laag moet deze fout weergeven aan de clienttoepassing, zodat de clienttoepassing de gebruikersinteractie kan bieden om te voldoen aan het beleid voor voorwaardelijke toegang.
Als u deze fout weer naar de client wilt weergeven, reageert de service in de middelste laag met HTTP 401 Niet geautoriseerd en met een HTTP-header www-authenticate met de fout en de claimvraag. De client moet deze header parseren en een nieuw token verkrijgen van de verlener van het token door de claimvraag te presenteren als deze bestaat. Clients moeten geen toegang proberen te krijgen tot de service in de middelste laag met behulp van een toegangstoken in de cache.
{
"error":"interaction_required",
"error_description":"AADSTS50079: Due to a configuration change made by your administrator, or because you moved to a new location, you must enroll in multifactor authentication to access 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2017-05-01 22:43:20Z",
"error_codes":[50079],
"timestamp":"2017-05-01 22:43:20Z",
"trace_id":"0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id":"aaaa0000-bb11-2222-33cc-444444dddddd",
"claims":"{\"access_token\":{\"polids\":{\"essential\":true,\"values\":[\"00aa00aa-bb11-cc22-dd33-44ee44ee44ee\"]}}}"
}
Gebruik het toegangstoken voor toegang tot de resource
Nu kan de service in de middelste laag het token gebruiken dat u eerder hebt verkregen om geverifieerde aanvragen naar de downstream-web-API uit te voeren door het token in de Authorization header in te stellen.
Opmerking
GET /v1.0/me HTTP/1.1
Host: graph.microsoft.com
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
SAML-asserties verkregen met een OAuth2.0 OBO-stroom
Sommige op OAuth gebaseerde webservices moeten toegang hebben tot andere webservice-API's die SAML-asserties accepteren in niet-interactieve stromen. Microsoft Entra ID kan een SAML-assertie bieden als reactie op een on-Behalf-Of-stroom die gebruikmaakt van een op SAML gebaseerde webservice als doelresource.
Dit is een niet-standaardextensie voor de OAuth 2.0 On-Behalf-Of-stroom waarmee een OAuth2-toepassing toegang heeft tot api-eindpunten voor webservices die SAML-tokens gebruiken.
Tip
Wanneer u een met SAML beveiligde webservice aanroept vanuit een front-endwebtoepassing, kunt u de API aanroepen en een normale interactieve verificatiestroom initiëren met de bestaande sessie van de gebruiker. U hoeft alleen een OBO-stroom te gebruiken wanneer voor een service-naar-service-aanroep een SAML-token is vereist om gebruikerscontext te bieden.
Een SAML-token verkrijgen met behulp van een OBO-aanvraag met een gedeeld geheim
Een service-naar-serviceaanvraag voor een SAML-assertie bevat de volgende parameters:
| Parameter | Type | Description |
|---|---|---|
| grant_type | vereist | Het type tokenaanvraag. Voor een aanvraag die gebruikmaakt van een JWT, moet de waarde zijn urn:ietf:params:oauth:grant-type:jwt-bearer. |
| assertion | vereist | De waarde van het toegangstoken dat in de aanvraag wordt gebruikt. |
| client_id | vereist | De app-id die is toegewezen aan de aanroepende service tijdens de registratie met Microsoft Entra-id. Als u de app-id in het Microsoft Entra-beheercentrum wilt vinden, bladert u naar Identiteitstoepassingen>> App-registraties en selecteert u vervolgens de naam van de toepassing. |
| client_secret | vereist | De sleutel die is geregistreerd voor de aanroepende service in Microsoft Entra-id. Deze waarde moet worden genoteerd op het moment van registratie. Het basispatroon voor verificatie, per RFC 6749 wordt ook ondersteund, in plaats van referenties opgeven in de autorisatieheader. |
| bereik | vereist | Een door spaties gescheiden lijst met bereiken voor de tokenaanvraag. Zie bereiken voor meer informatie. SAML zelf heeft geen concept van bereiken, maar wordt gebruikt om de doel-SAML-toepassing te identificeren waarvoor u een token wilt ontvangen. Voor deze OBO-stroom moet de bereikwaarde altijd de SAML-entiteits-id zijn waaraan /.default is toegevoegd. Als de entiteits-id van de SAML-toepassing bijvoorbeeld is https://testapp.contoso.com, moet het aangevraagde bereik zijn https://testapp.contoso.com/.default. Als de entiteits-id niet begint met een URI-schema zoals https:Microsoft Entra, wordt de entiteits-id voorafgegaan door spn:Microsoft Entra. In dat geval moet u het bereik spn:<EntityID>/.defaultaanvragen, bijvoorbeeld spn:testapp/.default in het geval dat de entiteits-id is testapp. De bereikwaarde die u hier aanvraagt, bepaalt het resulterende Audience element in het SAML-token. Dit kan belangrijk zijn voor de SAML-toepassing die het token ontvangt. |
| requested_token_use | vereist | Hiermee geeft u aan hoe de aanvraag moet worden verwerkt. In de stroom namens de stroom moet de waarde zijn on_behalf_of. |
| requested_token_type | vereist | Geeft het aangevraagde tokentype aan. De waarde kan zijn urn:ietf:params:oauth:token-type:saml2 of urn:ietf:params:oauth:token-type:saml1 afhankelijk van de vereisten van de geopende resource. |
Het antwoord bevat een SAML-token dat is gecodeerd in UTF8 en Base 64url.
- SubjectConfirmationData voor een SAML-assertie die afkomstig is van een OBO-aanroep: Als voor de doeltoepassing een
RecipientwaardeSubjectConfirmationDatais vereist, moet de waarde worden geconfigureerd als de eerste niet-wildcard-antwoord-URL in de configuratie van de resourcetoepassing. Omdat de standaardantwoord-URL niet wordt gebruikt om deRecipientwaarde te bepalen, moet u de antwoord-URL's mogelijk opnieuw ordenen in de toepassingsconfiguratie om ervoor te zorgen dat de eerste niet-wildcard-antwoord-URL wordt gebruikt. Zie Antwoord-URL's voor meer informatie. - Het knooppunt SubjectConfirmationData: het knooppunt kan geen kenmerk bevatten
InResponseTo, omdat het geen deel uitmaakt van een SAML-antwoord. De toepassing die het SAML-token ontvangt, moet de SAML-assertie kunnen accepteren zonder eenInResponseTokenmerk. - API-machtigingen: u moet de benodigde API-machtigingen toevoegen aan de toepassing in de middelste laag om toegang tot de SAML-toepassing toe te staan, zodat er een token kan worden aangevraagd voor het
/.defaultbereik van de SAML-toepassing. - Toestemming: toestemming moet worden verleend om een SAML-token te ontvangen met gebruikersgegevens in een OAuth-stroom. Zie Toestemming verkrijgen voor de toepassing in de middelste laag voor meer informatie.
Antwoord met SAML-assertie
| Parameter | Description |
|---|---|
| token_type | Geeft de waarde van het tokentype aan. Het enige type dat door Microsoft Entra ID wordt ondersteund, is Bearer. Zie OAuth2.2.0 Authorization Framework: Bearer Tokens Usage (RFC 6750) (OAuth2.0 Authorization Framework: Bearer-tokengebruik (RFC 6750)) voor meer informatie over bearer-tokens. |
| bereik | Het toegangsbereik dat in het token wordt verleend. |
| expires_in | De tijdsduur van het toegangstoken is geldig (in seconden). |
| expires_on | De tijd waarop het token verloopt. De datum wordt weergegeven als het aantal seconden van 1970-01-01T0:0:0Z UTC tot de vervaltijd. Deze waarde wordt gebruikt om de levensduur van tokens in de cache te bepalen. |
| resource | De app-id-URI van de ontvangende service (beveiligde resource). |
| access_token | De parameter die de SAML-assertie retourneert. |
| refresh_token | Het vernieuwingstoken. De aanroepende service kan dit token gebruiken om een ander toegangstoken aan te vragen nadat het huidige toegangstoken is verlopen. |
- token_type: Bearer
- expires_in: 3296
- ext_expires_in: 0
- expires_on: 1529627844
- resource:
https://api.contoso.com - access_token: <SAML-assertie>
- issued_token_type: urn:ietf:params:oauth:token-type:saml2
- refresh_token: <Token vernieuwen>
Toestemming krijgen voor de toepassing in de middelste laag
Het doel van de OBO-stroom is om ervoor te zorgen dat de juiste toestemming wordt gegeven, zodat de client-app de middelste laag-app kan aanroepen en de middelste laag-app gemachtigd is om de back-endresource aan te roepen. Afhankelijk van de architectuur of het gebruik van uw toepassing, moet u rekening houden met het volgende om ervoor te zorgen dat de OBO-stroom is geslaagd:
.default en gecombineerde toestemming
De toepassing in de middelste laag voegt de client toe aan de lijst met bekende clienttoepassingen (knownClientApplications) in het manifest. Als een toestemmingsprompt wordt geactiveerd door de client, is de toestemmingsstroom zowel voor zichzelf als de middelste laagtoepassing. Op het Microsoft Identity Platform wordt dit gedaan met behulp van het .default bereik. Het .default bereik is een speciaal bereik dat wordt gebruikt om toestemming te vragen voor toegang tot alle bereiken waarvoor de toepassing machtigingen heeft. Dit is handig wanneer de toepassing toegang nodig heeft tot meerdere resources, maar de gebruiker mag slechts eenmaal om toestemming worden gevraagd.
Wanneer u een toestemmingsscherm activeert met behulp van bekende clienttoepassingen en .default, geeft het toestemmingsscherm machtigingen weer voor zowel de client als de API voor de middelste laag en vraagt u ook de machtigingen aan die zijn vereist voor de API van de middelste laag. De gebruiker geeft toestemming voor beide toepassingen en vervolgens werkt de OBO-stroom.
De resourceservice (API) die in de aanvraag is geïdentificeerd, moet de API zijn waarvoor de clienttoepassing een toegangstoken aanvraagt als gevolg van de aanmelding van de gebruiker. (als u bijvoorbeeld scope=openid https://middle-tier-api.example.com/.default een toegangstoken wilt aanvragen voor de API voor de middelste laag), of scope=openid offline_access .default (wanneer een resource niet wordt geïdentificeerd, wordt deze standaard ingesteld op Microsoft Graph).
Ongeacht welke API wordt geïdentificeerd in de autorisatieaanvraag, wordt de toestemmingsprompt gecombineerd met alle vereiste machtigingen die zijn geconfigureerd voor de client-app. Alle vereiste machtigingen die zijn geconfigureerd voor elke API voor de middelste laag die wordt vermeld in de lijst met vereiste machtigingen van de client, die de client heeft geïdentificeerd als een bekende clienttoepassing, worden ook opgenomen.
Vooraf geverifieerde toepassingen
Resources kunnen aangeven dat een bepaalde toepassing altijd gemachtigd is om bepaalde bereiken te ontvangen. Dit is handig om verbindingen tussen een front-endclient en een back-endresource naadlooser te maken. Een resource kan meerdere vooraf geverifieerde toepassingen (preAuthorizedApplications) declareren in het manifest. Elke dergelijke toepassing kan deze machtigingen aanvragen in een OBO-stroom en deze ontvangen zonder dat de gebruiker toestemming geeft.
toestemming van de beheerder
Een tenantbeheerder kan garanderen dat toepassingen gemachtigd zijn om hun vereiste API's aan te roepen door beheerderstoestemming te verlenen voor de toepassing in de middelste laag. Hiervoor kan de beheerder de toepassing in de middelste laag vinden in de tenant, de pagina vereiste machtigingen openen en ervoor kiezen om de app toestemming te geven. Zie de documentatie voor toestemming en machtigingen voor meer informatie over beheerderstoestemming.
Gebruik van één toepassing
In sommige scenario's zou u slechts één koppeling van de middelste laag en de front-endclient kunnen hebben. In dit scenario kunt u het eenvoudiger vinden om deze één toepassing te maken, waardoor de behoefte aan een toepassing in de middelste laag helemaal wordt genegeerd. Voor verificatie tussen de front-end en de web-API kunt u cookies, een id_token of een toegangstoken gebruiken dat is aangevraagd voor de toepassing zelf. Vraag vervolgens toestemming van deze enkele toepassing aan de back-endresource.
Zie ook
Meer informatie over het OAuth 2.0-protocol en een andere manier om service-naar-serviceverificatie uit te voeren met behulp van clientreferenties.