Microsoft Identitásplatform és OAuth 2.0 On-Behalf-Of flow
A helyszíni (OBO) folyamat egy olyan webes API forgatókönyvét írja le, amely nem a saját identitását használja egy másik webes API meghívására. Az OAuth-ban delegálásnak nevezett cél egy felhasználó identitásának és engedélyeinek átadása a kérelemláncon keresztül.
Ahhoz, hogy a középső szintű szolgáltatás hitelesített kéréseket küldjön az alsóbb rétegbeli szolgáltatásnak, biztonságossá kell tennie egy hozzáférési jogkivonatot a Microsoft Identitásplatform. Csak delegált hatóköröket használ, és nem alkalmazásszerepköröket. A szerepkörök továbbra is az egyszerűhöz (a felhasználóhoz) kapcsolódnak, és soha nem csatlakoznak a felhasználó nevében működő alkalmazáshoz. Ez megakadályozza, hogy a felhasználó engedélyt kapjon azokhoz az erőforrásokhoz, amelyekhez nem férhetnek hozzá.
Ez a cikk azt ismerteti, hogy hogyan programozhat közvetlenül a protokollra építve az alkalmazásban. Azt javasoljuk, hogy amikor lehetséges, inkább a támogatott Microsoft hitelesítési kódtárakat (MSAL) használja a tokenek beszerzéséhez és biztonságos webes API-k meghívásához. Példákért tekintse meg az MSAL-t használó mintaalkalmazásokat is.
Ügyfélkorlátozások
Ha egy szolgáltatásnév csak alkalmazásalapú jogkivonatot kért, és elküldte egy API-nak, akkor az API kicserél egy olyan jogkivonatot, amely nem az eredeti szolgáltatásnevet képviseli. Ennek az az oka, hogy az OBO-folyamat csak a felhasználói tagok számára működik. Ehelyett az ügyfél hitelesítő adatainak folyamatával kell lekérnie egy csak alkalmazáshoz használható jogkivonatot. Az egyoldalas alkalmazások (SLA-k) esetében egy hozzáférési jogkivonatot kell átadniuk egy középső rétegbeli bizalmas ügyfélnek az OBO-folyamatok végrehajtásához.
Ha egy ügyfél implicit folyamatot használ egy id_token lekéréséhez, és helyettesítő karaktereket is tartalmaz egy válasz URL-címben, a id_token nem használható OBO-folyamathoz. A helyettesítő karakterek egy karakterrel * végződő URL-címek. Ha például a válasz URL-címe volt, https://myapp.com/* a id_token nem lehet használni, mert nem elég specifikus az ügyfél azonosításához. Ez megakadályozná a jogkivonat kiadását. Az implicit engedélyezési folyamaton keresztül beszerzett hozzáférési jogkivonatokat azonban egy bizalmas ügyfél is beváltja, még akkor is, ha a kezdeményező ügyfélhez helyettesítő válasz URL-cím van regisztrálva. Ennek az az oka, hogy a bizalmas ügyfél azonosítani tudja a hozzáférési jogkivonatot beszerző ügyfelet. A bizalmas ügyfél ezután a hozzáférési jogkivonat használatával szerezhet be egy új hozzáférési jogkivonatot az alsóbb rétegbeli API-hoz.
Emellett az egyéni aláírókulcsokkal rendelkező alkalmazások nem használhatók középső szintű API-kként az OBO-folyamatban. Ide tartoznak az egyszeri bejelentkezéshez konfigurált vállalati alkalmazások. Ha a középső szintű API egyéni aláírókulcsot használ, az alsóbb rétegbeli API nem ellenőrzi a neki átadott hozzáférési jogkivonat aláírását. Ez hibát eredményez, mert az ügyfél által vezérelt kulccsal aláírt jogkivonatok nem fogadhatók el biztonságosan.
Protokolldiagram
Tegyük fel, hogy a felhasználó hitelesített egy alkalmazást az OAuth 2.0 engedélyezési kód engedélyezési folyamatával vagy egy másik bejelentkezési folyamattal. Ezen a ponton az alkalmazás rendelkezik egy hozzáférési jogkivonattal az API A -hoz (A jogkivonat), a felhasználó jogcímeivel és a középső szintű webes API (API A) eléréséhez való hozzájárulással. Most az API A-nak hitelesített kérést kell küldenie az alsóbb rétegbeli webes API-hoz (API B).
Az alábbi lépések alkotják az OBO-folyamatot, és az alábbi diagram segítségével magyarázzák el.
- Az ügyfélalkalmazás az A jogkivonattal (API A jogcímmel)
audkéri az API A-t. - Az API A hitelesíti a Microsoft Identitásplatform jogkivonat-kiállítási végpontot, és jogkivonatot kér a B API eléréséhez.
- A Microsoft Identitásplatform jogkivonat-kiállítási végpont ellenőrzi az API A hitelesítő adatait az A jogkivonattal együtt, és kibocsátja a B API hozzáférési jogkivonatát (B jogkivonat) az API A-hoz.
- A B jogkivonatot az API A állítja be a B API-nak küldött kérés engedélyezési fejlécében.
- A védett erőforrásból származó adatokat az API B adja vissza az API A-nak, majd az ügyfélnek.
Ebben a forgatókönyvben a középső szintű szolgáltatás nem rendelkezik felhasználói beavatkozással a felhasználó hozzájárulásának lekéréséhez az alsóbb rétegbeli API eléréséhez. Ezért az alsóbb rétegbeli API-hoz való hozzáférés engedélyezésének lehetősége a hitelesítés során a hozzájárulási lépés részeként jelenik meg. Ha meg szeretné tudni, hogyan valósíthatja meg ezt az alkalmazást, olvassa el a középső rétegbeli alkalmazás hozzájárulásának megszerzését ismertető témakört.
Középső szintű hozzáférési jogkivonat kérése
Hozzáférési jogkivonat kéréséhez hozzon létre egy HTTP POST-t a bérlőspecifikus Microsoft Identitásplatform tokenvégponthoz az alábbi paraméterekkel.
https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
Figyelmeztetés
NE küldjön olyan hozzáférési jogkivonatokat, amelyeket a középső rétegnek adtak ki, kivéve a jogkivonat célközönségét. A középső rétegnek kibocsátott hozzáférési jogkivonatokat csak az adott középső réteg használja a célközönség kívánt végpontjával való kommunikációhoz.
A hozzáférési jogkivonatok középszintű erőforrásból ügyfélre történő átfoglalásának biztonsági kockázatai (a hozzáférési jogkivonatokat lekért ügyfél helyett) a következők:
- Nagyobb a jogkivonatok elfogásának kockázata a feltört SSL-/TLS-csatornákkal szemben.
- A jogkivonat kötésének és a feltételes hozzáférésnek a jogcímek felfelé történő felfelé történő teljesítését igénylő forgatókönyvek (például MFA, bejelentkezési gyakoriság) kielégítése.
- Inkompatibilitás a rendszergazda által konfigurált eszközalapú szabályzatokkal (például MDM, helyalapú szabályzatok).
Két eset van attól függően, hogy az ügyfélalkalmazás közös titkos kóddal vagy tanúsítvánnyal védi-e.
Első eset: Hozzáférési jogkivonat-kérés megosztott titkos kóddal
Megosztott titkos kód használata esetén a szolgáltatásközi hozzáférési jogkivonat-kérés a következő paramétereket tartalmazza:
| Paraméter | Típus | Leírás |
|---|---|---|
grant_type |
Kötelező | A jogkivonat-kérés típusa. JWT-t használó kérés esetén az értéknek meg kell lennie urn:ietf:params:oauth:grant-type:jwt-bearer. |
client_id |
Kötelező | Az alkalmazás (ügyfél) azonosítója, amelyet a Microsoft Entra Felügyeleti központ Alkalmazásregisztrációk az alkalmazáshoz rendelt lap. |
client_secret |
Kötelező | Az alkalmazáshoz létrehozott ügyfélkód a Microsoft Entra Felügyeleti központban – Alkalmazásregisztrációk oldalon. Az RFC 6749-es verziójában a hitelesítő adatok megadása helyett az alapszintű hitelesítési minta is támogatott. |
assertion |
Kötelező | A középső szintű API-nak küldött hozzáférési jogkivonat. Ennek a jogkivonatnak rendelkeznie kell az OBO-kérést küldő alkalmazás célközönségi (aud) jogcímével (a client-id mező által jelölt alkalmazással). Az alkalmazások nem tudják beváltani a jogkivonatot egy másik alkalmazáshoz (például ha egy ügyfél a Microsoft Graph számára szánt tokent küld egy API-nak, az API nem tudja beváltani az OBO használatával. Ehelyett el kell utasítania a jogkivonatot). |
scope |
Kötelező | A jogkivonat-kérelem hatóköreinek szóközzel elválasztott listája. További információ: hatókörök. |
requested_token_use |
Kötelező | Meghatározza a kérés feldolgozásának módját. Az OBO-folyamatban az értéket a következőre kell állítani on_behalf_of: . |
Példa
Az alábbi HTTP POST egy hozzáférési jogkivonatot és egy frissítési jogkivonatot kér a https://graph.microsoft.com webes API hatóköréveluser.read. A kérés az ügyfél titkos kódjával van aláírva, és egy bizalmas ügyfél végzi.
//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
Második eset: Hozzáférési jogkivonat kérése tanúsítvánnyal
A szolgáltatás-szolgáltatás közötti hozzáférési jogkivonat-kérés tanúsítványsal az előző példában szereplő paraméterek mellett a következő paramétereket is tartalmazza:
| Paraméter | Típus | Leírás |
|---|---|---|
grant_type |
Kötelező | A jogkivonat-kérelem típusa. JWT-t használó kérés esetén az értéknek meg kell lennie urn:ietf:params:oauth:grant-type:jwt-bearer. |
client_id |
Kötelező | Az alkalmazás (ügyfél) azonosítója, amelyet a Microsoft Entra Felügyeleti központ Alkalmazásregisztrációk az alkalmazáshoz rendelt lap. |
client_assertion_type |
Kötelező | Az értéknek a következőnek kell lennie urn:ietf:params:oauth:client-assertion-type:jwt-bearer: . |
client_assertion |
Kötelező | Egy olyan állítás (JSON webes jogkivonat), amelyet létre kell hoznia és alá kell írnia az alkalmazás hitelesítő adataiként regisztrált tanúsítvánnyal. A tanúsítvány regisztrálásáról és az állítás formátumáról a tanúsítvány hitelesítő adatai című témakörben olvashat. |
assertion |
Kötelező | A középső szintű API-nak küldött hozzáférési jogkivonat. Ennek a jogkivonatnak rendelkeznie kell az OBO-kérést küldő alkalmazás célközönségi (aud) jogcímével (a client-id mező által jelölt alkalmazással). Az alkalmazások nem tudják beváltani a jogkivonatot egy másik alkalmazáshoz (például ha egy ügyfél MS Graph-hoz készült tokent küld egy API-nak, az API nem tudja beváltani az OBO használatával. Ehelyett el kell utasítania a jogkivonatot). |
requested_token_use |
Kötelező | Meghatározza a kérés feldolgozásának módját. Az OBO-folyamatban az értéket a következőre kell állítani on_behalf_of: . |
scope |
Kötelező | A jogkivonat-kérelem hatóköreinek szóközzel tagolt listája. További információ: hatókörök. |
Figyelje meg, hogy a paraméterek majdnem ugyanazok, mint a közös titkos kóddal történő kérés esetében, azzal a kivételrel, hogy a client_secret paramétert két paraméter váltja fel: a client_assertion_type és client_assertion. A client_assertion_type paraméter értéke urn:ietf:params:oauth:client-assertion-type:jwt-bearer és a client_assertion paraméter a tanúsítvány titkos kulcsával aláírt JWT-jogkivonatra van állítva.
Példa
Az alábbi HTTP POST egy hozzáférési jogkivonatot kér a webes API hatókörével user.readhttps://graph.microsoft.com egy tanúsítvánnyal. A kérés az ügyfél titkos kódjával van aláírva, és egy bizalmas ügyfél végzi.
// 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
Középső szintű hozzáférési jogkivonat válasza
A sikeres válasz egy JSON OAuth 2.0-válasz az alábbi paraméterekkel.
| Paraméter | Leírás |
|---|---|
token_type |
A jogkivonat típusértékét jelzi. Az Microsoft Identitásplatform csak a következő típust Bearertámogatja: . További információ a tulajdonosi jogkivonatokról: OAuth 2.0 Engedélyezési keretrendszer: Bearer Token Usage (RFC 6750). |
scope |
A jogkivonatban megadott hozzáférés hatóköre. |
expires_in |
A hozzáférési jogkivonat érvényességének időtartama másodpercben. |
access_token |
A kért hozzáférési jogkivonat. A hívószolgáltatás ezzel a jogkivonattal hitelesítheti magát a fogadó szolgáltatásban. |
refresh_token |
A kért hozzáférési jogkivonat frissítési jogkivonata. A hívószolgáltatás ezzel a jogkivonattal kérhet egy másik hozzáférési jogkivonatot az aktuális hozzáférési jogkivonat lejárata után. A frissítési jogkivonat csak akkor érhető el, ha a offline_access hatókört kérték. |
Példa a sikeres válaszra
Az alábbi példa egy sikeres választ mutat be a webes API hozzáférési jogkivonatára vonatkozó kérésre https://graph.microsoft.com . A válasz tartalmaz egy hozzáférési jogkivonatot és egy frissítési jogkivonatot, és a tanúsítvány titkos kulcsával van aláírva.
{
"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}"
}
Ez a hozzáférési jogkivonat a Microsoft Graph 1.0-s formátumú jogkivonata. Ennek az az oka, hogy a jogkivonat formátuma a hozzáférés alatt álló erőforráson alapul, és nem kapcsolódik a kéréshez használt végpontokhoz. A Microsoft Graph úgy van beállítva, hogy fogadja el az 1.0-s verziós jogkivonatokat, így a Microsoft Identitásplatform 1.0-s hozzáférési jogkivonatokat állít elő, amikor egy ügyfél jogkivonatokat kér a Microsoft Graphhoz. Más alkalmazások jelezhetik, hogy v2.0 formátumú jogkivonatokat, 1.0 formátumú jogkivonatokat, vagy akár védett vagy titkosított jogkivonat-formátumokat szeretnének. Az 1.0-s és a 2.0-s verziójú végpontok egyaránt kibocsáthatják a jogkivonatok bármelyik formátumát. Így az erőforrás mindig a megfelelő jogkivonat-formátumot kapja, függetlenül attól, hogy az ügyfél hogyan vagy hol kéri a jogkivonatot.
Figyelmeztetés
Ne kísérelje meg a jogkivonatok érvényesítését vagy olvasását a kódban a nem birtokolt API-k esetében, beleértve az ebben a példában szereplő jogkivonatokat is. A Microsoft-szolgáltatások jogkivonatai olyan speciális formátumot használhatnak, amely nem érvényesíthető JWT-ként, és titkosíthatók a fogyasztói (Microsoft-fiók) felhasználók számára is. Bár a jogkivonatok olvasása hasznos hibakeresési és tanulási eszköz, ne vegyen fel függőségeket a kódban, és ne feltételezze a nem ön által vezérelt API-khoz tartozó jogkivonatokat.
Példa hibaválaszra
A jogkivonatvégpont hibaüzenetet ad vissza, amikor hozzáférési jogkivonatot próbál beszerezni az alsóbb rétegbeli API-hoz, ha az alsóbb rétegbeli API feltételes hozzáférési szabályzattal (például többtényezős hitelesítéssel) rendelkezik. A középső szintű szolgáltatásnak ezt a hibát fel kell tárnia az ügyfélalkalmazásnak, hogy az ügyfélalkalmazás a feltételes hozzáférési szabályzatnak megfelelő felhasználói interakciót biztosítson.
Ha ezt a hibát vissza szeretné adni az ügyfélnek, a középső rétegbeli szolgáltatás a HTTP 401 Jogosulatlan és egy WWW-Authenticate HTTP fejléccel válaszol, amely tartalmazza a hibát és a jogcím-kihívást. Az ügyfélnek elemeznie kell ezt a fejlécet, és be kell szereznie egy új jogkivonatot a jogkivonat-kiállítótól, és be kell mutatnia a jogcímekkel kapcsolatos kihívást, ha van ilyen. Az ügyfeleknek nem szabad újrapróbálkoznia, hogy gyorsítótárazott hozzáférési jogkivonattal férhessenek hozzá a középső rétegbeli szolgáltatáshoz.
{
"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\"]}}}"
}
A hozzáférési jogkivonat használata a védett erőforrás eléréséhez
A középső rétegbeli szolgáltatás most már használhatja a korábban beszerzett jogkivonatot, hogy hitelesített kéréseket küldjön az alsóbb rétegbeli webes API-nak a jogkivonat fejlécben való Authorization beállításával.
Példa
GET /v1.0/me HTTP/1.1
Host: graph.microsoft.com
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
OAuth2.0 OBO-folyamattal kapott SAML-állítások
Egyes OAuth-alapú webszolgáltatásoknak más webszolgáltatás API-kat kell elérnie, amelyek saml-állításokat fogadnak el nem interaktív folyamatokban. A Microsoft Entra ID képes SAML-helyességi feltételt biztosítani egy olyan folyamat nevében történő folyamatra válaszul, amely SAML-alapú webszolgáltatást használ célerőforrásként.
Ez az OAuth 2.0 On-Behalf-Of folyamat nem szabványos kiterjesztése, amely lehetővé teszi, hogy egy OAuth2-alapú alkalmazás hozzáférjen az SAML-jogkivonatokat használó webszolgáltatás API-végpontjaihoz.
Tipp.
Amikor saml által védett webszolgáltatást hív meg egy előtérbeli webalkalmazásból, egyszerűen meghívhatja az API-t, és normál interaktív hitelesítési folyamatot kezdeményezhet a felhasználó meglévő munkamenetével. Csak akkor kell OBO-folyamatot használnia, ha egy szolgáltatásközi híváshoz SAML-jogkivonatra van szükség a felhasználói környezet biztosításához.
SAML-jogkivonat beszerzése megosztott titkos kóddal rendelkező OBO-kéréssel
Egy SAML-állítás szolgáltatásközi kérése a következő paramétereket tartalmazza:
| Paraméter | Típus | Leírás |
|---|---|---|
| engedélyezési típus | kötelező | A jogkivonat-kérelem típusa. JWT-t használó kérés esetén az értéknek meg kell lennie urn:ietf:params:oauth:grant-type:jwt-bearer. |
| követelés | kötelező | A kérelemben használt hozzáférési jogkivonat értéke. |
| ügyfél azonosítója | kötelező | A hívó szolgáltatáshoz rendelt alkalmazásazonosító a Microsoft Entra ID-val való regisztráció során. Ha meg szeretné keresni az alkalmazásazonosítót a Microsoft Entra Felügyeleti központban, keresse meg az Identitásalkalmazások>> lehetőséget Alkalmazásregisztrációk majd válassza ki az alkalmazás nevét. |
| titkos ügyfélkód | kötelező | A hívó szolgáltatáshoz regisztrált kulcs a Microsoft Entra-azonosítóban. Ezt az értéket a regisztrációkor fel kell jegyezni. Az RFC 6749-es verziójában a hitelesítő adatok megadása helyett az alapszintű hitelesítési minta is támogatott. |
| hatálya | kötelező | A jogkivonat-kérelem hatóköreinek szóközzel tagolt listája. További információ: hatókörök. Maga az SAML nem rendelkezik hatókörök fogalmával, hanem annak a cél SAML-alkalmazásnak a azonosítására szolgál, amelyhez jogkivonatot szeretne kapni. Ehhez az OBO-folyamathoz a hatókör értékének mindig hozzáfűzett SAML-entitásazonosítónak /.default kell lennie. Ha például az SAML-alkalmazás entitásazonosítója, https://testapp.contoso.comakkor a kért hatókörnek kell lennie https://testapp.contoso.com/.default. Abban az esetben, ha az entitásazonosító nem URI-sémával kezdődik, például https:a Microsoft Entra előtaggal ítja meg az entitásazonosítót spn:. Ebben az esetben a hatókört spn:<EntityID>/.defaultkell kérnie, például spn:testapp/.default abban az esetben, ha az entitás azonosítója .testapp Az itt kért hatókörérték határozza meg az SAML-jogkivonat eredményül kapott Audience elemét, ami fontos lehet a jogkivonatot fogadó SAML-alkalmazás számára. |
| requested_token_use | kötelező | Meghatározza a kérés feldolgozásának módját. A megbízási folyamatban az értéknek a következőnek kell lennie on_behalf_of: . |
| requested_token_type | kötelező | Megadja a kért jogkivonat típusát. Az érték lehet urn:ietf:params:oauth:token-type:saml2 vagy urn:ietf:params:oauth:token-type:saml1 attól függően, hogy milyen követelményekkel rendelkezik a hozzáféréssel rendelkező erőforrás. |
A válasz egy UTF8-ban és Base 64url-ben kódolt SAML-jogkivonatot tartalmaz.
- SubjectConfirmationData egy OBO-hívásból származó SAML-állításhoz: Ha a célalkalmazáshoz értékre
SubjectConfirmationDatavan szükségRecipient, akkor az értéket konfigurálnia kell az erőforrásalkalmazás konfigurációjának első nem kötelező válasz URL-címeként. Mivel az alapértelmezett válasz URL-cím nem az érték meghatározásáraRecipientszolgál, előfordulhat, hogy újra kell rendeznie a Válasz URL-címeket az alkalmazás konfigurációjában, hogy a rendszer az első nem adkarakerccsel rendelkező válasz URL-címet használja. További információ: Válasz URL-címek. - SubjectConfirmationData csomópont: A csomópont nem tartalmazhat attribútumot
InResponseTo, mivel nem része SAML-válasznak. Az SAML-jogkivonatot fogadó alkalmazásnak attribútum nélkül el kell tudnia fogadnia az SAML-állítástInResponseTo. - API-engedélyek: Hozzá kell adnia a szükséges API-engedélyeket a középső szintű alkalmazáshoz az SAML-alkalmazáshoz való hozzáférés engedélyezéséhez, hogy jogkivonatot igényelhessen az
/.defaultSAML-alkalmazás hatóköréhez. - Hozzájárulás: Hozzájárulást kell adni az OAuth-folyamat felhasználói adatait tartalmazó SAML-jogkivonat fogadásához. További információ: Hozzájárulás megszerzése a középső rétegbeli alkalmazáshoz.
Válasz SAML-állítással
| Paraméter | Leírás |
|---|---|
| token_type | A jogkivonat típusértékét jelzi. A Microsoft Entra ID által támogatott egyetlen típus a Bearer. További információ a tulajdonosi jogkivonatokról: OAuth 2.0 Engedélyezési keretrendszer: Bearer Token Usage (RFC 6750). |
| hatálya | A jogkivonatban megadott hozzáférés hatóköre. |
| expires_in | A hozzáférési jogkivonat érvényessége (másodpercben). |
| expires_on | A hozzáférési jogkivonat lejárati ideje. A dátum az 1970-01-01T0:0:0Z UTC-től a lejárati időig eltelt másodpercek száma. Ez az érték határozza meg a gyorsítótárazott jogkivonatok élettartamát. |
| erőforrás | A fogadó szolgáltatás (biztonságos erőforrás) alkalmazásazonosítójának URI-ja. |
| access_token | Az SAML-helyességi feltételt visszaadó paraméter. |
| refresh_token | A frissítési jogkivonat. A hívószolgáltatás ezzel a jogkivonattal kérhet egy másik hozzáférési jogkivonatot az aktuális SAML-érvényesség lejárta után. |
- token_type: Tulajdonos
- expires_in: 3296
- ext_expires_in: 0
- expires_on: 1529627844
- Erőforrás:
https://api.contoso.com - access_token: <SAML-állítás>
- issued_token_type: urn:ietf:params:oauth:token-type:saml2
- refresh_token: <Jogkivonat frissítése>
Hozzájárulás megszerzése a középső rétegbeli alkalmazáshoz
Az OBO-folyamat célja, hogy megfelelő hozzájárulást kapjon, hogy az ügyfélalkalmazás meghívhassa a középső rétegbeli alkalmazást, a középső rétegbeli alkalmazás pedig jogosult legyen a háttérerőforrás meghívására. Az alkalmazás architektúrájától vagy használatától függően az alábbiakat kell figyelembe vennie, hogy az OBO-folyamat sikeres legyen:
.default és kombinált hozzájárulás
A középső rétegbeli alkalmazás hozzáadja az ügyfelet az ismert ügyfélalkalmazások listájához (knownClientApplications) a jegyzékben. Ha az ügyfél aktivál egy hozzájárulási kérést, a hozzájárulási folyamat önmagára és a középső rétegbeli alkalmazásra is érvényes. A Microsoft Identitásplatform ez a .default hatókör használatával történik. A .default hatókör egy speciális hatókör, amellyel hozzájárulást kérhet az alkalmazás által engedélyekkel rendelkező összes hatókör eléréséhez. Ez akkor hasznos, ha az alkalmazásnak több erőforráshoz kell hozzáférnie, de a felhasználót csak egyszer kell hozzájárulásra kérni.
Ha a hozzájárulási képernyőt ismert ügyfélalkalmazások használatával aktiválja, és .defaulta hozzájárulási képernyő mindkét ügyfélnek a középső szintű API-hoz való engedélyeit jeleníti meg, valamint a középső szintű API által igényelt engedélyeket is kéri. A felhasználó mindkét alkalmazáshoz hozzájárul, majd az OBO-folyamat működik.
A kérelemben azonosított erőforrás-szolgáltatásnak (API) az az API-nak kell lennie, amelyhez az ügyfélalkalmazás hozzáférési jogkivonatot kér a felhasználó bejelentkezése miatt. Például scope=openid https://middle-tier-api.example.com/.default (hozzáférési jogkivonat kérése a középső szintű API-hoz), vagy scope=openid offline_access .default (ha egy erőforrás nincs azonosítva, akkor az alapértelmezés szerint a Microsoft Graph lesz).
Függetlenül attól, hogy az engedélyezési kérelem melyik API-t azonosítja, a hozzájárulási kérés az ügyfélalkalmazáshoz konfigurált összes szükséges engedéllyel együtt jelenik meg. Az ügyfél kötelező engedélylistájában felsorolt, az ügyfél által ismert ügyfélalkalmazásként azonosított összes középszintű API-hoz konfigurált összes szükséges engedély is szerepel.
Előre elkészített alkalmazások
Az erőforrások jelezhetik, hogy egy adott alkalmazás mindig rendelkezik engedéllyel bizonyos hatókörök fogadásához. Ez hasznos lehet az előtérbeli ügyfél és a háttérerőforrás közötti kapcsolatok zökkenőmentesebbé tétele érdekében. Egy erőforrás több előhitelesített alkalmazást (preAuthorizedApplications) deklarálhat a jegyzékben. Bármely ilyen alkalmazás kérheti ezeket az engedélyeket egy OBO-folyamatban, és megkaphatja azokat a felhasználó beleegyezése nélkül.
Rendszergazdai jóváhagyás
A bérlői rendszergazdák garantálhatják, hogy az alkalmazások rendelkeznek engedéllyel a szükséges API-k meghívására, ha rendszergazdai hozzájárulást adnak a középső szintű alkalmazáshoz. Ehhez a rendszergazda megtalálhatja a középső rétegbeli alkalmazást a bérlőjében, megnyithatja a szükséges engedélyoldalt, és engedélyt adhat az alkalmazásnak. A rendszergazdai hozzájárulással kapcsolatos további információkért tekintse meg a hozzájárulási és engedélydokumentációt.
Egyetlen alkalmazás használata
Bizonyos esetekben csak egyetlen párosítással rendelkezhet a középszintű és az előtér-ügyfél között. Ebben a forgatókönyvben egyszerűbbé teheti ezt az alkalmazást egyetlen alkalmazássá, ami teljesen szükségtelenné teszi a középszintű alkalmazás szükségességét. Az előtérbeli és a webes API közötti hitelesítéshez használhat cookie-kat, id_token vagy az alkalmazáshoz kért hozzáférési jogkivonatot. Ezután kérjen hozzájárulást ettől az egyetlen alkalmazástól a háttérerőforráshoz.
Lásd még
Tudjon meg többet az OAuth 2.0 protokollról, valamint az ügyfél hitelesítő adataival történő szolgáltatásszolgáltatás másik módjáról.