Använda namngivna värden i Azure API Management-principer

GÄLLER FÖR: Alla API Management-nivåer

API Management-principer är en kraftfull funktion i systemet som gör det möjligt för utgivaren att ändra beteendet för API:et via konfiguration. Principer är en samling instruktioner som körs sekventiellt på begäran av eller efter ett svar från ett API. Principinstruktioner kan konstrueras med hjälp av literala textvärden, principuttryck och namngivna värden.

Namngivna värden är en global samling namn/värde-par i varje API Management-instans. Det finns ingen gräns för antalet objekt i samlingen. Namngivna värden kan användas för att hantera konstanta strängvärden och hemligheter i alla API-konfigurationer och principer.

Värdetyper

Typ	Beskrivning
Slätt	Literalsträng eller principuttryck
Hemlig	Literalsträng eller principuttryck som krypteras av API Management
Nyckelvalv	Identifierare för en hemlighet som lagras i ett Azure-nyckelvalv.

Oformaterade värden eller hemligheter kan innehålla principuttryck. Uttrycket @(DateTime.Now.ToString()) returnerar till exempel en sträng som innehåller aktuellt datum och tid.

Mer information om de namngivna värdeattributen finns i API Management REST API-referensen.

Nyckelvalvshemligheter

Hemliga värden kan lagras antingen som krypterade strängar i API Management (anpassade hemligheter) eller genom att referera till hemligheter i Azure Key Vault.

Du rekommenderas att använda key vault-hemligheter eftersom det hjälper till att förbättra API Management-säkerheten:

• Hemligheter som lagras i nyckelvalv kan återanvändas mellan tjänster
• Detaljerade åtkomstprinciper kan tillämpas på hemligheter
• Hemligheter som uppdateras i nyckelvalvet roteras automatiskt i API Management. Efter uppdateringen i nyckelvalvet uppdateras ett namngivet värde i API Management inom 4 timmar. Du kan också uppdatera hemligheten manuellt med hjälp av Azure Portal eller via rest-API:et för hantering.

Kommentar

Hemligheterna som lagras i Azure Key Vault måste vara mellan 1 och 4 096 tecken eftersom API Management inte kan hämta värden som överskrider den här gränsen.

Förutsättningar

• Om du inte har skapat en API Management-tjänstinstans ännu kan du läsa Skapa en API Management-tjänstinstans.

Förutsättningar för key vault-integrering

Kommentar

För närvarande är den här funktionen inte tillgänglig på arbetsytor.

• Om du inte redan har ett nyckelvalv skapar du ett. Anvisningar för hur du skapar ett nyckelvalv finns i Snabbstart: Skapa ett nyckelvalv med hjälp av Azure Portal.

  Information om hur du skapar eller importerar en hemlighet till nyckelvalvet finns i Snabbstart: Ange och hämta en hemlighet från Azure Key Vault med hjälp av Azure Portal.

• Aktivera en systemtilldelad eller användartilldelad hanterad identitet i API Management-instansen.

Konfigurera åtkomst till nyckelvalv

1. I portalen navigerar du till ditt nyckelvalv.

2. I den vänstra menyn väljer du Åtkomstkonfiguration och noterar den behörighetsmodell som har konfigurerats.

3. Beroende på behörighetsmodellen konfigurerar du antingen en åtkomstprincip för nyckelvalvet eller Azure RBAC-åtkomst för en hanterad API Management-identitet.

   Så här lägger du till en åtkomstprincip för key vault:
   

   1. I den vänstra menyn väljer du Åtkomstprinciper.
   2. På sidan Åtkomstprinciper väljer du + Skapa.
   3. På fliken Behörigheter går du till Hemliga behörigheter, väljer Hämta och Lista och väljer sedan Nästa.
   4. På fliken Huvudnamn väljer du huvudnamn, söker efter resursnamnet för din hanterade identitet och väljer sedan Nästa. Om du använder en systemtilldelad identitet är huvudnamnet för din API Management-instans.
   5. Välj Nästa igen. På fliken Granska + skapa väljer du Skapa.

   Så här konfigurerar du Azure RBAC-åtkomst:
   

   1. Välj Åtkomstkontroll (IAM) i den vänstra menyn.
   2. På sidan Åtkomstkontroll (IAM) väljer du Lägg till rolltilldelning.
   3. På fliken Roll väljer du Nyckelvalvscertifikatanvändare.
   4. På fliken Medlemmar väljer du Hanterad identitet>+ Välj medlemmar.
   5. På sidan Välj hanterad identitet väljer du den systemtilldelade hanterade identiteten eller en användartilldelad hanterad identitet som är associerad med din API Management-instans och väljer sedan Välj.
   6. Välj Granska + tilldela.

Krav för Key Vault-brandvägg

Om Key Vault-brandväggen är aktiverad i nyckelvalvet är följande ytterligare krav:

• Du måste använda API Management-instansens systemtilldelade hanterade identitet för att få åtkomst till nyckelvalvet.

• I Key Vault-brandväggen aktiverar du alternativet Tillåt betrodda Microsoft-tjänster att kringgå den här brandväggen .

• Se till att din lokala klient-IP-adress tillåts komma åt nyckelvalvet tillfälligt medan du väljer ett certifikat eller en hemlighet som ska läggas till i Azure API Management. Mer information finns i Konfigurera nätverksinställningar för Azure Key Vault.

  När du har slutfört konfigurationen kan du blockera klientadressen i nyckelvalvsbrandväggen.

Krav för virtuella nätverk

Om API Management-instansen distribueras i ett virtuellt nätverk konfigurerar du även följande nätverksinställningar:

• Aktivera en tjänstslutpunkt till Azure Key Vault i API Management-undernätet.
• Konfigurera en NSG-regel (network security group) för att tillåta utgående trafik till tjänsttaggar för AzureKeyVault och AzureActiveDirectory.

Mer information finns i Nätverkskonfiguration när du konfigurerar Azure API Management i ett virtuellt nätverk.

Lägga till eller redigera ett namngivet värde

Lägga till en nyckelvalvshemlighet i API Management

Se Krav för key vault-integrering.

Viktigt!

När du lägger till en nyckelvalvshemlighet i DIN API Management-instans måste du ha behörighet att lista hemligheter från nyckelvalvet.

Varning

När du använder en nyckelvalvshemlighet i API Management bör du vara försiktig så att du inte tar bort hemligheten, nyckelvalvet eller den hanterade identitet som används för att komma åt nyckelvalvet.

1. I Azure Portal navigerar du till din API Management-instans.

2. Under API:er väljer du Namngivna värden>+Lägg till.

3. Ange en namnidentifierare och ange ett visningsnamn som används för att referera till egenskapen i principer.

4. I Värdetyp väljer du Nyckelvalv.

5. Ange identifieraren för en nyckelvalvshemlighet (utan version) eller välj Välj för att välja en hemlighet från ett nyckelvalv.

   Viktigt!

   Om du anger en hemlig identifierare för nyckelvalvet själv kontrollerar du att den inte har versionsinformation. Annars roteras inte hemligheten automatiskt i API Management efter en uppdatering i nyckelvalvet.

6. I Klientidentitet väljer du en systemtilldelad eller en befintlig användartilldelad hanterad identitet. Lär dig hur du lägger till eller ändrar hanterade identiteter i API Management-tjänsten.

   Kommentar

   Identiteten behöver behörighet för att hämta och lista hemligheter från nyckelvalvet. Om du inte redan har konfigurerat åtkomst till nyckelvalvet uppmanar API Management dig så att den automatiskt kan konfigurera identiteten med nödvändiga behörigheter.

7. Lägg till en eller flera valfria taggar som hjälper dig att organisera dina namngivna värden och sedan Spara.

8. Välj Skapa.

   

Lägga till ett enkelt eller hemligt värde i API Management

Portal

1. I Azure Portal navigerar du till din API Management-instans.
2. Under API:er väljer du Namngivna värden>+Lägg till.
3. Ange en namnidentifierare och ange ett visningsnamn som används för att referera till egenskapen i principer.
4. I Värdetyp väljer du Oformaterad eller Hemlig.
5. I Värde anger du ett sträng- eller principuttryck.
6. Lägg till en eller flera valfria taggar som hjälper dig att organisera dina namngivna värden och sedan Spara.
7. Välj Skapa.

När det namngivna värdet har skapats kan du redigera det genom att välja namnet. Om du ändrar visningsnamnet uppdateras alla principer som refererar till det namngivna värdet automatiskt för att använda det nya visningsnamnet.

Azure CLI

Så här börjar du använda Azure CLI:

• Använd Bash-miljön i Azure Cloud Shell. Mer information finns i Snabbstart för Bash i Azure Cloud Shell.

  

• Om du föredrar att köra CLI-referenskommandon lokalt installerar du Azure CLI. Om du kör i Windows eller macOS kan du köra Azure CLI i en Docker-container. Mer information finns i Så här kör du Azure CLI i en Docker-container.

  • Om du använder en lokal installation loggar du in på Azure CLI med hjälp av kommandot az login. Slutför autentiseringsprocessen genom att följa stegen som visas i terminalen. Andra inloggningsalternativ finns i Logga in med Azure CLI.

  • När du uppmanas att installera Azure CLI-tillägget vid första användningen. Mer information om tillägg finns i Använda tillägg med Azure CLI.

  • Kör az version om du vill hitta versionen och de beroende bibliotek som är installerade. Om du vill uppgradera till den senaste versionen kör du az upgrade.

Om du vill lägga till ett namngivet värde använder du kommandot az apim nv create :

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

När du har skapat ett namngivet värde kan du uppdatera det med hjälp av kommandot az apim nv update . Om du vill se alla namngivna värden kör du kommandot az apim nv list :

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

Om du vill se information om det namngivna värdet som du skapade för det här exemplet kör du kommandot 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

Det här exemplet är ett hemligt värde. Föregående kommando returnerar inte värdet. Om du vill se värdet kör du kommandot 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

Om du vill ta bort ett namngivet värde använder du kommandot 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

Använda ett namngivet värde

Exemplen i det här avsnittet använder de namngivna värden som visas i följande tabell.

Name	Värde	Hemlig
ContosoHeader	TrackingId	Falsk
ContosoHeaderValue	••••••••••••••••••••••	Sant
ExpressionProperty	@(DateTime.Now.ToString())	Falsk
ContosoHeaderValue2	This is a header value.	Falsk

Om du vill använda ett namngivet värde i en princip placerar du dess visningsnamn i ett dubbelt par klammerparenteser som {{ContosoHeader}}, som du ser i följande exempel:

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

I det här exemplet ContosoHeader används som namnet på en rubrik i en set-header princip och ContosoHeaderValue används som värde för rubriken. När den här principen utvärderas under en begäran eller ett svar på API Management-gatewayen {{ContosoHeader}} {{ContosoHeaderValue}} och ersätts med respektive värden.

Namngivna värden kan användas som fullständiga attribut- eller elementvärden enligt föregående exempel, men de kan också infogas i eller kombineras med en del av ett literalt textuttryck som visas i följande exempel:

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

Namngivna värden kan också innehålla principuttryck. I följande exempel ExpressionProperty används uttrycket.

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

När den här principen utvärderas {{ExpressionProperty}} ersätts med dess värde, @(DateTime.Now.ToString()). Eftersom värdet är ett principuttryck utvärderas uttrycket och principen fortsätter med körningen.

Du kan testa detta i Azure Portal eller utvecklarportalen genom att anropa en åtgärd som har en princip med namngivna värden i omfånget. I följande exempel anropas en åtgärd med de två föregående exempelprinciperna set-header med namngivna värden. Observera att svaret innehåller två anpassade rubriker som har konfigurerats med principer med namngivna värden.

Om du tittar på den utgående API-spårningen för ett anrop som innehåller de två tidigare exempelprinciperna med namngivna värden kan du se de två set-header principerna med de namngivna värdena infogade samt utvärdering av principuttryck för det namngivna värdet som innehöll principuttrycket.

Stränginterpolation kan också användas med namngivna värden.

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

Värdet för CustomHeader blir The URL encoded value is This+is+a+header+value..

Varning

Om en princip refererar till en hemlighet i Azure Key Vault visas värdet från nyckelvalvet för användare som har åtkomst till prenumerationer som är aktiverade för spårning av API-begäranden.

Även om namngivna värden kan innehålla principuttryck kan de inte innehålla andra namngivna värden. Om text som innehåller en namngiven värdereferens används för ett värde, till exempel Text: {{MyProperty}}, kommer referensen inte att matchas och ersättas.

Ta bort ett namngivet värde

Om du vill ta bort ett namngivet värde väljer du namnet och väljer sedan Ta bort på snabbmenyn (...).

Viktigt!

Om det namngivna värdet refereras av några API Management-principer kan du inte ta bort det förrän du tar bort det namngivna värdet från alla principer som använder det.

Nästa steg

• Läs mer om att arbeta med principer
  • Principer i API Management
  • Principreferens
  • Principuttryck