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. Beleidsinstructies kunnen worden samengesteld met letterlijke tekstwaarden, beleidsexpressies en benoemde waarden.

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

Waardetypen

Type	Description
Plain	Letterlijke tekenreeks of beleidsexpressie
Geheim	Letterlijke tekenreeks of beleidsexpressie die is versleuteld door API Management
Sleutelkluis	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.

Sleutelkluisgeheimen

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.

Vereisten

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

Vereisten voor key vault-integratie

• 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. Navigeer in de portal naar uw sleutelkluis.

2. Selecteer in het linkermenu De configuratie van Access en noteer het machtigingsmodel dat is geconfigureerd.

3. Afhankelijk van het machtigingsmodel configureert u een toegangsbeleid voor key vault of Azure RBAC-toegang voor een beheerde API Management-identiteit.

   Ga als volgende te werk om toegangsbeleid voor key vault toe te voegen:
   

   1. Selecteer toegangsbeleid in het linkermenu.
   2. Selecteer + Maken op de pagina Toegangsbeleid.
   3. Selecteer Op het tabblad Machtigingen onder Geheime machtigingen de optie Ophalen en lijst en selecteer vervolgens Volgende.
   4. Selecteer principal op het tabblad Principal, zoek 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 op het tabblad Rol de sleutelkluiscertificaatgebruiker.
   4. Selecteer Op het tabblad Leden beheerde identiteit>+ Leden selecteren.
   5. Selecteer op de pagina Beheerde identiteit selecteren de door het systeem toegewezen beheerde identiteit of een door de gebruiker toegewezen beheerde identiteit die is gekoppeld aan uw API Management-exemplaar en selecteer vervolgens Selecteren.
   6. Selecteer Controleren + toewijzen.

Vereisten voor Key Vault-firewall

Als Key Vault-firewall is ingeschakeld voor uw sleutelkluis, zijn de volgende aanvullende vereisten:

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

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

• 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 Azure Key Vault in het API Management-subnet.
• Configureer een netwerkbeveiligingsgroepregel (NSG) om uitgaand verkeer naar de AzureKeyVault- en AzureActiveDirectory-servicetags toe te staan.

Zie De netwerkconfiguratie bij het instellen van Azure API Management in een VNet 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.

Let op

Wanneer u een sleutelkluisgeheim gebruikt in API Management, moet u ervoor waken dat u het geheim, de sleutelkluis of de beheerde identiteit verwijdert die wordt gebruikt voor toegang tot de sleutelkluis.

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

2. Selecteer onder API's benoemde 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 draait het geheim niet automatisch in API Management na een update in de sleutelkluis.

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.

   Notitie

   De identiteit heeft machtigingen nodig om geheimen op te halen en weer te geven 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. Selecteer Maken.

   

Een gewone of geheime waarde toevoegen aan API Management

Portal

1. Blader in Azure Portal naar uw API Management-exemplaar.
2. Selecteer onder API's benoemde 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 waardetype de 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. Selecteer Maken.

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 quickstart voor Bash in Azure Cloud Shell voor meer informatie.

  

• Installeer de Azure CLI, indien gewenst, om CLI-referentieopdrachten uit te voeren. Als u in Windows of macOS werkt, kunt u Azure CLI uitvoeren in een Docker-container. Zie De Azure CLI uitvoeren in een Docker-container voor meer informatie.

  • Als u een lokale installatie gebruikt, meldt u zich aan bij Azure CLI met behulp van de opdracht az login. Volg de stappen die worden weergegeven in de terminal, om het verificatieproces te voltooien. Raadpleeg Aanmelden bij Azure CLI voor aanvullende aanmeldingsopties.

  • Installeer de Azure CLI-extensie bij het eerste gebruik, wanneer u hierom wordt gevraagd. Raadpleeg Extensies gebruiken met Azure CLI voor meer informatie over extensies.

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

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	Weergegeven als	Geheim
ContosoHeader	TrackingId	Onwaar
ContosoHeaderValue	••••••••••••••••••••••	Waar
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 en {{ContosoHeader}}{{ContosoHeaderValue}} worden 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..

Let op

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 waardereferentie wordt gebruikt voor een waarde, zoals Text: {{MyProperty}}, wordt die verwijzing niet omgezet 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.

Volgende stappen

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