Share via

Microsoft Identitásplatform és OAuth 2.0 On-Behalf-Of flow

  • Cikk

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 OAuth2.0 on-behalf-of folyamat megjelenítése

  1. Az ügyfélalkalmazás az A jogkivonattal (API A jogcímmel) aud kéri az API A-t.
  2. 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.
  3. 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.
  4. 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.
  5. 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\":[\"9ab03e19-ed42-4168-b6b7-7001fb3e933a\"]}}}"
}

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ára Recipient szolgá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ást InResponseTo .
  • 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 /.default SAML-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>

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:

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.

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.