Autorizace testovací konzoly portálu pro vývojáře konfigurací autorizace uživatele OAuth 2.0

Článek
04/01/2024

Mnoho rozhraní API podporuje OAuth 2.0 pro zabezpečení rozhraní API a zajišťuje, aby k němu měli přístup jenom platné uživatelé a mohli přistupovat pouze k prostředkům, ke kterým mají nárok. Pokud chcete používat interaktivní vývojářskou konzolu služby Azure API Management s těmito rozhraními API, služba umožňuje nakonfigurovat externího zprostředkovatele pro autorizaci uživatelů OAuth 2.0.

Konfigurace autorizace uživatelů OAuth 2.0 v testovací konzole portálu pro vývojáře poskytuje vývojářům pohodlný způsob získání přístupového tokenu OAuth 2.0. Z testovací konzoly se token pak předá back-endu pomocí volání rozhraní API. Ověření tokenu musí být nakonfigurováno samostatně – buď pomocí zásad ověřování JWT, nebo v back-endové službě.

Požadavky

V tomto článku se dozvíte, jak nakonfigurovat instanci služby API Management tak, aby používala autorizaci OAuth 2.0 v testovací konzole portálu pro vývojáře, ale nezobrazuje se, jak nakonfigurovat poskytovatele OAuth 2.0.

Pokud jste ještě nevytvořili instanci služby API Management, přečtěte si téma Vytvoření instance služby API Management.

Přehled scénáře

Konfigurace autorizace uživatelů OAuth 2.0 ve službě API Management povolí testovací konzolu portálu pro vývojáře (a testovací konzolu na webu Azure Portal) jako klient získat token z autorizačního serveru. Konfigurace každého poskytovatele OAuth 2.0 se liší, i když jsou kroky podobné a požadované informace použité ke konfiguraci OAuth 2.0 v instanci služby API Management jsou stejné. Tento článek ukazuje příklad použití Microsoft Entra ID jako poskytovatele OAuth 2.0.

Níže jsou uvedené kroky konfigurace vysoké úrovně:

Zaregistrujte aplikaci (back-endová aplikace) v Microsoft Entra ID, která bude představovat rozhraní API.
Zaregistrujte v Microsoft Entra ID jinou aplikaci (klient-app), která představuje klientskou aplikaci, která potřebuje volat rozhraní API – v tomto případě testovací konzolu portálu pro vývojáře.

V Microsoft Entra ID udělte klientské aplikaci oprávnění umožňující volat back-endovou aplikaci.
Nakonfigurujte testovací konzolu na portálu pro vývojáře tak, aby volala rozhraní API pomocí autorizace uživatele OAuth 2.0.
Nakonfigurujte rozhraní API tak, aby používalo autorizaci uživatele OAuth 2.0.
Přidejte zásadu pro předběžnou autorizaci tokenu OAuth 2.0 pro každý příchozí požadavek. Zásady můžete použít validate-jwt pro libovolného poskytovatele OAuth 2.0.

Tato konfigurace podporuje následující tok OAuth:

Přehledový obrázek pro vizuální koncepční znázornění následujícího toku

Portál pro vývojáře požaduje token z ID Microsoft Entra pomocí přihlašovacích údajů klientské aplikace.
Po úspěšném ověření microsoft Entra ID vydá přístupový nebo obnovovací token.
Vývojář (uživatel portálu pro vývojáře) provádí volání rozhraní API s autorizační hlavičkou.
Token se ověří pomocí validate-jwt zásad ve službě API Management pomocí ID Microsoft Entra.
Na základě výsledku ověření obdrží vývojář odpověď na portálu pro vývojáře.

Typy udělení autorizace

Azure API Management podporuje následující typy udělení OAuth 2.0 (toky). Typ udělení odkazuje na způsob klientské aplikace (v tomto kontextu testovací konzola na portálu pro vývojáře) k získání přístupového tokenu k back-endovému rozhraní API. V závislosti na poskytovateli OAuth 2.0 a scénářích můžete nakonfigurovat jeden nebo více typů udělení.

Následuje souhrn vysoké úrovně. Další informace o typech udělení najdete v autorizačním rozhraní OAuth 2.0 a typech udělení OAuth.

Typ udělení	Popis	Scénáře
Autorizační kód	Výměny autorizačního kódu pro token	Serverové aplikace, jako jsou webové aplikace
Autorizační kód + PKCE	Vylepšení toku autorizačního kódu, který vytváří výzvu kódu odesílanou pomocí žádosti o autorizaci	Mobilní a veřejné klienty, kteří nemůžou chránit tajný klíč nebo token
Implicitní (zastaralé)	Vrátí přístupový token okamžitě bez dalšího kroku výměny autorizačního kódu.	Klienti, kteří nemůžou chránit tajný kód nebo token, jako jsou mobilní aplikace a jednostráňové aplikace Obecně se nedoporučuje kvůli rizikům vrácení přístupového tokenu v přesměrování HTTP bez potvrzení, že ho klient přijal.
Heslo vlastníka prostředku	Vyžaduje přihlašovací údaje uživatele (uživatelské jméno a heslo), obvykle pomocí interaktivního formuláře.	Pro použití s vysoce důvěryhodnými aplikacemi Mělo by se používat jenom v případě, že jiné, bezpečnější toky se nedají použít.
Přihlašovací údaje klienta	Ověřuje a autorizuje aplikaci místo uživatele.	Aplikace typu machine-to-machine, které nevyžadují oprávnění konkrétního uživatele pro přístup k datům, jako jsou rozhraní CLI, démony nebo služby spuštěné na vašem back-endu

Bezpečnostní aspekty

Zvažte, jak typ udělení vygeneruje token, obor tokenu a způsob zveřejnění tokenu. Ohrožený token může zneužít aktér se zlými úmysly pro přístup k dalším prostředkům v rámci oboru tokenu.

Při konfiguraci autorizace uživatelů OAuth 2.0 v testovací konzole portálu pro vývojáře:

Omezte rozsah tokenu na minimum potřebné pro vývojáře k otestování rozhraní API. Omezte rozsah na testovací konzolu nebo na ovlivněná rozhraní API. Postup konfigurace oboru tokenu závisí na vašem poskytovateli OAuth 2.0.

V závislosti na vašich scénářích můžete nakonfigurovat více nebo méně omezující obory tokenů pro jiné klientské aplikace, které vytvoříte pro přístup k back-endovým rozhraním API.
Pokud povolíte tok přihlašovacích údajů klienta, je potřeba věnovat zvláštní pozornost. Testovací konzola na portálu pro vývojáře při práci s tokem přihlašovacích údajů klienta nevyžaduje přihlašovací údaje. Přístupový token může být neúmyslně vystaven vývojářům nebo anonymním uživatelům konzoly pro vývojáře.

Sledování klíčových informací

V tomto kurzu budete požádáni o zaznamenání klíčových informací, na které budete později odkazovat:

ID back-endové aplikace (klienta): IDENTIFIKÁTOR GUID aplikace, která představuje back-endové rozhraní API
Obory back-endové aplikace: Jeden nebo více oborů, které můžete vytvořit pro přístup k rozhraní API. Formát oboru je api://<Backend Application (client) ID>/<Scope Name> (například api://1764e900-1827-4a0b-9182-b2c1841864c2/Read)
ID klientské aplikace (klienta): IDENTIFIKÁTOR GUID aplikace, která představuje portál pro vývojáře
Hodnota tajného klíče klientské aplikace: Identifikátor GUID, který slouží jako tajný klíč pro interakci s klientskou aplikací v MICROSOFT Entra ID

Registrace aplikací na serveru OAuth

U poskytovatele OAuth 2.0 budete muset zaregistrovat dvě aplikace: jedna představuje back-endové rozhraní API, které se má chránit, a druhá představuje klientskou aplikaci, která volá rozhraní API – v tomto případě testovací konzolu portálu pro vývojáře.

Následuje příklad postupu použití Microsoft Entra ID jako poskytovatele OAuth 2.0. Podrobnosti o registraci aplikace najdete v tématu Rychlý start: Konfigurace aplikace pro zveřejnění webového rozhraní API.

Registrace aplikace v Microsoft Entra ID představující rozhraní API

Na webu Azure Portal vyhledejte a vyberte Registrace aplikací.
Vyberte Nová registrace.
Jakmile se zobrazí stránka Registrovat aplikaci, zadejte informace o registraci aplikace:
- V části Název zadejte smysluplný název aplikace, který se zobrazí uživatelům aplikace, například back-endové aplikaci.
- V části Podporované typy účtů vyberte možnost, která vyhovuje vašemu scénáři.
Oddíl identifikátoru URI přesměrování ponechte prázdný. Později přidáte identifikátor URI přesměrování vygenerovaný v konfiguraci OAuth 2.0 ve službě API Management.
Výběrem možnosti Registrovat aplikaci vytvořte.
Na stránce Přehled aplikace najděte hodnotu ID aplikace (klienta) a poznamenejte si ji pro pozdější použití.
V části Správa boční nabídky vyberte Zveřejnit rozhraní API a nastavte identifikátor URI ID aplikace na výchozí hodnotu. Tuto hodnotu si poznamenejte později.
Výběrem tlačítka Přidat obor zobrazte stránku Přidat obor:
1. Zadejte název oboru pro obor podporovaný rozhraním API (například Files.Read).
2. V Kdo může souhlasit?, vyberte svůj scénář, například Správa a uživatele. Vyberte Správa pouze pro scénáře s vyššími oprávněními.
3. Zadejte zobrazovaný název Správa souhlasu a Správa popis souhlasu.
4. Ujistěte se, že je vybraný stav povoleného oboru.
Výběrem tlačítka Přidat obor vytvořte obor.
Opakováním předchozích dvou kroků přidejte všechny obory podporované vaším rozhraním API.
Jakmile se obory vytvoří, poznamenejte si je, abyste je mohli použít v dalším kroku.

Registrace jiné aplikace v Microsoft Entra ID představující klientskou aplikaci

Zaregistrujte každou klientskou aplikaci, která volá rozhraní API jako aplikaci v MICROSOFT Entra ID.

Na webu Azure Portal vyhledejte a vyberte Registrace aplikací.
Vyberte Nová registrace.
Jakmile se zobrazí stránka Registrovat aplikaci, zadejte informace o registraci aplikace:
- V části Název zadejte smysluplný název aplikace, který se zobrazí uživatelům aplikace, například klientské aplikaci.
- V části Podporované typy účtů vyberte možnost, která vyhovuje vašemu scénáři.
V části Identifikátor URI pro přesměrování vyberte Web a pole adresy URL ponechte prozatím prázdné.
Výběrem možnosti Registrovat aplikaci vytvořte.
Na stránce Přehled aplikace najděte hodnotu ID aplikace (klienta) a poznamenejte si ji pro pozdější použití.
Vytvořte tajný klíč klienta pro tuto aplikaci, který se použije v dalším kroku.
1. V části Správa boční nabídky vyberte Certifikáty a tajné kódy.
2. V části Tajné kódy klienta vyberte + Nový tajný klíč klienta.
3. V části Přidat tajný klíč klienta zadejte popis a zvolte, kdy má klíč vypršet.
4. Vyberte Přidat.

Po vytvoření tajného kódu si poznamenejte hodnotu klíče, kterou použijete v dalším kroku. K tajnému kódu nemůžete znovu přistupovat na portálu.

Udělení oprávnění v MICROSOFT Entra ID

Teď, když jste zaregistrovali dvě aplikace, které představují rozhraní API a testovací konzolu, udělte oprávnění, aby klientská aplikace mohla volat back-endovou aplikaci.

Na webu Azure Portal vyhledejte a vyberte Registrace aplikací.
Zvolte klientskou aplikaci. Pak v boční nabídce vyberte oprávnění rozhraní API.
Vyberte + Přidat oprávnění.
V části Vybrat rozhraní API vyberte Moje rozhraní API a pak vyhledejte a vyberte svou back-endovou aplikaci.
Vyberte Delegovaná oprávnění a pak vyberte příslušná oprávnění pro vaši back-endovou aplikaci.
Vyberte Přidat oprávnění.

Nepovinná možnost:

Přejděte na stránku oprávnění rozhraní API klientské aplikace.
Pokud chcete udělit souhlas jménem všech uživatelů v tomto adresáři, vyberte Udělit souhlas správce pro <vaše jméno> tenanta.

Konfigurace autorizačního serveru OAuth 2.0 ve službě API Management

Na webu Azure Portal přejděte k vaší instanci služby API Management.
V části Portál pro vývojáře v boční nabídce vyberte OAuth 2.0 + OpenID Připojení.
Na kartě OAuth 2.0 vyberte + Přidat.
Do polí Název a Popis zadejte název a volitelný popis.

Poznámka:

Tato pole identifikují autorizační server OAuth 2.0 v rámci aktuální služby API Management. Jejich hodnoty nepocházejí ze serveru OAuth 2.0.
Zadejte adresu URL stránky registrace klienta , například https://contoso.com/login. Na této stránce můžou uživatelé vytvářet a spravovat své účty, pokud váš poskytovatel OAuth 2.0 podporuje správu účtů uživatelem. Stránka se liší v závislosti na použitém poskytovateli OAuth 2.0.

Pokud váš poskytovatel OAuth 2.0 nemá nakonfigurovanou správu účtů, zadejte zástupnou adresu URL, například adresu URL vaší společnosti, nebo adresu URL, například http://localhost.
Další část formuláře obsahuje typy udělení autorizace, adresu URL koncového bodu autorizace a nastavení metody žádosti o autorizaci.
- Vyberte jeden nebo více požadovaných typů udělení autorizace. V tomto příkladu vyberte Autorizační kód (výchozí). Další informace
- Zadejte adresu URL koncového bodu autorizace. Adresu URL koncového bodu můžete získat ze stránky Koncové body jedné z registrací vaší aplikace. V případě aplikace s jedním tenantem v Microsoft Entra ID bude tato adresa URL podobná jedné z následujících adres URL, kde {aad-tenant} se nahradí ID vašeho tenanta Microsoft Entra.
  
  Použití koncového bodu v2 se doporučuje. API Management ale podporuje koncové body v1 i v2.
  
  https://login.microsoftonline.com/{aad-tenant}/oauth2/v2.0/authorize (v2)
  
  https://login.microsoftonline.com/{aad-tenant}/oauth2/authorize (v1)
- Metoda žádosti o autorizaci určuje, jak se autorizační požadavek odešle na server OAuth 2.0. Vyberte POST.
Zadejte adresu URL koncového bodu tokenu, metody ověřování klienta, metodu odesílání přístupového tokenu a výchozí obor.
- Zadejte adresu URL koncového bodu tokenu. U jedné aplikace tenanta v Microsoft Entra ID bude vypadat podobně jako jedna z následujících adres URL, kde {aad-tenant} se nahradí ID vašeho tenanta Microsoft Entra. Použijte stejnou verzi koncového bodu (v2 nebo v1), kterou jste zvolili dříve.
  
  https://login.microsoftonline.com/{aad-tenant}/oauth2/v2.0/token (v2)
  
  https://login.microsoftonline.com/{aad-tenant}/oauth2/token (v1)
- Pokud používáte koncové body v1 , přidejte základní parametr:
  * Název: prostředek.
  * Hodnota: ID aplikace back-endové aplikace (klienta).
- Pokud používáte koncové body v2 :
  * Zadejte obor back-endové aplikace, který jste vytvořili v poli Výchozí obor .
  * Nastavte hodnotu accessTokenAcceptedVersion vlastnosti do 2 manifestu aplikace pro back-endovou aplikaci i registraci klientské aplikace.
- Přijměte výchozí nastavení pro metody ověřování klienta a metodu odesílání přístupového tokenu.
V přihlašovacích údajích klienta zadejte ID klienta a tajný klíč klienta, který jste získali při vytváření a konfiguraci aplikace klienta.
Po zadání ID klienta a tajného klíče klienta se vygeneruje identifikátor URI přesměrování pro autorizační kód. Tento identifikátor URI slouží ke konfiguraci identifikátoru URI přesměrování v konfiguraci serveru OAuth 2.0.

Na portálu pro vývojáře je přípona identifikátoru URI formuláře:
- /signin-oauth/code/callback/{authServerName} tok udělení autorizačního kódu
- /signin-oauth/implicit/callback pro implicitní tok udělení
Zkopírujte příslušný identifikátor URI přesměrování na stránku Ověřování registrace klientské aplikace. V registraci aplikace vyberte Ověřování> + Přidat web platformy>a pak zadejte identifikátor URI přesměrování.
Pokud jsou typy udělení autorizace nastavené na heslo vlastníka prostředku, použije se k zadání těchto přihlašovacích údajů oddíl přihlašovací údaje vlastníka prostředku. Jinak ho můžete ponechat prázdné.
Výběrem možnosti Vytvořit uložte konfiguraci autorizačního serveru API Management OAuth 2.0.
Znovu publikujte portál pro vývojáře.

Důležité

Při provádění změn souvisejících s OAuth 2.0 nezapomeňte znovu publikovat portál pro vývojáře po každé úpravě jako relevantní změny (například změny oboru), jinak se nemůže rozšířit na portál a následně je použít při vyzkoušení rozhraní API.

Konfigurace rozhraní API pro použití autorizace uživatelů OAuth 2.0

Po uložení konfigurace serveru OAuth 2.0 nakonfigurujte rozhraní API nebo rozhraní API pro použití této konfigurace.

Důležité

Konfigurace nastavení autorizace uživatelů OAuth 2.0 pro rozhraní API umožňuje službě API Management získat token z autorizačního serveru při použití testovací konzoly na webu Azure Portal nebo na portálu pro vývojáře. Nastavení autorizačního serveru se také přidá do definice rozhraní API a dokumentace.
V případě autorizace OAuth 2.0 za běhu musí klientská aplikace získat a předložit token a musíte nakonfigurovat ověření tokenu ve službě API Management nebo back-endovém rozhraní API. Příklad najdete v tématu Ochrana rozhraní API ve službě Azure API Management pomocí autorizace OAuth 2.0 s ID Microsoft Entra.

V nabídce API Management na levé straně vyberte rozhraní API.
Vyberte název požadovaného rozhraní API a vyberte kartu Nastavení. Přejděte do části Zabezpečení a pak vyberte OAuth 2.0.
V rozevíracím seznamu vyberte požadovaný autorizační server a vyberte Uložit.

Portál pro vývojáře – otestování autorizace uživatelů OAuth 2.0

Jakmile nakonfigurujete autorizační server OAuth 2.0 a nakonfigurujete rozhraní API tak, aby používalo tento server, můžete ho otestovat tak, že přejdete na portál pro vývojáře a zavoláte rozhraní API.

V horní nabídce na stránce Přehled instance služby Azure API Management vyberte Portál pro vývojáře.
Na portálu pro vývojáře přejděte na libovolnou operaci v rozhraní API.
Vyberte Vyzkoušet, abyste se mohli dostat do konzoly pro vývojáře.
Poznamenejte si novou položku v části Autorizace odpovídající autorizačnímu serveru, který jste právě přidali.
V rozevíracím seznamu autorizace vyberte autorizační kód .
Po zobrazení výzvy se přihlaste k tenantovi Microsoft Entra.
- Pokud jste už přihlášení k účtu, možná se nezobrazí výzva.
Po úspěšném přihlášení Authorization se do požadavku přidá hlavička s přístupovým tokenem z ID Microsoft Entra. Následuje zkrácený ukázkový token (kódovaný v Base64):
```
Authorization: Bearer eyJ0eXAiOi[...]3pkCfvEOyA
```
Nakonfigurujte požadované hodnoty pro zbývající parametry a vyberte Odeslat pro volání rozhraní API.

Konfigurace zásad ověřování JWT pro předběžné autorizace požadavků

V konfiguraci zatím služba API Management neověřuje přístupový token. Token v autorizační hlavičce předá pouze back-endovému rozhraní API.

Pokud chcete požadavky předem autorizovat, nakonfigurujte zásadu validate-jwt tak, aby ověřila přístupový token každého příchozího požadavku. Pokud požadavek nemá platný token, služba API Management ho zablokuje.

Následující ukázková zásada při přidání do oddílu <inbound> zásad zkontroluje hodnotu deklarace identity cílové skupiny v přístupovém tokenu získaném z ID Microsoft Entra, které se zobrazí v hlavičce Autorizace. Pokud token není platný, vrátí chybovou zprávu. Nakonfigurujte tuto zásadu v oboru zásad, který je vhodný pro váš scénář.

V adrese openid-config URL aad-tenant je ID tenanta v Microsoft Entra ID. Tuto hodnotu najdete na webu Azure Portal, například na stránce Přehled vašeho prostředku Microsoft Entra. Uvedený příklad předpokládá aplikaci Microsoft Entra s jedním tenantem a koncový bod konfigurace v2.
Hodnota claim je ID klienta back-endové aplikace, kterou jste zaregistrovali v Microsoft Entra ID.

<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>

Poznámka:

Předchozí openid-config adresa URL odpovídá koncovému bodu v2. Pro koncový bod v1 openid-config použijte https://login.microsoftonline.com/{aad-tenant}/.well-known/openid-configuration.

Informace o konfiguraci zásad najdete v tématu Nastavení nebo úprava zásad. Další přizpůsobení ověřování JWT najdete v referenční dokumentaci validate-jwt . K ověření JWT poskytované službou Microsoft Entra poskytuje validate-azure-ad-token služba API Management také zásady.

Další informace o používání OAuth 2.0 a API Management najdete v tématu Ochrana webového back-endu rozhraní API ve službě Azure API Management pomocí autorizace OAuth 2.0 s ID Microsoft Entra.
Další informace o toku autorizačního kódu Microsoft Identity Platform a OAuth 2.0