Läs på engelska

Dela via

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

  • Artikel

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.

Namngivna värden i Azure Portal

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.

Anteckning

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

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

Anteckning

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

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 Nyckelvalvshemlighetsanvä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:

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.

    Anteckning

    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ägg till nyckelvalvshemlighetsvärde

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

  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.

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:

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

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

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

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

Test-API-svar

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.

API Inspector-spårning

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

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