Védett webes API: Alkalmazásregisztráció

  • Cikk

Ez a cikk a védett webes API-k alkalmazásregisztrációjának sajátosságait ismerteti.

Az alkalmazások regisztrálásának gyakori lépéseit a rövid útmutatóban találja: Alkalmazás regisztrálása a Microsoft Identitásplatform.

Elfogadott jogkivonat-verzió

A Microsoft Identitásplatform 1.0-s és 2.0-s verziós jogkivonatokat bocsáthat ki. További információ ezekről a jogkivonatokról: Access-jogkivonatok.

Az API által elfogadható jogkivonat-verzió a támogatott fióktípusok kiválasztásától függ, amikor webes API-alkalmazásregisztrációt hoz létre az Azure Portalon.

  • Ha a támogatott fióktípusok értéke bármely szervezeti címtárban és személyes Microsoft-fiókban (pl. Skype, Xbox, Outlook.com) található fiókok, az elfogadott jogkivonat-verziónak 2.0-s verziónak kell lennie.
  • Ellenkező esetben az elfogadott jogkivonat verziója lehet 1.0-s verzió.

Az alkalmazás létrehozása után az alábbi lépések végrehajtásával határozhatja meg vagy módosíthatja az elfogadott jogkivonat verzióját:

  1. Az Azure Portalon válassza ki az alkalmazást, majd válassza a Jegyzék elemet.
  2. Keresse meg az accessTokenAcceptedVersion tulajdonságot a jegyzékben.
  3. Az érték megadja a Microsoft Entra számára, hogy a webes API melyik jogkivonat-verziót fogadja el.
    • Ha az érték 2, a webes API 2.0-s jogkivonatokat fogad el.
    • Ha az érték null, a webes API 1.0-s jogkivonatokat fogad el.
  4. Ha módosította a jogkivonat verzióját, válassza a Mentés lehetőséget.

A webes API megadja, hogy melyik jogkivonat-verziót fogadja el. Amikor egy ügyfél jogkivonatot kér a webes API-hoz a Microsoft Identitásplatform, az ügyfél egy jogkivonatot kap, amely jelzi, hogy a webes API melyik jogkivonat-verziót fogadja el.

Nincs átirányítási URI

A webes API-knak nem kell átirányítási URI-t regisztrálniuk, mert nincs interaktívan bejelentkezett felhasználó.

Közzétett API

A webes API-kra vonatkozó egyéb beállítások a közzétett API és a közzétett hatókörök vagy alkalmazásszerepkörök.

Hatókörök és az alkalmazásazonosító URI-ja

A hatókörök általában rendelkeznek az űrlappal resourceURI/scopeName. A Microsoft Graph esetében a hatókörök billentyűparancsokkal rendelkeznek. Például User.Read egy parancsikon a következőhöz https://graph.microsoft.com/user.read: .

Az alkalmazásregisztráció során adja meg az alábbi paramétereket:

  • Az erőforrás URI-ja
  • Egy vagy több hatókör
  • Egy vagy több alkalmazásszerepkör

Alapértelmezés szerint az alkalmazásregisztrációs portál az erőforrás URI használatát api://{clientId}javasolja. Ez az URI egyedi, de nem olvasható emberi. Ha módosítja az URI-t, győződjön meg arról, hogy az új érték egyedi. Az alkalmazásregisztrációs portál biztosítja, hogy konfigurált közzétevői tartományt használjon.

Az ügyfélalkalmazások esetében a hatókörök delegált engedélyekként jelennek meg, az alkalmazásszerepkörök pedig alkalmazásengedélyekként jelennek meg a webes API-hoz.

A hatókörök az alkalmazás felhasználói számára megjelenített hozzájárulási ablakban is megjelennek. Ezért adja meg a hatókört leíró megfelelő sztringeket:

  • Ahogy egy felhasználó látta.
  • Ahogy egy bérlői rendszergazda is láthatja, aki rendszergazdai hozzájárulást adhat.

Az alkalmazásszerepkörökhez nem járulhat hozzá a felhasználó (mivel a webes API-t saját nevében meghívó alkalmazás használja őket). A bérlői rendszergazdának hozzá kell adnia a webes API-nak az alkalmazásszerepkörök felfedéséhez szükséges ügyfélalkalmazásokat. Részletekért lásd Rendszergazda hozzájárulást.

Delegált engedélyek (hatókörök) nyilvánosságra helyezése

Ha delegált engedélyeket vagy hatóköröket szeretne elérhetővé tenni, kövesse az alkalmazás konfigurálása webes API-k felfedéséhez című témakör lépéseit.

Ha az ebben a cikkben ismertetett webes API-forgatókönyvet követi, használja az alábbi beállításokat:

  • Alkalmazásazonosító URI: Fogadja el a javasolt alkalmazásazonosító URI-ját (api://< clientId>) (ha a rendszer kéri)
  • Hatókör neve: access_as_user
  • Kik járulhatnak hozzá: Rendszergazda és felhasználók
  • Rendszergazda hozzájárulás megjelenítendő neve: Access TodoListService felhasználóként
  • Rendszergazda hozzájárulás leírása: Hozzáférés a TodoListService webes API-hoz felhasználóként
  • Felhasználói hozzájárulás megjelenítendő neve: Access TodoListService felhasználóként
  • Felhasználói hozzájárulás leírása: Felhasználóként hozzáfér a TodoListService webes API-hoz
  • Állapot: Engedélyezve

Tipp.

Az alkalmazásazonosító URI-ja esetében lehetősége van például az API https://graph.microsoft.comfizikai szolgáltatójának beállítására. Ez akkor lehet hasznos, ha a meghívandó API URL-címe ismert.

Ha a webes API-t szolgáltatás vagy démonalkalmazás hívja meg

Delegált engedélyek helyett tegye elérhetővé az alkalmazásengedélyeket , ha az API-t démonoknak, szolgáltatásoknak vagy más, nem interaktív (emberi) alkalmazásoknak kell elérnie. Mivel a démon- és szolgáltatás típusú alkalmazások felügyelet nélkül futnak, és saját identitással hitelesítik magukat, nincs olyan felhasználó, aki "delegálhatja" az engedélyét.

Alkalmazásengedélyek (alkalmazásszerepkörök) közzététele

Az alkalmazásengedélyek közzététele érdekében kövesse az Alkalmazásszerepkörök hozzáadása az alkalmazáshoz című témakörben leírt lépéseket.

Az Alkalmazásszerepkör létrehozása panel Engedélyezett tagtípusok csoportjában válassza az Alkalmazások lehetőséget. Vagy adja hozzá a szerepkört az Alkalmazásjegyzék-szerkesztővel a cikkben leírtak szerint.

Hozzáférési jogkivonatok korlátozása adott ügyfélalkalmazásokra

Az alkalmazásszerepkörök azok a mechanizmusok, amelyeket az alkalmazásfejlesztők az alkalmazás engedélyeinek közzététele érdekében használnak. A webes API kódjának ellenőriznie kell az alkalmazásszerepköröket a hívóktól kapott hozzáférési jogkivonatokban.

Egy másik biztonsági réteg hozzáadásához a Microsoft Entra bérlői rendszergazdája konfigurálhatja a bérlőt, hogy a Microsoft Identitásplatform csak az API-hozzáféréshez jóváhagyott ügyfélalkalmazások számára adja ki a biztonsági jogkivonatokat.

A biztonság növelése úgy, hogy csak az alkalmazásszerepkörökhöz hozzárendelt ügyfélalkalmazásokra korlátozza a jogkivonat-kiállítást:

  1. A Microsoft Entra Felügyeleti központban válassza ki az alkalmazást az Identitásalkalmazások>> területen Alkalmazásregisztrációk.
  2. Az alkalmazás áttekintési lapján válassza ki a felügyelt alkalmazást a helyi címtár hivatkozásában, és lépjen a Vállalati alkalmazás áttekintése lapra.
  3. A Kezelés területen válassza a Tulajdonságok elemet.
  4. Állítsa be a hozzárendelést kötelezőnek? az Igen értékre.
  5. Válassza a Mentés lehetőséget.

A Microsoft Entra ID mostantól ellenőrzi azoknak az ügyfélalkalmazásoknak az alkalmazásszerepkör-hozzárendeléseit, amelyek hozzáférési jogkivonatokat kérnek a webes API-hoz. Ha egy ügyfélalkalmazáshoz nincs hozzárendelve alkalmazásszerepkör, a Microsoft Entra ID a invalid_client hasonló hibaüzenetet ad vissza az ügyfélnek : AADSTS501051: Az alkalmazásalkalmazás <neve> nincs hozzárendelve a <webes API-hoz> tartozó szerepkörhöz.

Figyelmeztetés

NE használjon AADSTS hibakódokat vagy üzenetsztringeket literálként az alkalmazás kódjában. Az "AADSTS" hibakódok és a Microsoft Entra ID által visszaadott hibaüzenet-sztringek nem módosíthatók, és a Microsoft bármikor és az Ön tudta nélkül módosíthatja. Ha elágaztatási döntéseket hoz a kódban az AADSTS-kódok vagy üzenetsztringek értékei alapján, az alkalmazás működését és stabilitását kockáztatja.

Következő lépések

A sorozat következő cikke az alkalmazáskód konfigurációja.