Termékek és API-k biztonságos elérése Microsoft Entra-alkalmazásokkal

A KÖVETKEZŐKRE VONATKOZIK: Fejlesztő | Alapszintű | Standard | Prémium

Az API Management mostantól támogatja a beépített OAuth 2.0 alkalmazásalapú hozzáférést a termék API-khoz az ügyfél hitelesítő adatainak folyamatával. Ez a funkció lehetővé teszi, hogy az API-kezelők regisztrálják a Microsoft Entra ID-alkalmazásokat, és OAuth 2.0-hitelesítéssel egyszerűsíthessék a fejlesztők biztonságos API-hozzáférését.

Megjegyzés:

Az alkalmazások jelenleg korlátozott előzetes verzióban érhetők el. A regisztrációhoz töltse ki ezt az űrlapot.

Ezzel a funkcióval:

  • Az API-kezelők beállítanak egy terméktulajdonságot az alkalmazásalapú hozzáférés engedélyezéséhez.
  • Az API-kezelők ügyfélalkalmazásokat regisztrálnak a Microsoft Entra-azonosítóban az adott termékekhez való hozzáférés korlátozásához.
  • A fejlesztők az API Management fejlesztői portálon férhetnek hozzá az ügyfélalkalmazás hitelesítő adataihoz.
  • Az OAuth 2.0 ügyfél-hitelesítő adatokra vonatkozó folyamattal a fejlesztők vagy alkalmazások olyan tokeneket szereznek be, amelyeket belefoglalhatnak az API-kérésekben.
  • Az API Management átjáró hitelesíti az API-kérésekben megjelenített tokeneket, hogy engedélyezze a hozzáférést a termék API-jaihoz.

Előfeltételek

  • Prémium ,Standard, Alapszintű vagy Fejlesztői szinten üzembe helyezett API Management-példány. Ha telepítenie kell egy példányt, tekintse meg az API Management szolgáltatáspéldány létrehozása útmutatót.

  • Legalább egy termék az API Management-példányban, amelyhez legalább egy API van hozzárendelve.

    • A terméknek közzétett állapotban kell lennie, hogy a fejlesztők elérhessék a fejlesztői portálon keresztül.
    • Teszteléshez használhatja az alapértelmezett Starter terméket és a hozzá hozzáadott Echo API-t.
    • Ha létre szeretne hozni egy terméket, olvassa el a Termék létrehozása és közzététele című témakört.

  • A Microsoft Entra-bérlőben elegendő engedély szükséges az alkalmazásadminisztrátori szerepkör hozzárendeléséhez, amelyhez legalább a kiemelt szerepkör-rendszergazdai szerepkör szükséges.

  • Igény szerint vegyen fel egy vagy több felhasználót az API Management-példányba.

Felügyelt identitás konfigurálása

  1. Engedélyezze a rendszer által hozzárendelt felügyelt identitást az API Managementhez az API Management-példányban.

  2. Rendelje hozzá az identitást az alkalmazásadminisztrátor RBAC-szerepköréhez a Microsoft Entra-azonosítóban. A szerepkör hozzárendelése:

    1. Jelentkezzen be a portálra , és lépjen a Microsoft Entra-azonosítóra.
    2. A bal oldali menüben válassza aSzerepkörök és rendszergazdák> lehetőséget.
    3. Válassza az Alkalmazásadminisztrátor lehetőséget.
    4. A bal oldali menüben válassza aHozzárendelések>kezelése>+ Hozzárendelések hozzáadása lehetőséget.
    5. A Hozzárendelések hozzáadása lapon név szerint keresse meg az API Management-példány felügyelt identitását (az API Management-példány nevét). Válassza ki a felügyelt identitást, majd válassza a Hozzáadás lehetőséget.

Alkalmazásalapú hozzáférés engedélyezése a termékhez

Az alábbi lépéseket követve engedélyezheti az alkalmazásalapú hozzáférést egy termékhez. Egy terméknek engedélyeznie kell ezt a beállítást ahhoz, hogy az ügyfélalkalmazáshoz a későbbi lépésekben társítható legyen.

Az alábbi példa a Starter terméket használja, de válasszon olyan közzétett terméket, amelyhez legalább egy API van hozzárendelve.

  1. Jelentkezzen be a portálra a következő egyéni URL-címen az alkalmazások funkciójához: https://portal.azure.com/?feature.customPortal=false& Microsoft_Azure_ApiManagement=alkalmazások
  2. Navigáljon az API Management-példányhoz.
  3. A bal oldali menü API-k területén válassza a Termékek lehetőséget.
  4. Válassza ki a konfigurálni kívánt terméket, például a Starter terméket.
  5. A bal oldali menü Termék területén válassza a Tulajdonságok lehetőséget.
  6. Az Alkalmazásalapú hozzáférés szakaszban engedélyezze az OAuth 2.0 token (legbiztonságosabb) beállítását.
  7. Ha szeretné, engedélyezze az előfizetési kulcs beállítását. Ha az alkalmazásalapú hozzáférést és az előfizetési követelményt is engedélyezi, az API Management-átjáró elfogadhat egy OAuth 2.0-jogkivonatot vagy egy előfizetési kulcsot a termék API-khoz való hozzáféréshez.
  8. Válassza az Mentésgombot.

Képernyőkép az alkalmazásalapú hozzáférés engedélyezéséről a portálon.

Jótanács

Új termék létrehozásakor az OAuth 2.0 jogkivonat-beállítást is engedélyezheti.

Az alkalmazásalapú hozzáférés engedélyezése egy háttérbeli vállalati alkalmazást hoz létre a Microsoft Entra-azonosítóban a termék megjelenítéséhez. A háttéralkalmazás azonosítója megjelenik a termék Tulajdonságok lapján.

Képernyőkép a termék alkalmazásbeállításairól a portálon.

Megjegyzés:

Ez az alkalmazásazonosító célközönségértékként van beállítva, amikor ügyfélalkalmazást hoz létre a termék eléréséhez. Ezt az értéket használja a termék API hívásához szükséges token generálása során is.

(Nem kötelező) Termékalkalmazás-beállítások áttekintése a Microsoft Entra-azonosítóban

Igény szerint tekintse át a Microsoft Entra-azonosítóban létrehozott háttéralkalmazás beállításait a termék megjelenítéséhez.

Az alkalmazás neve a következő formátumban történik: APIMProductApplication<terméknév>. Ha például a termék neve Starter, az alkalmazás neve APIMProductApplicationStarter. Az alkalmazáshoz alkalmazásszerepkör van definiálva.

Alkalmazásbeállítások áttekintése az alkalmazásregisztrációkban:

  1. Jelentkezzen be a portálra, és navigáljon a Microsoft Entra ID>Alkalmazásregisztrációk elemre.
  2. Válassza az Összes alkalmazás lehetőséget.
  3. Keresse meg és válassza ki az API Management által létrehozott alkalmazást.
  4. A bal oldali menü Kezelés területén válassza az Alkalmazásszerepkörök lehetőséget.
  5. Erősítse meg az Azure API Management által beállított alkalmazásszerepkört az alábbi képernyőképen látható módon:

Képernyőkép az alkalmazásszerepkörökről a portálon.

Ügyfélalkalmazás regisztrálása a termék eléréséhez

Most regisztráljon egy ügyfélalkalmazást, amely egy vagy több termékhez való hozzáférést korlátozza.

  • Egy terméknek engedélyeznie kell az alkalmazásalapú hozzáférést ahhoz, hogy egy ügyfélalkalmazáshoz lehessen társítani.
  • Minden ügyfélalkalmazás egyetlen felhasználóval (tulajdonossal) rendelkezik az API Management-példányban. Csak a tulajdonos férhet hozzá a termék API-khoz az alkalmazáson keresztül.
  • Egy termék több ügyfélalkalmazáshoz is társítható.

Ügyfélalkalmazás regisztrálása:

  1. Jelentkezzen be a portálra a következő egyéni URL-címen az alkalmazások funkciójához: https://portal.azure.com/?feature.customPortal=false& Microsoft_Azure_ApiManagement=alkalmazások

  2. Navigáljon az API Management-példányhoz.

  3. A bal oldali menü API-k területén válassza az Alkalmazások>+ Alkalmazás regisztrálása lehetőséget.

  4. Az Alkalmazás regisztrálása lapon adja meg a következő alkalmazásbeállításokat:

    • Név: Adja meg az alkalmazás nevét.
    • Tulajdonos: Válassza ki az alkalmazás tulajdonosát az API Management-példány felhasználóinak legördülő listájából.
    • Hozzáférés biztosítása a kiválasztott termékekhez: Válasszon ki egy vagy több olyan terméket az API Management-példányban, amely korábban engedélyezve volt az alkalmazásalapú hozzáféréshez.
    • Leírás: Igény szerint adjon meg egy leírást.

    Képernyőkép a portál alkalmazásbeállításairól.

  5. Válassza a Regisztrálás lehetőséget.

Az alkalmazás hozzáadódik az alkalmazások listájához az Alkalmazások lapon. Válassza ki az alkalmazást az olyan részletek megtekintéséhez, mint az ügyfélazonosító. Az azonosítóra szükség van egy token létrehozásához az API hívása érdekében.

Jótanács

  • Az alkalmazás létrehozása után tetszés szerint társíthatja más termékekkel. Válassza ki az alkalmazást az Alkalmazások lapon, majd válassza a Részletek>termékek>+ Termék hozzáadása lehetőséget.
  • Az alkalmazásokat úgy is létrehozhatja vagy társíthatja, hogy szerkeszt egy terméket a Termékek lapon.

Titkos ügyfélkód létrehozása

Az OAuth 2.0 ügyfél hitelesítőadat-folyamatának használatához létre kell hozni egy ügyfélkulcsot az ügyfélalkalmazás számára. A titkos kód egy évig érvényes, de bármikor újragenerálható.

  1. Az Alkalmazások lapon válassza ki a létrehozott alkalmazást.

  2. Az alkalmazás Áttekintés lapján, az Ügyfél titkos kódja mellett válassza a Titkos kód hozzáadása lehetőséget.

  3. Az Új titkos ügyfélkód lapon válassza a Létrehozás lehetőséget.

    A rendszer létrehoz egy ügyfélkulcsot, és megjelenik az Ügyfélkód mezőben. Győződjön meg arról, hogy a titkos kulcs értékét kimásolja, és biztonságosan tárolja. A lap bezárása után nem fogja tudni újból lekérni.

  4. Válassza a Bezárás lehetőséget.

(Nem kötelező) Ügyfélalkalmazás-beállítások áttekintése a Microsoft Entra-azonosítóban

Igény szerint tekintse át az ügyfélalkalmazás beállításait a Microsoft Entra-azonosítóban.

Az alkalmazás neve a következő formátumban történik: APIMApplication<terméknév>. Ha például a termék neve Starter, az alkalmazás neve hasonló az APIMApplicationStarterhez.

Alkalmazásbeállítások áttekintése az alkalmazásregisztrációkban:

  1. Jelentkezzen be a portálra, és navigáljon a Microsoft Entra ID>Alkalmazásregisztrációk elemre.

  2. Válassza az Összes alkalmazás lehetőséget.

  3. Keresse meg és válassza ki az API Management által létrehozott ügyfélalkalmazást.

  4. A bal oldali menü Kezelés csoportjában válassza az API-engedélyeket.

  5. Győződjön meg arról, hogy az alkalmazás rendelkezik hozzáféréssel a háttérbeli termékalkalmazáshoz vagy -alkalmazásokhoz.

    Ha például az ügyfélalkalmazás hozzáférést ad a Starter termékhez, az alkalmazás Product.Starter.All engedéllyel rendelkezik az APIMProductApplicationStarter alkalmazás eléréséhez.

    Képernyőkép az API-engedélyekről a portálon.

Alkalmazásbeállítások lekérése a fejlesztői portálon

A felhasználók bejelentkezhetnek a fejlesztői portálra a tulajdonában lévő ügyfélalkalmazások megtekintéséhez.

  1. Jelentkezzen be a fejlesztői portálra (https://<your-apim-instance-name>.developer.azure-api.net) egy ügyfélalkalmazás tulajdonosaként beállított felhasználói fiókkal.

  2. A felső navigációs menüben válassza az Alkalmazások lehetőséget.

  3. A felhasználó tulajdonában lévő alkalmazások megjelennek a listában.

  4. Válasszon ki egy alkalmazást annak részleteinek megtekintéséhez, például az ügyfélazonosítót, az ügyfél titkos kódját és a hatókört. Ezek az értékek szükségesek a termék API-k meghívásához szükséges token generálásához.

    Képernyőkép a fejlesztői portál ügyfélalkalmazásairól.

Jelölő létrehozása és API hívásban való használata

Miután engedélyezte egy termék alkalmazásalapú hozzáférését, és regisztrált egy ügyfélalkalmazást, a fejlesztő vagy alkalmazás létrehozhat egy jogkivonatot a termék API-inak meghívásához. A tokennek szerepelnie kell a Authorization kérés fejlécében.

Egy fejlesztő vagy alkalmazás például a következő Azure PowerShell-szkripteket futtatva meghívhatja az ügyfélalkalmazást egy jogkivonat létrehozásához, majd a jogkivonat használatával meghívhat egy termék API-t az API Managementben.

Figyelmeztetés

Az alábbi szkriptek csak tesztelési célokra szolgálnak példák. Éles környezetben használjon biztonságos módszert az ügyfél titkos kódjának tárolására és lekérésére.

Hívja meg az ügyfélalkalmazást a token létrehozásához

# Replace placeholder values with your own values.

$clientId = "00001111-aaaa-2222-bbbb-3333cccc4444" # Client (application) ID of client application
$clientSecret = "******" # Retrieve secret of client application in developer portal
$scopeOfOtherApp = "api://55556666-ffff-7777-aaaa-8888bbbb9999/.default" # Value of Audience in product properties
$tenantId = "aaaabbbb-0000-cccc-1111-dddd2222eeee" # Directory (tenant) ID in Microsoft Entra ID

$body = @{
    grant_type    = "client_credentials"
    client_id     = $clientId
    client_secret = $clientSecret
    scope         = $scopeOfOtherApp
}
$response = Invoke-RestMethod -Method Post -Uri "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" -ContentType "application/x-www-form-urlencoded" -Body $body
$token = $response.access_token

Termék API meghívása token használatával

Az előző lépésben létrehozott jogkivonat egy termék API meghívására szolgál. A jogkivonat a kérelem Engedélyezési fejlécében lesz átadva. Az API Management példány érvényesíti a tokent, és engedélyezi az API-hoz való hozzáférést.

Az alábbi szkript egy példahívást mutat be az echo API-hoz.

# Gatewate endpoint to call. Update with URI of API operation you want to call.
$uri = "https://<gateway-hostname>/echo/resource?param1=sample"
$headers = @{
   "Authorization" = "Bearer $token"  # $token is the token generated in the previous script.
}
$body = @{
    "hello" = "world"
} | ConvertTo-Json -Depth 5

$getresponse = Invoke-RestMethod -Method Post -Uri $uri -ContentType "application/x-www-form-urlencoded" -Headers $headers -Body $body
Write-Host "Response:"
$getresponse | ConvertTo-Json -Depth 5

Hibaelhárítás

Belső kiszolgálóhiba az alkalmazások portálon való regisztrálásakor

Ha nem tudja listázni az alkalmazásokat, vagy belső kiszolgálóhiba lép fel az alkalmazások portálon való regisztrálásakor, ellenőrizze az alábbiakat:

Kapcsolódó tartalom

  • Last updated on