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 je možné vytvořit pomocí textových hodnot 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. Počet položek v kolekci není nijak omezen. Pojmenované hodnoty se dají 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

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.

Použití tajných kódů trezoru klíčů se doporučuje, protože pomáhá zlepšit zabezpečení služby API Management:

• Tajné kódy uložené v trezorech klíčů je možné opakovaně používat napříč službami.
• Podrobné zásady přístupu se dají použít na tajné kódy.
• 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 4 hodin. Tajný kód můžete aktualizovat také ručně pomocí webu Azure Portal nebo přes rozhraní REST API pro správu.

Požadavky

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

Požadavky na integraci trezoru klíčů

• 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 konfiguraci accessu a poznamenejte si nakonfigurovaný model 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.

   Přidání zásady přístupu 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 části Oprávnění vyberte Získat a Seznam a pak vyberte Další.
   4. Na kartě Objekt zabezpečení vyberte objekt zabezpečení, vyhledejte název prostředku vaší spravované identity a pak vyberte Další. Pokud používáte identitu přiřazenou systémem, objekt zabezpečení 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 Přidat přiřazení role.
   3. Na kartě Role vyberte uživatele certifikátu služby Key Vault.
   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 trezoru klíčů povolená brána firewall služby Key Vault, jsou další 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 služby Key Vault povolte, aby tuto možnost brány firewall vynechala důvěryhodná služba Microsoftu.

• 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 do služby Azure Key Vault v podsíti služby 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 Azure API Management ve virtuální síti.

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

Přidání tajného klíče trezoru klíčů do služby API Management

Viz Požadavky pro integraci 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. V hodnotě typu vyberte Trezor klíčů.

5. 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 zadáte identifikátor tajného klíče trezoru klíčů sami, 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.

6. V části Identita klienta 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 tajných kódů 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.

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

8. Vyberte Vytvořit.

   

Přidání hodnoty prostého nebo tajného kódu do 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

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

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

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

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

Použití pojmenované hodnoty

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

Pokud chcete v zásadě použít pojmenovanou hodnotu, umístěte její zobrazovaný název do dvojité dvojice 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 {{ContosoHeader}} služby API Management a {{ContosoHeaderValue}} nahradí se příslušnými hodnotami.

Pojmenované hodnoty lze 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 nebo kombinovat s částí literálového textového výrazu, 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>

Při vyhodnocování {{ExpressionProperty}} této zásady se nahradí hodnotou @(DateTime.Now.ToString()). Vzhledem k tomu, že hodnota je výraz zásad, výraz se vyhodnotí a zásada pokračuje jeho spuštěním.

Můžete to otestovat na webu Azure Portal nebo na portálu pro vývojáře voláním operace, která má zásadu s pojmenovanými hodnotami v oboru. V následujícím příkladu se volá operace se dvěma předchozími ukázkový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.

Interpolace řetězců se dá použít také 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 bude CustomHeader The URL encoded value is This+is+a+header+value..

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 nepřeloží a nahradí.

Odstranění pojmenované hodnoty

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

Další kroky

• 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