Hozzáférési jogkivonatok a Microsoft Identitásplatform

A hozzáférési jogkivonatok lehetővé teszik az ügyfelek számára a védett webes API-k biztonságos meghívását. A webes API-k hozzáférési jogkivonatokat használnak a hitelesítés és az engedélyezés végrehajtásához.

Az OAuth-specifikáció szerint a hozzáférési jogkivonatok olyan átlátszatlan sztringek, amelyekhez nincs megadva formátum. Egyes identitásszolgáltatók (IDP-k) GUID-ket, míg mások titkosított blobokat használnak. A hozzáférési jogkivonat formátuma az azt elfogadó API konfigurációjától függhet.

A fejlesztők által a Microsoft Identitásplatform regisztrált egyéni API-k két különböző JSON-webes jogkivonat -formátum közül választhatnak, amelyeket meghívnak v1.0 és v2.0. A Microsoft által fejlesztett API-k, például a Microsoft Graph vagy az Azure API-k más, saját jogkivonat-formátumokkal rendelkeznek. Ezek a nem érvényesíthető védett formátumok lehetnek titkosított jogkivonatok, JWT-k vagy speciális JWT-szerűek.

A jogkivonat tartalma csak az API-hoz készült, ami azt jelenti, hogy a hozzáférési jogkivonatokat átlátszatlan sztringekként kell kezelni. Csak érvényesítési és hibakeresési célokra a fejlesztők jWT-ket dekódolhatnak egy olyan webhely használatával, mint a jwt.ms. Előfordulhat, hogy a Microsoft API által kapott jogkivonatok nem mindig dekódolható JWT-k.

Az ügyfeleknek a hozzáférési jogkivonattal visszaadott jogkivonat-válaszadatokat kell használniuk a benne található adatok részleteihez. Amikor az ügyfél hozzáférési jogkivonatot kér, a Microsoft Identitásplatform is visszaad néhány metaadatot a hozzáférési jogkivonatról az alkalmazás használatához. Ezek az információk tartalmazzák a hozzáférési jogkivonat lejárati idejét és az érvényes hatóköröket. Ezek az adatok lehetővé teszik az alkalmazás számára a hozzáférési jogkivonatok intelligens gyorsítótárazását anélkül, hogy magát a hozzáférési jogkivonatot kellene elemeznie.

Az alábbi szakaszokból megtudhatja, hogyan érvényesítheti és használhatja az API a jogcímeket egy hozzáférési jogkivonaton belül.

Feljegyzés

Az ezen a lapon található összes dokumentáció, kivéve, ha fel van jegyezve, csak a regisztrált API-khoz kibocsátott jogkivonatokra vonatkozik. Ez nem vonatkozik a Microsoft tulajdonában lévő API-khoz kibocsátott jogkivonatokra, és ezek a jogkivonatok sem használhatók annak ellenőrzésére, hogy a Microsoft Identitásplatform hogyan ad ki jogkivonatokat egy regisztrált API-hoz.

Jogkivonat-formátumok

A hozzáférési jogkivonatok két verziója érhető el a Microsoft Identitásplatform: 1.0-s és 2.0-s verzió. Ezek a verziók határozzák meg a jogkivonatban lévő jogcímeket, és győződjön meg arról, hogy egy webes API szabályozni tudja a jogkivonat tartalmát.

A webes API-k a következő verziók egyikét jelölik ki alapértelmezettként a regisztráció során:

• 1.0-s verzió csak Microsoft Entra-alkalmazásokhoz. Az alábbi példa egy v1.0-s jogkivonatot mutat be (a kulcsok módosulnak, és a személyes adatok törlődnek, ami megakadályozza a jogkivonatok érvényesítését):

  eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiJlZjFkYTlkNC1mZjc3LTRjM2UtYTAwNS04NDBjM2Y4MzA3NDUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTUyMjIyOS8iLCJpYXQiOjE1MzcyMzMxMDYsIm5iZiI6MTUzNzIzMzEwNiwiZXhwIjoxNTM3MjM3MDA2LCJhY3IiOiIxIiwiYWlvIjoiQVhRQWkvOElBQUFBRm0rRS9RVEcrZ0ZuVnhMaldkdzhLKzYxQUdyU091TU1GNmViYU1qN1hPM0libUQzZkdtck95RCtOdlp5R24yVmFUL2tES1h3NE1JaHJnR1ZxNkJuOHdMWG9UMUxrSVorRnpRVmtKUFBMUU9WNEtjWHFTbENWUERTL0RpQ0RnRTIyMlRJbU12V05hRU1hVU9Uc0lHdlRRPT0iLCJhbXIiOlsid2lhIl0sImFwcGlkIjoiNzVkYmU3N2YtMTBhMy00ZTU5LTg1ZmQtOGMxMjc1NDRmMTdjIiwiYXBwaWRhY3IiOiIwIiwiZW1haWwiOiJBYmVMaUBtaWNyb3NvZnQuY29tIiwiZmFtaWx5X25hbWUiOiJMaW5jb2xuIiwiZ2l2ZW5fbmFtZSI6IkFiZSAoTVNGVCkiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMjIyNDcvIiwiaXBhZGRyIjoiMjIyLjIyMi4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJvaWQiOiIwMjIyM2I2Yi1hYTFkLTQyZDQtOWVjMC0xYjJiYjkxOTQ0MzgiLCJyaCI6IkkiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJsM19yb0lTUVUyMjJiVUxTOXlpMmswWHBxcE9pTXo1SDNaQUNvMUdlWEEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6ImFiZWxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJGVnNHeFlYSTMwLVR1aWt1dVVvRkFBIiwidmVyIjoiMS4wIn0.D3H6pMUtQnoJAGq6AHd
  

• 2.0-s verzió a fogyasztói fiókokat támogató alkalmazásokhoz. Az alábbi példa egy v2.0-s jogkivonatot mutat be (a kulcsok módosulnak, és a személyes adatok törlődnek, ami megakadályozza a jogkivonatok érvényesítését):

  eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt
  

Az alkalmazások verziószámának beállításához adja meg a megfelelő értéket az accessTokenAcceptedVersionalkalmazásjegyzékben. A v1.0-s jogkivonatok és null1 az eredmények értéke 2 v2.0-jogkivonatokban.

Jogkivonat tulajdonjoga

A hozzáférési jogkivonat-kérés két félből áll: a jogkivonatot kérő ügyfélből és a jogkivonatot elfogadó erőforrásból (Web API). A jogkivonat (célközönsége) számára szánt erőforrás egy jogkivonat jogcímében aud van definiálva. Az ügyfelek a jogkivonatot használják, de nem érthetik meg vagy nem próbálják elemezni. Az erőforrások elfogadják a jogkivonatot.

A Microsoft Identitásplatform támogatja a jogkivonatok bármely verziójának kiadását bármely verzióvégpontból. Ha például az érték accessTokenAcceptedVersion az 2, egy ügyfél, amely meghívja az 1.0-s verziójú végpontot, hogy jogkivonatot kapjon az adott erőforráshoz, egy v2.0 hozzáférési jogkivonatot kap.

Az erőforrások mindig a jogcím használatával birtokolják a aud jogkivonataikat, és csak azok az alkalmazások, amelyek módosíthatják a jogkivonat részleteit.

A tokenek élettartama

A hozzáférési jogkivonat alapértelmezett élettartama változó. A Microsoft Identitásplatform a hozzáférési jogkivonat alapértelmezett élettartamaként 60–90 perc (átlagosan 75 perc) közötti véletlenszerű értéket rendel hozzá. A változat javítja a szolgáltatás rugalmasságát azáltal, hogy a hozzáférési jogkivonatok igényét egy adott idő alatt elterjeszti, ami megakadályozza a Microsoft Entra ID felé történő forgalom óránkénti megugrását.

A feltételes hozzáférést nem használó bérlők alapértelmezett hozzáférési jogkivonatának élettartama két óra, például a Microsoft Teams és a Microsoft 365 esetében.

A hozzáférési jogkivonat élettartamának módosítása annak szabályozásához, hogy az ügyfélalkalmazás milyen gyakran jár le az alkalmazás munkamenetében, és milyen gyakran követeli meg a felhasználótól az újrahitelesítést (akár csendben, akár interaktívan). Az alapértelmezett hozzáférési jogkivonat élettartam-változatának felülbírálásához használja a Konfigurálható jogkivonat élettartamát (CTL).

Az alapértelmezett jogkivonat élettartam-változatának alkalmazása azokra a szervezetekre, amelyeken engedélyezve van a folyamatos hozzáférés kiértékelése (CAE). Az alapértelmezett jogkivonat élettartam-változatának alkalmazása akkor is, ha a szervezetek CTL-szabályzatokat használnak. A hosszú élettartamú tokenek alapértelmezett élettartama 20 és 28 óra között lehet. Amikor a hozzáférési jogkivonat lejár, az ügyfélnek a frissítési jogkivonat használatával csendesen be kell szereznie egy új frissítési jogkivonatot és hozzáférési jogkivonatot.

Azok a szervezetek, amelyek feltételes hozzáférési bejelentkezési gyakoriságot (SIF) használnak a bejelentkezések gyakoriságának kikényszerítéséhez, nem bírálhatják felül az alapértelmezett hozzáférési jogkivonat élettartamának változását. Ha a szervezetek SIF-t használnak, az ügyfél hitelesítő adatainak kérései közötti idő a jogkivonat élettartama 60–90 perc, valamint a bejelentkezési gyakorisági intervallum.

Íme egy példa a token alapértelmezett élettartam-változatának működésére a bejelentkezési gyakorisággal. Tegyük fel, hogy egy szervezet óránként beállítja a bejelentkezés gyakoriságát. Ha a jogkivonat élettartama a token élettartamának változása miatt 60–90 perc között van, a tényleges bejelentkezési időköz 1 óra és 2,5 óra között történik.

Ha egy egyórás élettartamú jogkivonattal rendelkező felhasználó 59 percen belül végez interaktív bejelentkezést, nincs hitelesítőadat-kérés, mert a bejelentkezés a SIF küszöbértéke alatt van. Ha egy új jogkivonat élettartama 90 perc, a felhasználó másfél órán át nem látna hitelesítő adatokat. Csendes megújítási kísérlet során a Microsoft Entra-azonosító hitelesítő adatokat kér, mert a munkamenet teljes hossza túllépte az 1 órás bejelentkezési gyakorisági beállítást. Ebben a példában a hitelesítő adatok kérései közötti időkülönbség az SIF-intervallum és a token élettartamának változása miatt 2,5 óra lenne.

Jogkivonatok érvényesítése

Nem minden alkalmazásnak kell érvényesítenie a jogkivonatokat. Csak bizonyos esetekben érvényesítse az alkalmazások a jogkivonatot:

• A webes API-knak ellenőrizniük kell az ügyfél által nekik küldött hozzáférési jogkivonatokat. Csak az egyik AppId URI-t tartalmazó jogkivonatokat fogadhatják el jogcímként aud .
• A webalkalmazásoknak a felhasználói adatokhoz való hozzáférés engedélyezése vagy munkamenet létrehozása előtt ellenőrizniük kell a felhasználó böngészőjével a számukra küldött azonosító jogkivonatokat.

Ha a korábban ismertetett forgatókönyvek egyike sem érvényes, akkor nincs szükség a jogkivonat érvényesítésére. Az olyan nyilvános ügyfelek, mint a natív, asztali vagy egyoldalas alkalmazások, nem élvezik az azonosító jogkivonatok érvényesítését, mivel az alkalmazás közvetlenül kommunikál az identitásszolgáltatóval, ahol az SSL-védelem biztosítja az azonosító jogkivonatok érvényességét. Nem szabad ellenőrizniük a hozzáférési jogkivonatokat, mivel a webes API-nak kell érvényesítenie, nem pedig az ügyfélnek.

Az API-knak és a webalkalmazásoknak csak az alkalmazásnak megfelelő jogcímekkel rendelkező aud jogkivonatokat kell érvényesíteniük. Más erőforrásokhoz egyéni jogkivonat-érvényesítési szabályok tartozhatnak. A Microsoft Graph-jogkivonatok például a saját formátumuk miatt nem érvényesíthetők a szabályok szerint. Egy másik erőforráshoz tartozó jogkivonatok érvényesítése és elfogadása a hibás helyettes probléma példája.

Ha az alkalmazásnak érvényesítenie kell egy azonosító jogkivonatot vagy egy hozzáférési jogkivonatot, először ellenőriznie kell a jogkivonat és a kiállító aláírását az OpenID felderítési dokumentumban szereplő értékek alapján.

A Microsoft Entra köztes szoftver beépített képességekkel rendelkezik a hozzáférési jogkivonatok érvényesítéséhez, a megfelelő nyelven történő kereséshez lásd a mintákat . A JWT-ellenőrzéshez számos külső nyílt forráskódú kódtár is rendelkezésre áll. A hitelesítési kódtárakról és a kódmintákról további információt a hitelesítési kódtárakban talál. Ha a webalkalmazás vagy a webes API ASP.NET vagy ASP.NET Core-on található, használja a Microsoft.Identity.Web alkalmazást, amely kezeli az Ön számára az ellenőrzést.

1.0-s és 2.0-s verziós jogkivonatok

• Ha a webalkalmazás/API egy v1.0-s jogkivonatot (verjogcím ="1.0" jogcímet) érvényesít, akkor is be kell olvasnia az OpenID Csatlakozás metaadat-dokumentumot a v1.0 végpontról (https://login.microsoftonline.com/{example-tenant-id}/.well-known/openid-configurationmég akkor is, ha a webes API-hoz konfigurált szolgáltató egy v2.0-s szolgáltató).
• Ha a webalkalmazás/API egy v2.0-s jogkivonatot (verjogcím ="2.0" jogcímet) érvényesít, akkor is be kell olvasnia az OpenID Csatlakozás metaadat-dokumentumot a v2.0 végpontról (https://login.microsoftonline.com/{example-tenant-id}/v2.0/.well-known/openid-configurationmég akkor is, ha a webes API-hoz konfigurált szolgáltató egy 1.0-s verziójú szolgáltató).

Az alábbi példák feltételezik, hogy az alkalmazás egy 2.0-s verziójú hozzáférési jogkivonatot érvényesít (ezért hivatkozik az OIDC metaadat-dokumentumainak és kulcsainak 2.0-s verziójára). Csak távolítsa el a "/v2.0" értéket az URL-címből, ha érvényesíti az 1.0-s jogkivonatokat.

A kiállító ellenőrzése

OpenID Csatlakozás Core mondja: "A kiállító azonosítója [...] Pontosan meg kell egyeznie az iss (kiállító) jogcím értékével." A bérlőspecifikus metaadat-végpontot (hasonló vagy https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configurationhasonlóhttps://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/.well-known/openid-configuration) használó alkalmazások esetében csak erre van szükség.

A Microsoft Entra ID rendelkezik a dokumentum bérlőfüggetlen verziójával, amely a következő címen https://login.microsoftonline.com/common/v2.0/.well-known/openid-configurationérhető el: . Ez a végpont egy kiállítói értéket https://login.microsoftonline.com/{tenantid}/v2.0ad vissza. Az alkalmazások ezt a bérlőfüggetlen végpontot használhatják minden bérlő jogkivonatainak érvényesítéséhez az alábbi módosításokkal:

1. Ahelyett, hogy a jogkivonatban szereplő kiállítói jogcím pontosan megfelel a metaadatokból származó kiállítói értéknek, az alkalmazásnak a kiállító metaadataiban szereplő értéket az aktuális kérés céljának megfelelő bérlőazonosítóra kell cserélnie {tenantid} , majd ellenőriznie kell a pontos egyezést.

2. Az alkalmazásnak a issuer kulcsvégponttól visszaadott tulajdonságot kell használnia a kulcsok hatókörének korlátozásához.

   • A kiállítói értékkel https://login.microsoftonline.com/{tenantid}/v2.0 rendelkező kulcsok bármely egyező jogkivonat-kiállítóval használhatók.
   • A kiállítói értékkel https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0 rendelkező kulcsokat csak pontos egyezéssel szabad használni.

   A Microsoft Entra bérlőfüggetlen kulcsvégpontja (https://login.microsoftonline.com/common/discovery/v2.0/keys) a következő dokumentumokat adja vissza:

   {
     "keys":[
       {"kty":"RSA","use":"sig","kid":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","x5t":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","n":"spv...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
       {"kty":"RSA","use":"sig","kid":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","x5t":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","n":"wEM...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
       {"kty":"RSA","use":"sig","kid":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","x5t":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","n":"rv0...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0"}
     ]
   }
   

3. A Microsoft Entra tenantid (tid) jogcímet a standard kiállítói jogcím helyett megbízhatósági határként használó alkalmazásoknak biztosítaniuk kell, hogy a bérlőazonosító jogcím guid legyen, és hogy a kiállító és a bérlőazonosító egyezzen.

A bérlőfüggetlen metaadatok használata hatékonyabb az olyan alkalmazások esetében, amelyek számos bérlőtől fogadnak jogkivonatokat.

Feljegyzés

A Microsoft Entra bérlőfüggetlen metaadataival a jogcímeket a bérlőn belül kell értelmezni, csakúgy, mint a standard OpenID Csatlakozás, a jogcímeket a kiállítón belül. Ez azt is jelent, {"sub":"ABC123","iss":"https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0","tid":"aaaabbbb-0000-cccc-1111-dddd2222eeee"} és {"sub":"ABC123","iss":"https://login.microsoftonline.com/bbbbcccc-1111-dddd-2222-eeee3333ffff/v2.0","tid":"bbbbcccc-1111-dddd-2222-eeee3333ffff"} írja le a különböző felhasználókat, annak ellenére, hogy ez sub ugyanaz, mert a jogcímeket a sub rendszer a kiállító/bérlő kontextusában értelmezi.

Az aláírás ellenőrzése

A JWT három, a karakterrel elválasztott szegmenst . tartalmaz. Az első szegmens a fejléc, a második a törzs, a harmadik pedig az aláírás. Az aláírási szegmens használatával értékelje ki a jogkivonat hitelességét.

A Microsoft Entra ID az iparági szabvány aszimmetrikus titkosítási algoritmusokkal, például RS256-tal aláírt jogkivonatokat ad ki. A JWT fejléce információkat tartalmaz a jogkivonat aláírásához használt kulcsról és titkosítási módszerről:

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk",
  "kid": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk"
}

A alg jogcím a jogkivonat aláírásához használt algoritmust jelöli, míg a kid jogcím a jogkivonat érvényesítéséhez használt konkrét nyilvános kulcsot jelöli.

A Microsoft Entra ID bármikor aláírhat egy azonosító jogkivonatot egy bizonyos nyilvános-privát kulcspárok bármelyikének használatával. A Microsoft Entra ID rendszeres időközönként elforgatja a lehetséges kulcsokat, ezért írja meg az alkalmazást, hogy automatikusan kezelje ezeket a kulcsmódosításokat. A Microsoft Entra ID által használt nyilvános kulcsok frissítéseinek ellenőrzésének ésszerű gyakorisága 24 óránként történik.

Szerezze be az aláírás ellenőrzéséhez szükséges aláírókulcs-adatokat az OpenID Csatlakozás metaadat-dokumentum használatával, amely a következő helyen található:

https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration

Tipp.

Próbálja ki ezt egy böngészőben: URL-cím

Az alábbi információk a metaadat-dokumentumot ismertetik:

• Olyan JSON-objektum, amely számos hasznos információt tartalmaz, például az OpenID Csatlakozás hitelesítéshez szükséges különböző végpontok helyét.
• Tartalmaz egy jwks_uriolyan nyilvános kulcskészletet, amely a jogkivonatok aláírásához használt titkos kulcsoknak megfelelő nyilvános kulcsok helyét adja meg. A JSON-webkulcs (JWK) az jwks_uri adott időpontban használt összes nyilvános kulcsinformációt tartalmazza. Az RFC 7517 a JWK formátumot írja le. Az alkalmazás a kid JWT fejlécben található jogcím használatával kiválaszthatja a nyilvános kulcsot a dokumentumból, amely megfelel az adott jogkivonat aláírásához használt titkos kulcsnak. Ezután a megfelelő nyilvános kulccsal és a megadott algoritmussal végezhet aláírás-ellenőrzést.

Feljegyzés

A jogcím használatával kid érvényesítheti a jogkivonatot. Bár az 1.0-s jogkivonatok mind a jogcímeket, mind a x5tkid jogcímeket tartalmazzák, a 2.0-s verziós jogkivonatok csak a kid jogcímet tartalmazzák.

Az aláírás-ellenőrzés a dokumentum hatókörén kívül esik. Számos nyílt forráskódú kódtár érhető el, amelyek segítenek az aláírás ellenőrzésében, ha szükséges. A Microsoft Identitásplatform azonban egy jogkivonat-aláírási kiterjesztéssel rendelkezik a szabványokhoz, amelyek egyéni aláírási kulcsok.

Ha az alkalmazás egyéni aláíró kulcsokkal rendelkezik a jogcímleképezési funkció használata miatt, fűzze hozzá az appid alkalmazásazonosítót tartalmazó lekérdezési paramétert. Az ellenőrzéshez használja jwks_uri az alkalmazás aláírókulcs-adatait. Például: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=00001111-aaaa-2222-bbbb-3333cccc4444 tartalmaz egyjwks_uri.https://login.microsoftonline.com/{tenant}/discovery/keys?appid=00001111-aaaa-2222-bbbb-3333cccc4444

A kiállító ellenőrzése

Az azonosító jogkivonatokat érvényesítő webalkalmazásoknak és a hozzáférési jogkivonatokat érvényesítő webes API-knak ellenőriznie kell a jogkivonat (iss jogcím) kiállítóját a következőkkel szemben:

1. az OpenID connect metaadat-dokumentumban elérhető kiállító, amely az alkalmazáskonfigurációhoz (szolgáltatóhoz) van társítva. Az ellenőrizni kívánt metaadat-dokumentum a következőtől függ:
   • a jogkivonat verziója
   • az alkalmazás által támogatott fiókokat.
2. a jogkivonat bérlőazonosítója (tid jogcíme),
3. az aláírókulcs kiállítója.

Egybérlős alkalmazások

OpenID Csatlakozás Core mondja: "A kiállító azonosítója [...] PONTOSAN meg kell egyeznie a iss (kiállítói) jogcím értékével." Bérlőspecifikus metaadat-végpontot (például https://login.microsoftonline.com/{example-tenant-id}/v2.0/.well-known/openid-configuration vagy https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration.

Az egybérlős alkalmazások olyan alkalmazások, amelyek támogatják a következőket:

• Fiókok egy szervezeti címtárban (csak példa-bérlőazonosító ): https://login.microsoftonline.com/{example-tenant-id}
• Csak személyes Microsoft-fiókok: https://login.microsoftonline.com/consumers (a felhasználók a 9188040d-6c67-4c5b-b112-36a304b66dad bérlő beceneve)

Több-bérlős alkalmazások

A Microsoft Entra ID a több-bérlős alkalmazásokat is támogatja. Ezek az alkalmazások támogatják a következőt:

• Bármely szervezeti címtárban (bármely Microsoft Entra-címtárban) található fiókok: https://login.microsoftonline.com/organizations
• Bármely szervezeti címtárban (bármely Microsoft Entra-címtárban) és személyes Microsoft-fiókban (például Skype, XBox) lévő fiókok: https://login.microsoftonline.com/common

Ezeknél az alkalmazásoknál a Microsoft Entra ID az OIDC-dokumentum bérlőfüggetlen verzióit teszi elérhetővé a következő helyen https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration és https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration helyen: Ezek a végpontok egy kiállítói értéket ad vissza, amely a következő https://login.microsoftonline.com/{tenantid}/v2.0által tenantidparametrizált sablon. Az alkalmazások ezeket a bérlőfüggetlen végpontokat használhatják minden bérlő jogkivonatainak érvényesítéséhez az alábbi kikötésekkel:

• Az aláírókulcs-kiállító ellenőrzése
• Ahelyett, hogy a jogkivonatban szereplő kiállítói jogcím pontosan megfelel a metaadatokból származó kiállítói értéknek, az alkalmazásnak a kiállító metaadataiban szereplő értéket az aktuális kérés céljának megfelelő bérlőazonosítóra kell cserélnie {tenantid} , majd ellenőriznie kell a pontos egyezést (tid a jogkivonat jogcímét).
• Ellenőrizze, hogy a tid jogcím GUID-ként van-e megállítva, és a iss jogcím azon az űrlapon https://login.microsoftonline.com/{tid}/v2.0 van, ahol {tid} a pontos tid jogcím szerepel. Ez az ellenőrzés visszakonti a bérlőt a kiállítóhoz, majd vissza az aláírási kulcs hatóköréhez, amely megbízhatósági láncot hoz létre.
• A jogcímet akkor használja tid , ha megkeresi a jogcím tárgyát képező adatokat. Más szóval a tid jogcímnek a felhasználó adatainak eléréséhez használt kulcsnak kell lennie.

Az aláírókulcs-kiállító ellenőrzése

A v2.0-s bérlőfüggetlen metaadatokat használó alkalmazásoknak ellenőriznie kell az aláírókulcs-kiállítót.

Kulcsok dokumentuma és aláírókulcs-kiállítója

Amint arról már szó volt, az OpenID Csatlakozás dokumentumból az alkalmazás hozzáfér a jogkivonatok aláírásához használt kulcsokhoz. A megfelelő kulcsok dokumentumát az OpenId Csatlakozás dokumentum jwks_uri tulajdonságában közzétett URL-cím elérésével kapja meg.

 "jwks_uri": "https://login.microsoftonline.com/{example-tenant-id}/discovery/v2.0/keys",

Az {example-tenant-id} érték helyettesíthető guid azonosítóval, tartománynévvel vagy gyakori szervezetekkel és fogyasztókkal

Az keys Azure AD v2.0 által közzétett dokumentumok minden kulcshoz tartalmazzák az aláíró kulcsot használó kiállítót. A bérlőfüggetlen "common" kulcsvégpont https://login.microsoftonline.com/common/discovery/v2.0/keys például a következő dokumentumokat adja vissza:

{
  "keys":[
    {"kty":"RSA","use":"sig","kid":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","x5t":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","n":"spv...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","x5t":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","n":"wEM...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","x5t":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","n":"rv0...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0"}
  ]
}

Az aláírókulcs-kiállító ellenőrzése

Az alkalmazásnak a issuer kulcsok hatókörének korlátozása érdekében a kulcsok dokumentumának tulajdonságát kell használnia a jogkivonat aláírásához használt kulcshoz társítva:

• A GUID azonosítóval https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0 rendelkező kiállítói értékkel rendelkező kulcsokat csak akkor szabad használni, ha a iss jogkivonat jogcíme pontosan megfelel az értéknek.
• A sablonalapú kiállítói értékkel https://login.microsoftonline.com/{tenantid}/v2.0 rendelkező kulcsokat csak akkor szabad használni, ha a iss jogkivonat jogcíme megfelel ennek az értéknek{tenantid}, miután a tid jogcímet a helyőrző jogkivonatában helyettesítettük.

A bérlőfüggetlen metaadatok használata hatékonyabb az olyan alkalmazások esetében, amelyek számos bérlőtől fogadnak jogkivonatokat.

Feljegyzés

A Microsoft Entra bérlőfüggetlen metaadataival a jogcímeket a bérlőn belül kell értelmezni, csakúgy, mint a standard OpenID Csatlakozás, a jogcímeket a kiállítón belül. Ez azt is jelent, {"sub":"ABC123","iss":"https://login.microsoftonline.com/{example-tenant-id}/v2.0","tid":"{example-tenant-id}"} és {"sub":"ABC123","iss":"https://login.microsoftonline.com/{another-tenand-id}/v2.0","tid":"{another-tenant-id}"} írja le a különböző felhasználókat, annak ellenére, hogy ez sub ugyanaz, mert a jogcímeket a sub rendszer a kiállító/bérlő kontextusában értelmezi.

Összefoglalás

Íme néhány álkód, amely összefoglalja a kiállító és az aláírókulcs-kiállító érvényesítésének módját:

1. Kulcsok lekérése a konfigurált metaadatok URL-címéről
2. Ellenőrizze a jogkivonatot, ha a közzétett kulcsok egyikével van aláírva, sikertelen, ha nem
3. Azonosítsa a kulcsot a metaadatokban a gyermekfejléc alapján. Ellenőrizze a metaadat-dokumentum kulcsához csatolt "kiállító" tulajdonságot:

   var issuer = metadata["kid"].issuer;
   if (issuer.contains("{tenantId}", CaseInvariant)) issuer = issuer.Replace("{tenantid}", token["tid"], CaseInvariant);
   if (issuer != token["iss"]) throw validationException;
   if (configuration.allowedIssuer != "*" && configuration.allowedIssuer != issuer) throw validationException;
   var issUri = new Uri(token["iss"]);
   if (issUri.Segments.Count < 1) throw validationException;
   if (issUri.Segments[1] != token["tid"]) throw validationException;
   

Lásd még

• Hozzáférési jogkivonat jogcímeinek referenciája
• Alkalmazások és API-k védelme jogcímek érvényesítésével

Következő lépések

• További információ a Microsoft Entra ID-ban használt biztonsági jogkivonatokról.