Benoemde waarden gebruiken in Azure API Management-beleid

Van toepassing op: Alle API Management-lagen

API Management-beleid is een krachtige mogelijkheid van het systeem waarmee de uitgever het gedrag van de API kan wijzigen via configuratie. Beleidsregels zijn een verzameling instructies die sequentieel worden uitgevoerd op de aanvraag of het antwoord van een API. Beleidsuitspraken kunnen worden samengesteld met letterlijke tekstwaarden, beleidsuitdrukkingen en benoemde waarden.

Benoemde waarden zijn een globale verzameling naam-/waardeparen in elk API Management-exemplaar. Benoemde waarden kunnen worden gebruikt voor het beheren van constante tekenreekswaarden en geheimen voor alle API-configuraties en -beleidsregels.

Waardetypen

Typologie	Beschrijving
Vlakte	Letterlijke tekenreeks of beleidsexpressie
Geheim	Letterlijke tekenreeks of beleidsexpressie die is versleuteld door API Management
Key Vault	Id van een geheim dat is opgeslagen in een Azure-sleutelkluis.

Gewone waarden of geheimen kunnen beleidsexpressies bevatten. De expressie @(DateTime.Now.ToString()) retourneert bijvoorbeeld een tekenreeks met de huidige datum en tijd.

Zie de API Management REST API-verwijzing voor meer informatie over de benoemde waardekenmerken.

Geheimen van de sleutelkluis

Geheime waarden kunnen worden opgeslagen als versleutelde tekenreeksen in API Management (aangepaste geheimen) of door te verwijzen naar geheimen in Azure Key Vault.

Het gebruik van key vault-geheimen wordt aanbevolen omdat hiermee de beveiliging van API Management wordt verbeterd:

• Geheimen die zijn opgeslagen in sleutelkluizen kunnen opnieuw worden gebruikt in verschillende services
• Gedetailleerde toegangsbeleidsregels kunnen worden toegepast op geheimen
• Geheimen die in de sleutelkluis worden bijgewerkt, worden automatisch geroteerd in API Management. Na de update in de sleutelkluis wordt een benoemde waarde in API Management binnen 4 uur bijgewerkt. U kunt het geheim ook handmatig vernieuwen via Azure Portal of via de REST API voor beheer.

Opmerking

De geheimen die zijn opgeslagen in Azure Key Vault moeten tussen 1 en 4096 tekens liggen, omdat API Management geen waarden kan ophalen die deze limiet overschrijden.

Vereiste voorwaarden

• Zie Een API Management-service-exemplaar maken als u nog geen API Management-service-exemplaar hebt gemaakt.

Vereisten voor key vault-integratie

Opmerking

Deze functie is momenteel niet beschikbaar in werkruimten.

• Als u nog geen sleutelkluis hebt, maakt u er een. Zie quickstart: Een sleutelkluis maken met behulp van Azure Portal voor stappen voor het maken van een sleutelkluis.

  Als u een geheim wilt maken of importeren in de sleutelkluis, raadpleegt u quickstart: Een geheim instellen en ophalen uit Azure Key Vault met behulp van Azure Portal.

• Schakel een door het systeem toegewezen of door de gebruiker toegewezen beheerde identiteit in het API Management-exemplaar in.

Toegang tot key vault configureren

1. Ga in de portal naar uw Key Vault.
2. Selecteer in het linkermenu De configuratie van Access. Let op het machtigingsmodel dat is geconfigureerd.
3. Afhankelijk van het machtigingsmodel configureert u een key vault-toegangsbeleid of Azure RBAC-toegang voor een beheerde identiteit binnen API Management.

Om een toegangsbeleid voor een key vault toe te voegen:

1. Selecteer toegangsbeleid in het linkermenu.
2. Op de pagina Toegangsbeleid, selecteer + Toevoegen.
3. Selecteer Op het tabblad Machtigingen onder Geheime machtigingen de optie Ophalen en weergeven en selecteer vervolgens Volgende.
4. Klik op het tabblad Principal, selecteer Principal, zoek naar de resourcenaam van uw beheerde identiteit en selecteer Vervolgens Volgende. Als u een door het systeem toegewezen identiteit gebruikt, is de principal de naam van uw API Management-exemplaar.
5. Selecteer Volgende opnieuw. Selecteer op het tabblad Beoordelen en maken de optie Maken.

Azure RBAC-toegang configureren:

1. Selecteer toegangsbeheer (IAM) in het linkermenu.
2. Selecteer Op de pagina Toegangsbeheer (IAM) de optie Roltoewijzing toevoegen.
3. Selecteer Key Vault Secrets User op het tabblad Rol.
4. Op het tabblad Leden selecteer beheerde identiteit>+ Leden selecteren.
5. Selecteer op de pagina Beheerde identiteit selecteren de beheerde identiteit die door het systeem is toegewezen of een door de gebruiker toegewezen beheerde identiteit die gekoppeld is aan uw API Management-exemplaar en selecteer vervolgens Selecteren.
6. Selecteer Beoordelen en toewijzen.

Vereisten voor Key Vault-firewall

Als Key Vault-firewall is ingeschakeld voor uw sleutelkluis, moet u aan deze vereisten voldoen:

• U moet de door het systeem toegewezen beheerde identiteit van het API Management-exemplaar gebruiken om toegang te krijgen tot de sleutelkluis.

• Schakel in de Key Vault-firewall de optie Vertrouwde Microsoft-services toestaan om deze firewall te omzeilen in.

• Zorg ervoor dat uw lokale client-IP-adres tijdelijk toegang heeft tot de sleutelkluis terwijl u een certificaat of geheim selecteert om toe te voegen aan Azure API Management. Zie Azure Key Vault-netwerkinstellingen configureren voor meer informatie.

  Nadat u de configuratie hebt voltooid, kunt u het clientadres blokkeren in de firewall van de sleutelkluis.

Vereisten voor het virtuele netwerk

Als het API Management-exemplaar wordt geïmplementeerd in een virtueel netwerk, configureert u ook de volgende netwerkinstellingen:

• Schakel een service-eindpunt in voor Key Vault in het API Management-subnet.
• Configureer een NSG-regel voor netwerkbeveiliging om uitgaand verkeer naar de AzureKeyVault- en AzureActiveDirectory-service tags toe te staan.

Zie De netwerkconfiguratie bij het instellen van API Management in een virtueel netwerk voor meer informatie.

Een benoemde waarde toevoegen of bewerken

Een sleutelkluisgeheim toevoegen aan API Management

Zie Vereisten voor key vault-integratie.

Belangrijk

Wanneer u een sleutelkluisgeheim toevoegt aan uw API Management-exemplaar, moet u gemachtigd zijn om geheimen uit de sleutelkluis weer te geven.

Waarschuwing

Wanneer u een sleutelkluisegeheim gebruikt in API Management, wees voorzichtig om het geheim, de sleutelkluis of de beheerde identiteit die wordt gebruikt voor toegang tot de sleutelkluis niet te verwijderen.

1. Blader in Azure Portal naar uw API Management-exemplaar.

2. Selecteer onder API'sbenoemde waarden>+Toevoegen.

3. Voer een naam-id in en voer een weergavenaam in die wordt gebruikt om te verwijzen naar de eigenschap in beleidsregels.

4. Selecteer Sleutelkluis in waardetype.

5. Voer de id in van een sleutelkluisgeheim (zonder versie) of kies Selecteren om een geheim in een sleutelkluis te selecteren.

   Belangrijk

   Als u zelf een sleutelkluisgeheim-id invoert, moet u ervoor zorgen dat deze geen versiegegevens bevat. Anders wordt het geheim in API Management na een update in de sleutelkluis niet automatisch vervangen.

6. Selecteer in clientidentiteit een door het systeem toegewezen of een bestaande door de gebruiker toegewezen beheerde identiteit. Meer informatie over het toevoegen of wijzigen van beheerde identiteiten in uw API Management-service.

   Opmerking

   De identiteit heeft machtigingen nodig om geheimen op te halen en op te sommen uit de sleutelkluis. Als u nog geen toegang tot de sleutelkluis hebt geconfigureerd, wordt u door API Management gevraagd om de identiteit automatisch te configureren met de benodigde machtigingen.

7. Voeg een of meer optionele tags toe om uw benoemde waarden te ordenen en vervolgens Op te slaan.

8. Klik op Creëren.

   

Een gewone of geheime waarde toevoegen aan API Management

Portaal

1. Blader in Azure Portal naar uw API Management-exemplaar.
2. Selecteer onder API'sbenoemde waarden>+Toevoegen.
3. Voer een naam-id in en voer een weergavenaam in die wordt gebruikt om te verwijzen naar de eigenschap in beleidsregels.
4. Selecteer In waardetypede optie Plain of Secret.
5. Voer in Waarde een tekenreeks of beleidsexpressie in.
6. Voeg een of meer optionele tags toe om uw benoemde waarden te ordenen en vervolgens Op te slaan.
7. Klik op Creëren.

Zodra de benoemde waarde is gemaakt, kunt u deze bewerken door de naam te selecteren. Als u de weergavenaam wijzigt, worden beleidsregels die verwijzen naar de benoemde waarde automatisch bijgewerkt om de nieuwe weergavenaam te gebruiken.

Azure CLI

Ga als volgt te werk om Azure CLI te gebruiken:

• Gebruik de Bash-omgeving in Azure Cloud Shell. Zie Aan de slag met Azure Cloud Shell voor meer informatie.

  

• Als je de voorkeur geeft aan het lokaal uitvoeren van CLI-referentiecommando's, installeer dan de Azure CLI. Als je op Windows of macOS werkt, overweeg dan om Azure CLI in een Docker-container te draaien. Voor meer informatie, zie Hoe u de Azure CLI in een Docker-container kunt uitvoeren.

  • Als u een lokale installatie gebruikt, meldt u zich aan bij Azure CLI met de opdracht az login. Om het authenticatieproces te voltooien, volgt u de stappen die op uw terminal worden weergegeven. Zie Verifiëren bij Azure met behulp van Azure CLI voor andere aanmeldingsopties.

  • Wanneer u daarom wordt gevraagd, installeer de Azure CLI-extensie bij het eerste gebruik. Zie Extensies gebruiken en beheren met de Azure CLIvoor meer informatie over extensies.

  • Voer az version uit om de geïnstalleerde versie en de afhankelijke bibliotheken te vinden. Voer az upgrade uit om naar de nieuwste versie te upgraden.

Als u een benoemde waarde wilt toevoegen, gebruikt u de opdracht 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

Nadat u een benoemde waarde hebt gemaakt, kunt u deze bijwerken met behulp van de opdracht az apim nv update . Als u al uw benoemde waarden wilt zien, voert u de opdracht az apim nv list uit:

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

Als u de details wilt zien van de benoemde waarde die u voor dit voorbeeld hebt gemaakt, voert u de opdracht az apim nv show uit:

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

Dit voorbeeld is een geheime waarde. De vorige opdracht retourneert de waarde niet. Voer de opdracht az apim nv show-secret uit om de waarde te bekijken:

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

Als u een benoemde waarde wilt verwijderen, gebruikt u de opdracht 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

Een benoemde waarde gebruiken

In de voorbeelden in deze sectie worden de benoemde waarden gebruikt die worden weergegeven in de volgende tabel.

Naam	Waarde	Geheim
ContosoHeader	TrackingId	Onwaar
ContosoHeaderValue	••••••••••••••••••••••	Klopt
ExpressionProperty	@(DateTime.Now.ToString())	Onwaar
ContosoHeaderValue2	This is a header value.	Onwaar

Als u een benoemde waarde in een beleid wilt gebruiken, plaatst u de weergavenaam in een dubbel paar accolades, zoals {{ContosoHeader}}wordt weergegeven in het volgende voorbeeld:

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

In dit voorbeeld ContosoHeader wordt deze gebruikt als de naam van een header in een set-header beleid en ContosoHeaderValue wordt deze gebruikt als de waarde van die header. Wanneer dit beleid wordt geëvalueerd tijdens een aanvraag of reactie op de API Management-gateway, worden {{ContosoHeader}} en {{ContosoHeaderValue}} vervangen door hun respectieve waarden.

Benoemde waarden kunnen worden gebruikt als volledige kenmerk- of elementwaarden, zoals wordt weergegeven in het vorige voorbeeld, maar ze kunnen ook worden ingevoegd in of gecombineerd met een deel van een letterlijke tekstexpressie, zoals wordt weergegeven in het volgende voorbeeld:

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

Benoemde waarden kunnen ook beleidsexpressies bevatten. In het volgende voorbeeld wordt de ExpressionProperty expressie gebruikt.

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

Wanneer dit beleid wordt geëvalueerd, {{ExpressionProperty}} wordt deze vervangen door de bijbehorende waarde. @(DateTime.Now.ToString()) Omdat de waarde een beleidsexpressie is, wordt de expressie geëvalueerd en wordt het beleid uitgevoerd.

U kunt dit testen in Azure Portal of de ontwikkelaarsportal door een bewerking aan te roepen met een beleid met benoemde waarden binnen het bereik. In het volgende voorbeeld wordt een bewerking aangeroepen met het twee vorige voorbeeldbeleid set-header met benoemde waarden. U ziet dat het antwoord twee aangepaste headers bevat die zijn geconfigureerd met behulp van beleid met benoemde waarden.

Als u de uitgaande API-trace bekijkt voor een aanroep die de twee vorige voorbeeldbeleidsregels met benoemde waarden bevat, ziet u de twee set-header beleidsregels waarin de benoemde waarden zijn ingevoegd en de evaluatie van de beleidsexpressie voor de benoemde waarde die de beleidsexpressie bevat.

Tekenreeksinterpolatie kan ook worden gebruikt met benoemde waarden.

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

De waarde voor CustomHeader is The URL encoded value is This+is+a+header+value..

Waarschuwing

Als een beleid verwijst naar een geheim in Azure Key Vault, is de waarde van de sleutelkluis zichtbaar voor gebruikers die toegang hebben tot abonnementen waarvoor API-aanvraagtracering is ingeschakeld.

Hoewel benoemde waarden beleidsexpressies kunnen bevatten, kunnen ze geen andere benoemde waarden bevatten. Als tekst met een benoemde waardeverwijzing wordt gebruikt voor een waarde, zoals Text: {{MyProperty}}, dan zal die verwijzing niet worden opgelost en vervangen.

Een benoemde waarde verwijderen

Als u een benoemde waarde wilt verwijderen, selecteert u de naam en selecteert u Verwijderen in het contextmenu (...).

Belangrijk

Als naar de benoemde waarde wordt verwezen door een API Management-beleid, kunt u deze pas verwijderen als u de benoemde waarde verwijdert uit alle beleidsregels die deze gebruiken.

Verwante inhoud

• Meer informatie over het werken met beleid
  • Beleid in API Management
  • Beleidsreferentie
  • Beleidsexpressies