API-k védelme az Azure API Managementben az OAuth 2.0 hitelesítés és a Microsoft Entra ID használatával

  • Cikk

A KÖVETKEZŐRE VONATKOZIK: Minden API Management-szint

Ebben a cikkben az OAuth 2.0 protokoll és a Microsoft Entra ID protokoll használatával konfigurálhatja az Azure API Management-példányt az API védelmére.

Az API-engedélyezés elméleti áttekintését lásd : Hitelesítés és API-k engedélyezése az API Managementben.

Előfeltételek

A cikk lépéseinek végrehajtása előtt a következőkkel kell rendelkeznie:

  • API Management-példány
  • Közzétett API az API Management-példány használatával
  • Egy Microsoft Entra bérlő

Áttekintés

Kövesse az alábbi lépéseket egy API védelméhez az API Managementben OAuth 2.0-hitelesítéssel a Microsoft Entra ID-val.

  1. Regisztráljon egy alkalmazást (ebben a cikkben a háttéralkalmazást) a Microsoft Entra ID-ban az API-hoz való hozzáférés védelme érdekében.

    Az API eléréséhez a felhasználók vagy alkalmazások egy érvényes OAuth-jogkivonatot szereznek be és mutatnak be, amely minden API-kéréshez hozzáférést biztosít az alkalmazáshoz.

  2. Konfigurálja a validate-jwt szabályzatot az API Managementben az egyes bejövő API-kérésekben bemutatott OAuth-jogkivonat érvényesítéséhez. Érvényes kérések továbbíthatók az API-nak.

Az OAuth-engedélyezési folyamatokkal és a szükséges OAuth-jogkivonatok létrehozásának módjával kapcsolatos részletek túlmutatnak a jelen cikk hatókörén. Általában egy külön ügyfélalkalmazással szerez be jogkivonatokat a Microsoft Entra ID-ból, amely engedélyezi az API-hoz való hozzáférést. További információkra mutató hivatkozásokért tekintse meg a következő lépéseket.

Alkalmazás regisztrálása a Microsoft Entra-azonosítóban az API-t ábrázoló módon

Az Azure Portal használatával védje meg az API-t a Microsoft Entra-azonosítóval, először regisztráljon egy alkalmazást, amely az API-t képviseli.

Az alkalmazásregisztrációval kapcsolatos részletekért tekintse meg a rövid útmutatót: Alkalmazás konfigurálása webes API-k megjelenítéséhez.

  1. Az Azure Portalon keresse meg és válassza ki a Alkalmazásregisztrációk.

  2. Új regisztráció kiválasztása.

  3. Amikor megjelenik az Alkalmazás regisztrálása lap, adja meg az alkalmazás regisztrációs adatait:

    • A Név szakaszban adjon meg egy értelmes alkalmazásnevet, amely megjelenik az alkalmazás felhasználóinak, például a háttéralkalmazásnak.
    • A Támogatott fióktípusok szakaszban válasszon egy, a forgatókönyvnek megfelelő lehetőséget.

  4. Hagyja üresen az Átirányítás URI szakaszt.

  5. Válassza a Regisztráció elemet az alkalmazás létrehozásához.

  6. Az Alkalmazás áttekintése lapon keresse meg az alkalmazás (ügyfél) azonosítójának értékét, és jegyezze fel későbbre.

  7. Az oldalmenü Kezelés szakaszában válassza az API-k felfedése lehetőséget, és állítsa be az alkalmazásazonosító URI-ját az alapértelmezett értékkel. Ha egy külön ügyfélalkalmazást fejleszt, amely OAuth 2.0-jogkivonatokat szerez be a háttéralkalmazáshoz való hozzáféréshez, jegyezze fel ezt az értéket későbbre.

  8. A Hatókör hozzáadása lap megjelenítéséhez válassza a Hatókör hozzáadása gombot:

    1. Adjon meg egy új hatókörnevet, Rendszergazda hozzájárulás megjelenítendő nevét és Rendszergazda hozzájárulás leírását.
    2. Győződjön meg arról, hogy az Engedélyezett hatókör állapota ki van jelölve.

  9. A hatókör létrehozásához válassza a Hatókör hozzáadása gombot.

  10. Ismételje meg az előző két lépést az API által támogatott összes hatókör hozzáadásához.

  11. A hatókörök létrehozása után jegyezze fel őket későbbi használatra.

JWT érvényesítési szabályzat konfigurálása a kérések előzetes engedélyezéséhez

Az alábbi példaszabályzat a <inbound> szabályzatszakaszhoz hozzáadva ellenőrzi a célközönség jogcímének értékét egy, az Engedélyezés fejlécben található Microsoft Entra-azonosítóból beszerzett hozzáférési jogkivonatban. Hibaüzenetet ad vissza, ha a jogkivonat érvénytelen. Konfigurálja ezt a szabályzatot a forgatókönyvnek megfelelő szabályzat hatókörében.

  • openid-config Az URL-címben ez aad-tenant a Microsoft Entra-azonosító bérlőazonosítója. Keresse meg ezt az értéket az Azure Portalon, például a Microsoft Entra-erőforrás Áttekintés lapján. Az alábbi példa egy egybérlős Microsoft Entra-alkalmazást és egy v2-konfigurációs végpontot feltételez.
  • Az érték a claim Microsoft Entra ID-ban regisztrált háttéralkalmazás ügyfél-azonosítója.
<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/{aad-tenant}/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>{audience-value - (ex:api://guid)}</audience>
    </audiences>
    <issuers>
        <issuer>{issuer-value - (ex: https://sts.windows.net/{tenant id}/)}</issuer>
    </issuers>
    <required-claims>
        <claim name="aud">
            <value>{backend-app-client-id}</value>
        </claim>
    </required-claims>
</validate-jwt>

Feljegyzés

Az előző openid-config URL-cím a v2-végpontnak felel meg. A v1 openid-config végponthoz használja a következőt https://login.microsoftonline.com/{aad-tenant}/.well-known/openid-configuration: .

A szabályzatok konfigurálásáról további információt a Szabályzatok beállítása vagy szerkesztése című témakörben talál. A JWT-érvényesítések további testreszabásához tekintse meg a validate-jwt referenciát. A Microsoft Entra szolgáltatás által biztosított JWT érvényesítéséhez az API Management a szabályzatot validate-azure-ad-token is biztosítja.

Engedélyezési munkafolyamat

  1. Egy felhasználó vagy alkalmazás jogkivonatot szerez be a Microsoft Entra-azonosítóból olyan engedélyekkel, amelyek hozzáférést biztosítanak a háttéralkalmazáshoz.

  2. A jogkivonat az API-kérések engedélyezési fejlécében lesz hozzáadva az API Managementhez.

  3. Az API Management a szabályzat használatával ellenőrzi a jogkivonatot validate-jwt .

    • Ha egy kérelem nem rendelkezik érvényes jogkivonattal, az API Management letiltja azt.

    • Ha egy kéréshez érvényes jogkivonat tartozik, az átjáró továbbíthatja a kérést az API-nak.

Következő lépések