Autorizace přístupu k rozhraním API v Centru rozhraní API

Nakonfigurujte nastavení pro autorizaci přístupu k rozhraním API v centru rozhraní API. Tato nastavení:

• Povolení ověřování a autorizace rozhraní API pomocí klíčů rozhraní API, autorizace OAuth 2.0 nebo jiného schématu zabezpečení HTTP
• Přidružení konfigurací ověřování k verzím rozhraní API v inventáři
• Správa přístupu k verzím rozhraní API určeným uživatelům nebo skupinám prostřednictvím zásad přístupu
• Povolení autorizovaných uživatelů k testování rozhraní API na portálu API Center

Poznámka:

Tato funkce je aktuálně dostupná jako ukázková verze.

Požadavky

• Centrum rozhraní API ve vašem předplatném Azure. Pokud jste ho ještě nevytvořili, přečtěte si článek Rychlý start: Vytvoření centra rozhraní API.

• Alespoň jedno rozhraní API zaregistrované ve vašem centru rozhraní API. Viz kurz: Registrace rozhraní API v inventáři rozhraní API.

• Prostředí a nasazení nakonfigurované pro rozhraní API Viz kurz: Přidání prostředí a nasazení pro rozhraní API.

• Nastavil se portál API Center. Viz Nastavení portálu API Center.

• Trezor klíčů Azure pro ukládání klíčů rozhraní API nebo tajných kódů klienta OAuth 2.0. Viz Vytvoření služby Key Vault. Trezor klíčů musí používat model oprávnění řízení přístupu na základě role (RBAC) Azure.

• (Pro OAuth 2.0 s Microsoft Entra ID) Oprávnění k vytvoření registrace aplikace v tenantovi Microsoft Entra přidruženém k vašemu předplatnému

Možnost 1: Konfigurace ověřování pomocí klíče rozhraní API

Pro rozhraní API, které podporuje ověřování pomocí klíče rozhraní API, proveďte následující kroky.

1. Uložení klíče rozhraní API ve službě Azure Key Vault

Pokud chcete klíč rozhraní API uložit jako tajný klíč do trezoru klíčů, přečtěte si téma Nastavení a načtení tajného klíče ve službě Key Vault.

Získejte přístup k trezoru klíčů pomocí spravované identity centra api.

Povolte spravovanou identitu ve vašem centru API

V tomto scénáři centrum rozhraní API používá spravovanou identitu pro přístup k prostředkům Azure. V závislosti na vašich potřebách povolte spravované identity přiřazené systémem nebo jednu nebo více spravovaných identit přiřazených uživatelem.

Následující příklady ukazují, jak povolit spravovanou identitu přiřazenou systémem pomocí webu Azure Portal nebo Azure CLI. Na vysoké úrovni jsou kroky konfigurace podobné spravované identitě přiřazené uživatelem.

Portal

1. Na portálu přejděte do centra rozhraní API.
2. V nabídce bočního panelu v části Zabezpečení vyberte Spravované identity.
3. Vyberte Přiřazený systém a nastavte stav na Zapnuto.
4. Vyberte Uložit.

Azure CLI

Pomocí následujícího příkazu az apic update nastavte identitu přiřazenou systémem v centru rozhraní API. Nahraďte názvy svého centra rozhraní API a skupiny prostředků.

az apic update --name <api-center-name> --resource-group <resource-group-name> --identity '{"type": "SystemAssigned"}'

Přiřazení spravované identity roli uživatele tajných kódů služby Key Vault

Pokud chcete povolit import prostředků, přiřaďte spravované identitě centra rozhraní API roli Uživatele tajných kódů služby Key Vault ve službě Azure Key Vault. Můžete použít portál nebo Azure CLI.

Portal

1. Na portálu přejděte do trezoru klíčů.
2. V nabídce bočního panelu vyberte Řízení přístupu (IAM).
3. Vyberte + Přidat přiřazení role.
4. Na stránce Přidat přiřazení role nastavte hodnoty následujícím způsobem:
   1. Na kartě Role vyberte Uživatel tajných kódů v Key Vault.
   2. Na kartě Členové v části Přiřadit přístup ke – Vyberte spravovanou identitu> + Vyberte členy.
   3. Na stránce Vybrat spravované identity vyberte spravovanou identitu přiřazenou systémem centra rozhraní API, kterou jste přidali v předchozí části. Klepněte na tlačítko Vybrat.
   4. Vyberte Review + assign.

Azure CLI

1. Získejte hlavní ID identity. Pro identitu přiřazenou systémem použijte příkaz az apic show .

   #! /bin/bash
   apicObjID=$(az apic show --name <api-center-name> \
       --resource-group <resource-group-name> \
       --query "identity.principalId" --output tsv)
   

   # Formatted for PowerShell
   $apicObjID=$(az apic show --name <api-center-name> `
       --resource-group <resource-group-name> `
       --query "identity.principalId" --output tsv)
   

2. Pomocí příkazu az keyvault show získejte ID prostředku vašeho trezoru klíčů.

   #! /bin/bash
   kvID=$(az keyvault show --name <kv-name> --resource-group <resource-group-name> --query "id" --output tsv)
   

   # Formatted for PowerShell
   $kvID=$(az keyvault show --name <kv-name> --resource-group <resource-group-name> --query "id" --output tsv)
   

3. Přiřaďte spravovanou identitu roli uživatele tajných kódů služby Key Vault v trezoru klíčů příkaz az role assignment create .

   #! /bin/bash
   scope="${kvID:1}"
   
   az role assignment create \
       --role "Key Vault Secrets User" \
       --assignee-object-id $apicObjID \
       --assignee-principal-type ServicePrincipal \
       --scope $scope 
   

   # Formatted for PowerShell
   $scope=$apimID.substring(1)
   
   az role assignment create `
       --role "Key Vault Secrets User" `
       --assignee-object-id $apicObjID `
       --assignee-principal-type ServicePrincipal `
       --scope $scope 
   

2. Přidání konfigurace klíče rozhraní API

1. Na portálu přejděte do centra rozhraní API.

2. V části Zásady správného řízení vyberte Authorization (Preview)>+ Přidat konfiguraci.

3. Na stránce Přidat konfiguraci nastavte následující hodnoty:

   Nastavení	Popis
   Titul	Zadejte název autorizace.
   Popis	Volitelně můžete zadat popis autorizace.
   Schéma zabezpečení	Vyberte klíč rozhraní API.
   Umístění klíče rozhraní API	Vyberte způsob, jakým se klíč prezentuje v požadavcích rozhraní API. Dostupné hodnoty jsou hlavička (hlavička požadavku) a dotaz (parametr dotazu).
   Název parametru klíče rozhraní API	Zadejte název hlavičky HTTP nebo parametru dotazu, který obsahuje klíč rozhraní API. Příklad: x-api-key
   Reference k tajným klíčům rozhraní API v Key Vault	Vyberte předplatné , trezor klíčů a tajný klíč, které jste uložili. Příklad: https://<key-vault-name>.vault.azure.net/secrets/<secret-name>

4. Vyberte Vytvořit.

Po dokončení této konfigurace přejděte do části Přidat konfiguraci ověřování do části Verze rozhraní API a přidružte konfiguraci klíče rozhraní API k verzi rozhraní API.

Možnost 2: Konfigurace autorizace OAuth 2.0

Pro rozhraní API, které podporuje autorizaci OAuth 2.0, proveďte následující kroky. Můžete nakonfigurovat jeden nebo oba následující toky:

• Tok autorizačního kódu s PKCE (Proof Key for Code Exchange) – Autentizace uživatelů v prohlížeči, například na portálu API Center.
• Autentizace klientských přihlašovacích údajů – pro aplikace, které nevyžadují uživatelská oprávnění.

1. Vytvoření aplikace OAuth 2.0

Vytvořte registraci aplikace ve zprostředkovateli identity, jako je tenant Microsoft Entra přidružený k vašemu předplatnému. Postup závisí na vašem poskytovateli identity.

Následující příklad ukazuje, jak vytvořit registraci aplikace v Microsoft Entra ID.

1. Přihlaste se do Azure portálu s dostatečnými oprávněními v tenantu.
2. Přejděte na Microsoft Entra ID>+ Nová registrace.
3. Na stránce Registrace aplikace :
   1. Do pole Název zadejte smysluplný název.
   2. V části Podporované typy účtů vyberte příslušnou možnost, například Účty v tomto organizačním adresáři (jenom jeden tenant).
   3. Pro tok autorizačního kódu v Přesměrovací URI vyberte jednostránková aplikace (SPA) a zadejte URI vašeho portálu API Center: https://<service-name>.portal.<location>.azure-api-center.ms. Nahraďte <service-name> a <location> názvem vašeho centra rozhraní API a umístěním nasazení. Příklad: https://myapicenter.portal.eastus.azure-api-center.ms
   4. Vyberte Zaregistrovat.
4. V části Spravovat vyberte Certifikáty a tajné kódy>+ Nový tajný klíč klienta.
   1. Zadejte popis.
   2. Vyberte možnost Vypršení platnosti.
   3. Vyberte Přidat.
   4. Před opuštěním stránky zkopírujte hodnotu tajného klíče klienta. Budete ho potřebovat v další části.
5. Volitelně můžete do registrace aplikace přidat obory rozhraní API. Viz Konfigurace aplikace pro zveřejnění webového rozhraní API.

Při konfiguraci OAuth 2.0 v centru rozhraní API potřebujete následující hodnoty z registrace aplikace:

• ID aplikace (klienta) ze stránky Přehled a tajný klíč klienta , který jste zkopírovali.
• Následující adresy URL koncových bodů z přehledu<:c0>Endpoints:
  • Koncový bod autorizace OAuth2.0 (v2)
  • Koncový bod tokenu OAuth 2.0 (v2) ( používaný také jako koncový bod aktualizace tokenu)
• Všechny obory rozhraní API, které jste nakonfigurovali.

2. Uložení tajného klíče klienta ve službě Azure Key Vault

Pokud chcete uložit tajný klíč klienta do trezoru klíčů, přečtěte si téma Nastavení a načtení tajného klíče ve službě Key Vault.

Získejte přístup k trezoru klíčů pomocí spravované identity centra api.

Povolte spravovanou identitu ve vašem centru API

V tomto scénáři centrum rozhraní API používá spravovanou identitu pro přístup k prostředkům Azure. V závislosti na vašich potřebách povolte spravované identity přiřazené systémem nebo jednu nebo více spravovaných identit přiřazených uživatelem.

Následující příklady ukazují, jak povolit spravovanou identitu přiřazenou systémem pomocí webu Azure Portal nebo Azure CLI. Na vysoké úrovni jsou kroky konfigurace podobné spravované identitě přiřazené uživatelem.

Portal

1. Na portálu přejděte do centra rozhraní API.
2. V nabídce bočního panelu v části Zabezpečení vyberte Spravované identity.
3. Vyberte Přiřazený systém a nastavte stav na Zapnuto.
4. Vyberte Uložit.

Azure CLI

Pomocí následujícího příkazu az apic update nastavte identitu přiřazenou systémem v centru rozhraní API. Nahraďte názvy svého centra rozhraní API a skupiny prostředků.

az apic update --name <api-center-name> --resource-group <resource-group-name> --identity '{"type": "SystemAssigned"}'

Přiřazení spravované identity roli uživatele tajných kódů služby Key Vault

Pokud chcete povolit import prostředků, přiřaďte spravované identitě centra rozhraní API roli Uživatele tajných kódů služby Key Vault ve službě Azure Key Vault. Můžete použít portál nebo Azure CLI.

Portal

1. Na portálu přejděte do trezoru klíčů.
2. V nabídce bočního panelu vyberte Řízení přístupu (IAM).
3. Vyberte + Přidat přiřazení role.
4. Na stránce Přidat přiřazení role nastavte hodnoty následujícím způsobem:
   1. Na kartě Role vyberte Uživatel tajných kódů v Key Vault.
   2. Na kartě Členové v části Přiřadit přístup ke – Vyberte spravovanou identitu> + Vyberte členy.
   3. Na stránce Vybrat spravované identity vyberte spravovanou identitu přiřazenou systémem centra rozhraní API, kterou jste přidali v předchozí části. Klepněte na tlačítko Vybrat.
   4. Vyberte Review + assign.

Azure CLI

1. Získejte hlavní ID identity. Pro identitu přiřazenou systémem použijte příkaz az apic show .

   #! /bin/bash
   apicObjID=$(az apic show --name <api-center-name> \
       --resource-group <resource-group-name> \
       --query "identity.principalId" --output tsv)
   

   # Formatted for PowerShell
   $apicObjID=$(az apic show --name <api-center-name> `
       --resource-group <resource-group-name> `
       --query "identity.principalId" --output tsv)
   

2. Pomocí příkazu az keyvault show získejte ID prostředku vašeho trezoru klíčů.

   #! /bin/bash
   kvID=$(az keyvault show --name <kv-name> --resource-group <resource-group-name> --query "id" --output tsv)
   

   # Formatted for PowerShell
   $kvID=$(az keyvault show --name <kv-name> --resource-group <resource-group-name> --query "id" --output tsv)
   

3. Přiřaďte spravovanou identitu roli uživatele tajných kódů služby Key Vault v trezoru klíčů příkaz az role assignment create .

   #! /bin/bash
   scope="${kvID:1}"
   
   az role assignment create \
       --role "Key Vault Secrets User" \
       --assignee-object-id $apicObjID \
       --assignee-principal-type ServicePrincipal \
       --scope $scope 
   

   # Formatted for PowerShell
   $scope=$apimID.substring(1)
   
   az role assignment create `
       --role "Key Vault Secrets User" `
       --assignee-object-id $apicObjID `
       --assignee-principal-type ServicePrincipal `
       --scope $scope 
   

3. Přidání konfigurace OAuth 2.0

1. Na portálu přejděte do centra rozhraní API.

2. V části Zásady správného řízení vyberte Authorization (Preview)>+ Přidat konfiguraci.

3. Na stránce Přidat konfiguraci nastavte následující hodnoty:

   

   Poznámka:

   Použijte hodnoty z registrace aplikace, kterou jste vytvořili dříve. V případě ID Microsoft Entra vyhledejte ID klienta na stránce Přehled registrace aplikace a URL koncové body na stránkách Přehled>Koncové body.

   Nastavení	Popis
   Titul	Zadejte název autorizace.
   Popis	Volitelně můžete zadat popis autorizace.
   Schéma zabezpečení	Vyberte OAuth2.
   ID klienta	Zadejte ID klienta (GUID) aplikace, kterou jste vytvořili ve zprostředkovateli identity.
   Tajný klíč klienta	Vyberte předplatné, trezor klíčů a tajný klíč klienta, který jste uložili. Příklad: https://<key-vault-name>.vault.azure.net/secrets/<secret-name>
   Adresa URL autorizace	Zadejte koncový bod autorizace OAuth 2.0 pro zprostředkovatele identity. Příklad pro Microsoft Entra ID: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize
   Adresa URL tokenu	Zadejte koncový bod tokenu OAuth 2.0 pro zprostředkovatele identity. Příklad pro Microsoft Entra ID: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
   Aktualizovat adresu URL	Zadejte koncový bod aktualizace tokenu OAuth 2.0 pro zprostředkovatele identity. U většiny poskytovatelů je stejná jako adresa URL tokenu. Příklad pro Microsoft Entra ID: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
   Tok OAuth2	Vyberte jeden nebo oba toky OAuth 2.0: Autorizační kód (PKCE) a přihlašovací údaje klienta.
   Oblasti	Zadejte jeden nebo více oborů rozhraní API nakonfigurovaných pro vaše rozhraní API oddělené mezerami. Pokud nejsou nakonfigurovány žádné obory, zadejte .default.

4. Výběrem možnosti Vytvořit uložte konfiguraci.

Po dokončení této konfigurace přejděte do části Přidat konfiguraci ověřování do části Verze rozhraní API a přidružte konfiguraci OAuth 2.0 k verzi rozhraní API.

Možnost 3: Konfigurace nastavení pro jiné schéma zabezpečení HTTP

Pro rozhraní API, která používají jiné schéma zabezpečení HTTP, například základní ověřování nebo nosné tokeny, které nepoužívají OAuth 2.0, proveďte následující kroky. Tuto možnost možná budete muset zvolit pro starší rozhraní API.

Na portálu přejděte do centra rozhraní API.

1. V části Zásady správného řízení vyberte Authorization (Preview)>+ Přidat konfiguraci.

2. Na stránce Přidat konfiguraci nastavte následující hodnoty:

   Nastavení	Popis
   Titul	Zadejte název autorizace.
   Popis	Volitelně můžete zadat popis autorizace.
   Schéma zabezpečení	Vyberte HTTP.
   Schéma ověřování	Vyberte schéma ověřování používané rozhraním API. Příklady zahrnují schémata v následující tabulce.

   Schéma ověřování	Description
   Basic	Odešle username:password jako řetězec kódovaný v base64 v hlavičce Authorization: Basic <credentials>.
   Nosič	Odešle jiný token než přístupový token OAuth 2.0 v Authorization: Bearer <token> hlavičce.
   Přehled	Mechanismus výzva-odpověď, kde server odesílá nonce; klient odpoví hash přihlašovacích údajů a nonce.
   Custom	Jiné schéma mechanismu, jako je schéma specifické pro dodavatele.

Po dokončení této konfigurace přejděte k další části a přidružte konfiguraci k verzi rozhraní API.

Přidání konfigurace ověřování do verze rozhraní API

Po konfiguraci schématu ověřování přidružte konfiguraci k verzi rozhraní API.

1. Na portálu přejděte do centra rozhraní API.

2. V části Inventory (Inventář) vyberte Assets (Prostředky).

3. Vyberte rozhraní API, ke kterým chcete konfiguraci přidružit.

4. V části Podrobnosti vyberte Verze a pak vyberte cílovou verzi rozhraní API.

5. V místní nabídce pro verzi rozhraní API vyberte Spravovat přístup (Preview).

6. Na stránce Spravovat přístup vyberte + Přidat ověřování.

7. Vyberte dostupnou konfiguraci ověřování.

8. Vyberte Vytvořit.

Poznámka:

Do verze rozhraní API můžete přidat více konfigurací ověřování (například klíč rozhraní API i OAuth 2.0), pokud je rozhraní API podporované. Stejnou konfiguraci můžete přidat také do více verzí rozhraní API.

Správa přístupu pro konkrétní uživatele nebo skupiny

Nakonfigurujte zásadu přístupu, která přiřazuje uživatelům nebo skupinám roli Čtenář přihlašovacích údajů služby API Center s oborem na konkrétní konfigurace ověřování ve verzi rozhraní API. Tato role umožňuje pouze určeným uživatelům testovat rozhraní API na portálu API Center.

1. Na portálu přejděte do centra rozhraní API.

2. Přejděte na verzi rozhraní API s konfigurací ověřování.

3. Vyberte Spravovat přístup (Preview).

4. Vyberte konfiguraci ověřování, kterou chcete spravovat.

5. V rozevírací nabídce vyberte Upravit zásady přístupu.

6. Na stránce Spravovat přístup vyberte + Přidat > uživatele nebo + Přidat > skupiny.

7. Vyhledejte a vyberte uživatele nebo skupiny. Můžete vybrat více položek.

8. Vyberte Vybrat.

Návod

Chcete-li odebrat uživatele nebo skupiny, vyberte Smazat v místní nabídce na stránce Spravovat přístup.

Testování rozhraní API na portálu API Center

Otestujte rozhraní API, které jste nakonfigurovali pro ověřování a přístup uživatelů.

Návod

Můžete také nakonfigurovat nastavení viditelnosti pro řízení, která rozhraní API se zobrazí pro všechny přihlášené uživatele na portálu.

1. Na portálu přejděte do centra rozhraní API.

2. V části Portál centra rozhraní API vyberte Nastavení >Zobrazit portál Centra rozhraní API.

3. Vyberte rozhraní API a pak vyberte verzi s nakonfigurovanou metodou ověřování.

4. V části Možnosti vyberte Zobrazit dokumentaci.

5. Vyberte operaci a pak vyberte Vyzkoušet toto rozhraní API.

6. Zkontrolujte nastavení ověřování. Pokud máte přístup, vyberte Odeslat.

7. Úspěšná operace vrátí 200 OK kód odpovědi a text odpovědi. Neúspěšná operace vrátí chybovou zprávu.

Související obsah

• Nastavení portálu API Center
• Povolení zobrazení portálu Azure API Center v editoru Visual Studio Code
• Ověřování a autorizace pro přístup k rozhraním API v Azure API Management