Benoemde waarden gebruiken in Azure API Management-beleid

API Management beleidsregels zijn een krachtige mogelijkheid van het systeem waarmee de uitgever het gedrag van de API via configuratie kan wijzigen. Beleidsregels zijn een verzameling instructies die sequentieel worden uitgevoerd op de aanvraag of het antwoord van een API. Beleidsinstructies kunnen worden samengesteld met behulp van 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 in alle API-configuraties en -beleidsregels.

Named values in the Azure portal

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 naslaginformatie over de API Management REST API voor meer informatie over de benoemde waardekenmerken.

Key Vault-geheimen

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 dit helpt bij het verbeteren van API Management beveiliging:

  • Geheimen die zijn opgeslagen in sleutelkluizen kunnen opnieuw worden gebruikt in services
  • Gedetailleerd toegangsbeleid kan worden toegepast op geheimen
  • Geheimen die zijn bijgewerkt in de sleutelkluis, 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 met behulp van de Azure Portal of via de REST API voor beheer.

Vereisten voor key vault-integratie

  1. Zie Quickstart: Een sleutelkluis maken met behulp van de Azure Portal voor stappen voor het maken van een sleutelkluis.
  2. Schakel een door het systeem toegewezen of door de gebruiker toegewezen beheerde identiteit in het API Management exemplaar in.
  3. Wijs een sleutelkluistoegangsbeleid toe aan de beheerde identiteit met machtigingen om geheimen op te halen en weer te geven uit de kluis. Het beleid toevoegen:
    1. Navigeer in de portal naar uw sleutelkluis.
    2. Selecteer Instellingen > Toegangsbeleid > +Toegangsbeleid toevoegen.
    3. Selecteer Geheime machtigingen en selecteer Vervolgens Ophalen en Lijst.
    4. Selecteer in Principal selecteren de resourcenaam van uw beheerde identiteit. Als u een door het systeem toegewezen identiteit gebruikt, is de principal de naam van uw API Management exemplaar.
  4. Maak of importeer een geheim in de sleutelkluis. Zie quickstart: Een geheim instellen en ophalen uit Azure Key Vault met behulp van de Azure Portal.

Als u het sleutelkluisgeheim wilt gebruiken, voegt u een benoemde waarde toe of bewerkt u deze en geeft u een type sleutelkluis op. Selecteer het geheim in de sleutelkluis.

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.

Vereisten voor het virtuele netwerk

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

  • Een service-eindpunt inschakelen naar Azure Key Vault op het API Management subnet.
  • Configureer een NSG-regel (netwerkbeveiligingsgroep) om uitgaand verkeer naar de servicetags AzureKeyVault en AzureActiveDirectory toe te staan.

Zie Netwerkconfiguratie bij het instellen van Azure API Management in een VNet voor meer informatie.

Een benoemde waarde toevoegen of bewerken

Een sleutelkluisgeheim toevoegen

Zie Vereisten voor sleutelkluisintegratie.

Waarschuwing

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

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

  2. Selecteer Benoemde waarden>+Toevoegen onder API's.

  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 te selecteren in een sleutelkluis.

    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 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 sla op.

  8. Selecteer Maken.

    Add key vault secret value

Een gewone of geheime waarde toevoegen

  1. Blader in Azure Portal naar uw API Management-exemplaar.
  2. Selecteer Benoemde waarden>+Toevoegen onder API's.
  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 Niet-opgemaakt of Geheim.
  5. Voer in Waarde een tekenreeks of beleidsexpressie in.
  6. Voeg een of meer optionele tags toe om uw benoemde waarden te ordenen en sla op.
  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.

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 Niet waar
ContosoHeaderValue •••••••••••••••••••••• Waar
ExpressionProperty @(DateTime.Now.ToString()) Niet waar

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 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 de Azure Portal of de ontwikkelaarsportal door een bewerking aan te roepen met een beleid met benoemde waarden in 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 beleidsregels met benoemde waarden.

Test API response

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 met de benoemde waarden ingevoegd en de evaluatie van de beleidsexpressie voor de benoemde waarde die de beleidsexpressie bevat.

API Inspector trace

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 die zijn ingeschakeld voor tracering van API-aanvragen.

Hoewel benoemde waarden beleidsexpressies kunnen bevatten, kunnen ze geen andere benoemde waarden bevatten. Als tekst met een verwijzing naar een benoemde waarde 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