Použití pojmenovaných hodnot v zásadách služby Azure API Management

PLATÍ PRO: Všechny úrovně služby API Management

Zásady služby API Management představují výkonnou funkci systému, která vydavateli umožňuje změnit chování rozhraní API prostřednictvím konfigurace. Zásady představují kolekci příkazů, které se postupně provádí na základě požadavku nebo odezvy z rozhraní API. Příkazy zásad lze sestavit pomocí textových literálů, výrazů zásad a pojmenovaných hodnot.

Pojmenované hodnoty jsou globální kolekce párů názvů a hodnot v každé instanci služby API Management. Pojmenované hodnoty můžete použít ke správě konstantních řetězcových hodnot a tajných kódů napříč všemi konfiguracemi a zásadami rozhraní API.

Typy hodnot

Typ	Popis
Planina	Literálový řetězec nebo výraz zásad
Tajný	Doslovný řetězec nebo výraz zásad, který je šifrován službou API Management.
Trezor klíčů	Identifikátor tajného klíče uloženého v trezoru klíčů Azure.

Prosté hodnoty nebo tajné kódy můžou obsahovat výrazy zásad. Výraz například @(DateTime.Now.ToString()) vrátí řetězec obsahující aktuální datum a čas.

Podrobnosti o pojmenovaných atributech hodnot najdete v referenčních informacích k rozhraní REST API služby API Management.

Tajné kódy trezoru klíčů

Hodnoty tajných kódů je možné uložit buď jako šifrované řetězce ve službě API Management (vlastní tajné kódy), nebo odkazovat na tajné kódy ve službě Azure Key Vault.

Doporučujeme používat tajné kódy trezoru klíčů, protože pomáhají zlepšit zabezpečení služby API Management:

Poznámka:

V současné době není integrace s trezorem klíčů pro tento scénář dostupná v pracovních prostorech.

• Tajné kódy uložené v trezorech klíčů můžete opakovaně používat napříč službami.
• Podrobné zásady přístupu můžete použít u tajných kódů.
• Tajné kódy aktualizované v trezoru klíčů se ve službě API Management automaticky obměňují. Po aktualizaci v trezoru klíčů se pojmenovaná hodnota ve službě API Management aktualizuje do čtyř hodin. Tajný kód můžete aktualizovat také ručně pomocí webu Azure Portal nebo přes rozhraní REST API pro správu.

Poznámka:

Tajné kódy uložené ve službě Azure Key Vault musí mít délku 1 až 4096 znaků, protože služba API Management nemůže načíst hodnoty, které tento limit překračují.

Požadavky

• Pokud jste ještě nevytvořili instanci služby API Management, přečtěte si článek Rychlý start: Vytvoření nové instance služby Azure API Management pomocí webu Azure Portal.

Požadavky na integraci trezoru klíčů

Poznámka:

V současné době tato funkce není dostupná v pracovních prostorech.

• Pokud ještě trezor klíčů nemáte, vytvořte ho. Postup vytvoření trezoru klíčů najdete v tématu Rychlý start: Vytvoření trezoru klíčů pomocí webu Azure Portal.

  Informace o vytvoření nebo importu tajného kódu do trezoru klíčů najdete v tématu Rychlý start: Nastavení a načtení tajného klíče ze služby Azure Key Vault pomocí webu Azure Portal.

• Povolte spravovanou identitu přiřazenou systémem nebo přiřazenou uživatelem v instanci služby API Management.

Konfigurace přístupu k trezoru klíčů

1. Na portálu přejděte do trezoru klíčů.
2. V nabídce vlevo vyberte Nastavení>konfigurace přístupu. Všimněte si nakonfigurovaného modelu oprávnění .
3. V závislosti na modelu oprávnění nakonfigurujte zásady přístupu trezoru klíčů nebo přístup Azure RBAC pro spravovanou identitu služby API Management.

Chcete-li přidat zásadu přístupu k trezoru klíčů:

1. V nabídce vlevo vyberte Zásady přístupu.
2. Na stránce Zásady přístupu vyberte + Vytvořit.
3. Na kartě Oprávnění v sekci Oprávnění pro tajné vyberte Získat a Vypsat a pak vyberte Další.
4. Na kartě Hlavní vyhledejte název prostředku vaší spravované identity a poté vyberte Další. Pokud používáte identitu přiřazenou systémem, hlavní název je název vaší instance služby API Management.
5. Znovu vyberte Další . Na kartě Revize a vytvoření vyberte Vytvořit.

Konfigurace přístupu Azure RBAC:

1. V nabídce vlevo vyberte Řízení přístupu (IAM).
2. Na stránce Řízení přístupu (IAM) vyberte možnost Přidat přiřazení role.
3. Na kartě Role vyberte Uživatele tajných kódů služby Key Vault a pak vyberte Další.
4. Na kartě Členové vyberte Spravovaná identita>+ Vybrat členy.
5. Na stránce Vybrat spravovanou identitu vyberte spravovanou identitu přiřazenou systémem nebo spravovanou identitu přiřazenou uživatelem přidruženou k vaší instanci služby API Management a pak vyberte Vybrat.
6. Vyberte Zkontrolovat + přiřadit.

Požadavky na bránu firewall služby Key Vault

Pokud je ve vašem klíčovém trezoru povolená brána firewall služby Key Vault, je potřeba splňovat následující požadavky:

• Pro přístup k trezoru klíčů musíte použít spravovanou identitu přiřazenou systémem instance služby API Management.

• V bráně firewall Key Vault povolte možnost Povolit důvěryhodným službám Microsoftu obejít tento firewall.

• Ujistěte se, že vaše IP adresa místního klienta má povolený přístup k trezoru klíčů dočasně, když vyberete certifikát nebo tajný klíč pro přidání do služby Azure API Management. Další informace najdete v tématu Konfigurace nastavení sítě služby Azure Key Vault.

  Po dokončení konfigurace můžete zablokovat adresu klienta v bráně firewall trezoru klíčů.

Požadavky na virtuální síť

Pokud je instance služby API Management nasazená ve virtuální síti, nakonfigurujte také následující nastavení sítě:

• Povolte koncový bod služby Key Vault na podsíti API Management.
• Nakonfigurujte pravidlo skupiny zabezpečení sítě (NSG), které povolí odchozí provoz do značek služeb AzureKeyVault a AzureActiveDirectory.

Podrobnosti najdete v tématu Konfigurace sítě při nastavování služby API Management ve virtuální síti.

Přidání nebo úprava pojmenované hodnoty

Přidání tajemství z trezoru klíčů do služby API Management

Viz Požadavky pro integraci Key Vault.

Důležité

Při přidávání tajného kódu trezoru klíčů do instance služby API Management musíte mít oprávnění k výpisu tajných kódů z trezoru klíčů.

Upozornění

Při použití tajného klíče trezoru klíčů ve službě API Management dávejte pozor, abyste neodstraňovat tajný klíč, trezor klíčů nebo spravovanou identitu použitou pro přístup k trezoru klíčů.

1. Na webu Azure Portal přejděte k vaší instanci služby API Management.

2. V části Rozhraní API vyberte Pojmenované hodnoty>+ Přidat.

3. Zadejte identifikátor názvu a zadejte zobrazovaný název, který se používá pro odkaz na vlastnost v zásadách.

4. Přidejte jednu nebo více volitelných značek , které vám pomůžou uspořádat pojmenované hodnoty.

5. V rozevíracím seznamu Typ vyberte trezor klíčů.

6. Zadejte identifikátor tajného klíče trezoru klíčů (bez verze) nebo zvolte Vybrat a vyberte tajný klíč z trezoru klíčů.

   Důležité

   Pokud sami zadáte identifikátor tajemství trezoru klíčů, ujistěte se, že neobsahuje informace o verzi. Jinak se tajný klíč po aktualizaci v trezoru klíčů automaticky neobměňuje ve službě API Management.

7. V části Klientská identita vyberte spravovanou identitu přiřazenou systémem nebo existující spravovanou identitu přiřazenou uživatelem. Naučte se přidávat nebo upravovat spravované identity ve službě API Management.

   Poznámka:

   Identita potřebuje oprávnění k získání a výpisu tajemství z trezoru klíčů. Pokud jste ještě nenakonfigurovali přístup k trezoru klíčů, služba API Management vás vyzve, aby automaticky nakonfigurovala identitu s potřebnými oprávněními.

8. Vyberte Uložit a pak vyberte Vytvořit.

   

Přidání hodnoty prostého nebo tajného kódu do služby API Management

Portál

1. Na webu Azure Portal přejděte k vaší instanci služby API Management.
2. V části Rozhraní API vyberte Pojmenované hodnoty>+ Přidat.
3. Zadejte identifikátor názvu a zadejte zobrazovaný název, který se používá pro odkaz na vlastnost v zásadách.
4. V rozevíracím seznamu Typ vyberte Prostý nebo Tajný kód.
5. Do pole Hodnota zadejte řetězec nebo výraz zásad.
6. Přidejte jednu nebo více volitelných značek, které vám pomůžou uspořádat pojmenované hodnoty a pak uložit.
7. Vyberte Vytvořit.

Po vytvoření pojmenované hodnoty ji můžete upravit výběrem názvu. Pokud změníte zobrazovaný název, všechny zásady, které odkazují na pojmenovanou hodnotu, se automaticky aktualizují tak, aby používaly nový zobrazovaný název.

Azure CLI

Jak začít používat Azure CLI:

• Použijte prostředí Bash v Azure Cloud Shellu. Další informace najdete v tématu Začínáme s Azure Cloud Shellem.

  

• Pokud dáváte přednost místnímu spouštění referenčních příkazů rozhraní příkazového řádku, nainstalujte Azure CLI. Pokud používáte Windows nebo macOS, zvažte spuštění Azure CLI v kontejneru Docker. Další informace najdete v tématu Jak spustit Azure CLI v kontejneru Dockeru.

  • Pokud používáte místní instalaci, přihlaste se k Azure CLI pomocí příkazu az login. Pokud chcete dokončit proces ověřování, postupujte podle kroků zobrazených na terminálu. Další možnosti přihlášení najdete v tématu Ověřování v Azure pomocí Azure CLI.

  • Po zobrazení výzvy nainstalujte rozšíření Azure CLI při prvním použití. Další informace o rozšířeních najdete v tématu Použití a správa rozšíření pomocí Azure CLI.

  • Spuštěním příkazu az version zjistěte verzi a závislé knihovny, které jsou nainstalované. Pokud chcete upgradovat na nejnovější verzi, spusťte az upgrade.

Pokud chcete přidat pojmenovanou hodnotu, použijte příkaz az apim nv create . Nahraďte hodnoty resource-group a service-name názvem vaší skupiny prostředků a názvem instance služby API Management.

az apim nv create --resource-group apim-hello-word-resource-group \
    --display-name "named_value_01" --named-value-id named_value_01 \
    --secret true --service-name apim-hello-world --value test

Po vytvoření pojmenované hodnoty ji můžete aktualizovat pomocí příkazu az apim nv update . Pokud chcete zobrazit všechny pojmenované hodnoty, spusťte příkaz az apim nv list :

az apim nv list --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --output table

Pokud chcete zobrazit podrobnosti o pojmenované hodnotě, kterou jste vytvořili v tomto příkladu, spusťte příkaz az apim nv show :

az apim nv show --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

Tento příklad je tajná hodnota. Předchozí příkaz nevrací hodnotu. Pokud chcete zobrazit hodnotu, spusťte příkaz az apim nv show-secret :

az apim nv show-secret --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

Pokud chcete odstranit pojmenovanou hodnotu, použijte příkaz az apim nv delete :

az apim nv delete --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

Použijte pojmenovanou hodnotu

Příklady v této části používají pojmenované hodnoty uvedené v následující tabulce.

Jméno	Hodnota	Tajný
ContosoHeader	TrackingId	Nepravda
ContosoHeaderValue	••••••••••••••••••••••	Pravdivé
Výrazová vlastnost	@(DateTime.Now.ToString())	Nepravda
ContosoHeaderValue2	This is a header value.	Nepravda

Pokud chcete v politice použít pojmenovanou hodnotu, umístěte její zobrazovaný název do dvojitých složených závorek {{ContosoHeader}}, jak je znázorněno v následujícím příkladu:

<set-header name="{{ContosoHeader}}" exists-action="override">
  <value>{{ContosoHeaderValue}}</value>
</set-header>

V tomto příkladu ContosoHeader se používá jako název hlavičky v set-header zásadě a ContosoHeaderValue slouží jako hodnota této hlavičky. Když se tato zásada vyhodnotí během požadavku nebo odpovědi na bránu služby API Management, {{ContosoHeader}} a {{ContosoHeaderValue}} se nahradí příslušnými hodnotami.

Pojmenované hodnoty můžete použít jako úplný atribut nebo hodnoty prvků, jak je znázorněno v předchozím příkladu, ale dají se také vložit do nebo zkombinovat s částí textového výrazu literálu, jak je znázorněno v následujícím příkladu:

<set-header name = "CustomHeader{{ContosoHeader}}" ...>

Pojmenované hodnoty mohou také obsahovat výrazy zásad. V následujícím příkladu se ExpressionProperty výraz použije.

<set-header name="CustomHeader" exists-action="override">
    <value>{{ExpressionProperty}}</value>
</set-header>

Když je tato zásada vyhodnocována, {{ExpressionProperty}} je nahrazen svými hodnotami, @(DateTime.Now.ToString()). Vzhledem k tomu, že hodnota je výraz politiky, výraz se vyhodnotí a politika pokračuje ve svém provádění.

Můžete to otestovat v Azure portálu nebo na portálu pro vývojáře voláním operace, která má zásadu s pojmenovanými hodnotami v rozsahu. V následujícím příkladu se volá operace se dvěma předchozími příkladovými set-header zásadami s pojmenovanými hodnotami. Všimněte si, že odpověď obsahuje dvě vlastní hlavičky, které byly nakonfigurovány pomocí zásad s pojmenovanými hodnotami.

Pokud se podíváte na trasování odchozího rozhraní API pro volání, které obsahuje dvě předchozí ukázkové zásady s pojmenovanými hodnotami, uvidíte dvě set-header zásady s vloženými pojmenovanými hodnotami a také vyhodnocení výrazu zásad pro pojmenovanou hodnotu, která obsahovala výraz zásad.

Můžete také použít interpolaci řetězců s pojmenovanými hodnotami.

<set-header name="CustomHeader" exists-action="override">
    <value>@($"The URL encoded value is {System.Net.WebUtility.UrlEncode("{{ContosoHeaderValue2}}")}")</value>
</set-header>

Hodnota pro CustomHeader bude The URL encoded value is This+is+a+header+value..

Upozornění

Pokud zásada odkazuje na tajný klíč ve službě Azure Key Vault, je hodnota z trezoru klíčů viditelná pro uživatele, kteří mají přístup k předplatným povoleným pro trasování požadavků rozhraní API.

Pojmenované hodnoty sice můžou obsahovat výrazy zásad, ale nemůžou obsahovat jiné pojmenované hodnoty. Pokud se pro hodnotu použije text obsahující pojmenovaný odkaz na hodnotu, například Text: {{MyProperty}}, tento odkaz se nevyřeší a nenahradí.

Odstranění pojmenované hodnoty

Pokud chcete odstranit pojmenovanou hodnotu, vyberte název a pak v místní nabídce (...) vyberte Odstranit.

Důležité

Pokud na pojmenovanou hodnotu odkazují nějaké zásady služby API Management, nemůžete ji odstranit, dokud pojmenovanou hodnotu neodeberete ze všech zásad, které ji používají.

Související obsah

Další informace o práci se zásadami:

• Zásady ve službě API Management
• referenční příručce o zásadách
• Výrazy zásad