Sdílet prostřednictvím

Zabezpečený přístup k produktům a rozhraním API pomocí aplikací Microsoft Entra

PLATÍ PRO: Vývojář | Základní | Standardní | Premium

Api Management teď podporuje integrovaný přístup založený na aplikacích OAuth 2.0 k rozhraním API produktů pomocí toku přihlašovacích údajů klienta. Tato funkce umožňuje správcům rozhraní API registrovat aplikace Microsoft Entra ID a tím zjednodušit bezpečný přístup k rozhraní API pro vývojáře prostřednictvím autorizace OAuth 2.0.

Poznámka:

Aplikace jsou aktuálně ve verzi Limited Preview. Pokud se chcete zaregistrovat, vyplňte tento formulář.

S touto funkcí:

  • Správci rozhraní API nastavily vlastnost produktu tak, aby povolily přístup na základě aplikací.
  • Správci rozhraní API registrují klientské aplikace v MICROSOFT Entra ID, aby omezili přístup k určitým produktům.
  • Vývojáři mají přístup k přihlašovacím údajům klientské aplikace pomocí portálu pro vývojáře služby API Management.
  • Pomocí toku přihlašovacích údajů klienta OAuth 2.0 získávají vývojáři nebo aplikace tokeny, které můžou zahrnout do požadavků rozhraní API.
  • Tokeny prezentované v požadavcích rozhraní API jsou ověřeny bránou služby API Management za účelem autorizace přístupu k rozhraním API produktu.

Požadavky

  • Instance služby API Management nasazená v úrovni Premium, Standard, Basic nebo Developer . Pokud potřebujete nasadit instanci, přečtěte si téma Vytvoření instance služby API Management.

  • Alespoň jeden produkt ve vaší instanci služby API Management s alespoň jedním přiřazeným rozhraním API.

    • Produkt by měl být ve stavu Publikováno , aby k němu měli přístup vývojáři prostřednictvím portálu pro vývojáře.
    • K testování můžete použít výchozí počáteční produkt a rozhraní API echo , které je do něj přidáno.
    • Pokud chcete vytvořit produkt, přečtěte si téma Vytvoření a publikování produktu.

  • Dostatečná oprávnění ve vašem tenantovi Microsoft Entra pro přiřazení role Správce aplikace , která vyžaduje alespoň roli Správce privilegovaných rolí .

  • Volitelně můžete do instance služby API Management přidat jednoho nebo více uživatelů .

Konfigurace spravované identity

  1. Povolte spravovanou identitu přiřazenou systémem pro službu API Management ve vaší instanci služby API Management.

  2. Přiřaďte identitě roli RBAC Application Administrator v Microsoft Entra ID. Přiřazení role:

    1. Přihlaste se k portálu a přejděte na MICROSOFT Entra ID.
    2. V nabídce vlevo vyberte Spravovat>Role a Správci.
    3. Vyberte Správce aplikace.
    4. V nabídce vlevo vyberte Spravovat>přiřazení>+ Přidat zadání.
    5. Na stránce Přidat přiřazení vyhledejte spravovanou identitu instance služby API Management podle názvu (název instance služby API Management). Vyberte spravovanou identitu a pak vyberte Přidat.

Povolení přístupu k produktu na základě aplikace

Pokud chcete povolit přístup na základě aplikací pro produkt, postupujte podle těchto kroků. Produkt musí mít toto nastavení povolené, aby bylo možné ho přidružit k klientské aplikaci v pozdějších krocích.

Následující příklad používá počáteční produkt, ale zvolte libovolný publikovaný produkt, který má přiřazené alespoň jedno rozhraní API.

  1. Přihlaste se k portálu na následující vlastní adrese URL funkce aplikací: https://portal.azure.com/?feature.customPortal=false& Microsoft_Azure_ApiManagement=aplikace
  2. Přejděte do vaší instance služby API Management.
  3. V nabídce vlevo v části Rozhraní API vyberte Produkty.
  4. Zvolte produkt, který chcete nakonfigurovat, například počáteční produkt .
  5. V nabídce vlevo v části Produkt vyberte Vlastnosti.
  6. V části Přístup na základě aplikace povolte nastavení tokenu OAuth 2.0 (nejbezpečnější).
  7. Volitelně můžete povolit nastavení klíče předplatného . Pokud povolíte přístup na základě aplikace i požadavek na předplatné, brána API Management může pro přístup k rozhraním API produktu přijmout token OAuth 2.0 nebo klíč předplatného.
  8. Vyberte Uložit.

Snímek obrazovky s povolením přístupu na základě aplikace na portálu

Návod

Při vytváření nového produktu můžete také povolit nastavení tokenu OAuth 2.0 .

Povolení přístupu na základě aplikace vytvoří back-endovou podnikovou aplikaci v Microsoft Entra ID představující produkt. ID back-endové aplikace se zobrazí na stránce Vlastnosti produktu.

Snímek obrazovky s nastavením aplikace produktu na portálu

Poznámka:

Toto ID aplikace je nastaveno jako hodnota Cílové skupiny při vytváření klientské aplikace pro přístup k produktu. Tuto hodnotu také použijte při generování tokenu pro volání rozhraní API produktu.

(Volitelné) Kontrola nastavení aplikace produktu v Microsoft Entra ID

Volitelně zkontrolujte nastavení back-endové podnikové aplikace vytvořené v Microsoft Entra ID představující produkt.

Aplikace má následující formát: název produktu< APIMProductApplication>. Pokud je například název produktu Starter, název aplikace je APIMProductApplicationStarter. Aplikace má definovanou roli aplikace .

Kontrola nastavení aplikace v registracích aplikací:

  1. Přihlaste se k portálu a přejděte do Microsoft Entra ID>, Správa>registrací aplikací.
  2. Vyberte Všechny aplikace.
  3. Vyhledejte a vyberte aplikaci vytvořenou službou API Management.
  4. V nabídce vlevo v části Spravovat vyberte Role aplikace.
  5. Potvrďte roli aplikace nastavenou službou Azure API Management, jak je znázorněno na následujícím snímku obrazovky:

Snímek obrazovky s rolemi aplikace na portálu

Registrace klientské aplikace pro přístup k produktu

Teď zaregistrujte klientskou aplikaci, která omezuje přístup k jednomu nebo více produktům.

  • Produkt musí mít aplikace pro řízení přístupu povoleny, aby mohl být přidružený ke klientské aplikaci.
  • Každá klientská aplikace má v instanci služby API Management jednoho uživatele (vlastníka). K rozhraním API produktů má přístup pouze vlastník prostřednictvím aplikace.
  • Produkt může být přidružený k více než jedné klientské aplikaci.

Registrace klientské aplikace:

  1. Přihlaste se k portálu na následující vlastní adrese URL funkce aplikací: https://portal.azure.com/?feature.customPortal=false& Microsoft_Azure_ApiManagement=aplikace

  2. Přejděte do vaší instance služby API Management.

  3. V nabídce vlevo v části Rozhraní API vyberte Aplikace>+ Zaregistrovat aplikaci.

  4. Na stránce Zaregistrovat aplikaci zadejte následující nastavení aplikace:

    • Název: Zadejte název aplikace.
    • Vlastník: V rozevíracím seznamu uživatelů v instanci služby API Management vyberte vlastníka aplikace.
    • Udělení přístupu k vybraným produktům: Vyberte jeden nebo více produktů v instanci služby API Management, které byly dříve povoleny pro přístup na základě aplikací.
    • Popis: Volitelně zadejte popis.

    Snímek obrazovky s nastavením aplikace na portálu

  5. Vyberte Zaregistrovat.

Aplikace se přidá do seznamu aplikací na stránce Aplikace . Výběrem aplikace zobrazíte podrobnosti, jako je ID klienta. Toto ID potřebujete k vygenerování tokenu pro volání rozhraní API produktu.

Návod

  • Po vytvoření aplikace ji volitelně přidružte k jiným produktům. Na stránce Aplikace vyberte aplikaci a pak vyberte Podrobnosti>produkty>+ Přidat produkt.
  • Aplikaci můžete také vytvořit nebo přidružit úpravou produktu ze stránky Produkty .

Generování tajného klíče klienta

Aby klientská aplikace používala tok přihlašovacích údajů klienta OAuth 2.0, musí se vygenerovat tajný klíč klienta. Tajný kód je platný po dobu jednoho roku, ale dá se kdykoli znovu vygenerovat.

  1. Na stránce Aplikace vyberte aplikaci, kterou jste vytvořili.

  2. Na stránce Přehled aplikace vedle tajného klíče klienta vyberte Přidat tajný klíč.

  3. Na stránce Nový tajný kód klienta vyberte Generovat.

    Tajný klíč klienta se vygeneruje a zobrazí v poli Tajný kód klienta . Nezapomeňte zkopírovat hodnotu tajného kódu a bezpečně ji uložit. Po zavření stránky ho nebudete moct znovu načíst.

  4. Vyberte Zavřít.

(Volitelné) Kontrola nastavení klientské aplikace v Microsoft Entra ID

Volitelně zkontrolujte nastavení klientské aplikace v Microsoft Entra ID.

Aplikace má následující formát: název produktu< APIMApplication>. Pokud je například název produktu Starter, název aplikace se podobá APIMApplicationStarter.

Kontrola nastavení aplikace v registracích aplikací:

  1. Přihlaste se k portálu a přejděte do Microsoft Entra ID>, Správa>registrací aplikací.

  2. Vyberte Všechny aplikace.

  3. Vyhledejte a vyberte klientskou aplikaci vytvořenou službou API Management.

  4. V nabídce vlevo v části Spravovat vyberte oprávnění rozhraní API.

  5. Ověřte, že má aplikace oprávnění pro přístup k back-endové aplikaci nebo aplikacím produktu.

    Pokud například klientská aplikace uděluje přístup k produktu Starter , má aplikace oprávnění Product.Starter.All pro přístup k aplikaci APIMProductApplicationStarter .

    Snímek obrazovky s oprávněními rozhraní API na portálu

Získání nastavení aplikace na portálu pro vývojáře

Uživatelé se můžou přihlásit k portálu pro vývojáře a zobrazit si klientské aplikace, které vlastní.

  1. Přihlaste se k portálu pro vývojáře (https://<your-apim-instance-name>.developer.azure-api.net) pomocí uživatelského účtu, který byl nastavený jako vlastník klientské aplikace.

  2. V horní navigační nabídce vyberte Aplikace.

  3. Aplikace, které uživatel vlastní, se zobrazí v seznamu.

  4. Výběrem aplikace zobrazíte podrobnosti, například ID klienta, tajný klíč klienta a obor. Tyto hodnoty jsou potřeba k vygenerování tokenu pro volání rozhraní API produktu.

    Snímek obrazovky s klientskými aplikacemi na portálu pro vývojáře

Vytvoření tokenu a použití s voláním rozhraní API

Po povolení přístupu na základě aplikace pro produkt a registraci klientské aplikace může vývojář nebo aplikace vygenerovat token pro volání rozhraní API produktu. Token musí být součástí Authorization hlavičky požadavku.

Vývojář nebo aplikace může například spustit následující skripty Azure PowerShellu pro volání klientské aplikace pro vygenerování tokenu a pak tento token použít k volání rozhraní API produktu ve službě API Management.

Upozornění

Následující skripty jsou příklady pouze pro účely testování. V produkčním prostředí použijte zabezpečenou metodu k uložení a načtení tajného klíče klienta.

Vyvolat klientskou aplikaci pro generování tokenu

# 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

Volání rozhraní API produktu pomocí tokenu

Token vygenerovaný v předchozím kroku slouží k volání rozhraní API produktu. Token se předá v autorizační hlavičce požadavku. Instance API Management ověří token a autorizuje přístup k API.

Následující skript ukazuje ukázkové volání rozhraní API echo.

# 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

Řešení problémů

Vnitřní chyba serveru při registraci aplikací na portálu

Pokud se vám nedaří vypsat aplikace nebo při registraci aplikací na portálu dojde k vnitřní chybě serveru, zkontrolujte následující:

Související obsah

  • Last updated on