Névvel ellátott értékek használata az Azure API Management-szabályzatokban

  • Cikk

A KÖVETKEZŐRE VONATKOZIK: Minden API Management-szint

Az API Management-szabályzatok a rendszer hatékony funkciói, amelyek lehetővé teszik a közzétevő számára, hogy konfiguráción keresztül módosítsa az API viselkedését. A házirendek utasítások gyűjteményei, amelyeket az API-k kérelmei és válaszai szerint egymást követően hajtanak végre. A házirend-utasítások konstans szöveges értékek, szabályzatkifejezések és elnevezett értékek használatával hozhatók létre.

Az elnevezett értékek az egyes API Management-példányokban található név-érték párok globális gyűjteményei. A gyűjteményben lévő elemek száma nincs korlátozva. Az elnevezett értékek az állandó sztringértékek és titkos kódok kezelésére használhatók minden API-konfigurációban és szabályzatban.

Elnevezett értékek az Azure Portalon

Értéktípusok

Típus Leírás
Sima Literális sztring vagy szabályzatkifejezés
Titkos Az API Management által titkosított literális sztring vagy szabályzatkifejezés
Key Vault Egy Azure-kulcstartóban tárolt titkos kód azonosítója.

Az egyszerű értékek vagy titkos kódok szabályzatkifejezéseket tartalmazhatnak. A kifejezés @(DateTime.Now.ToString()) például egy sztringet ad vissza, amely az aktuális dátumot és időt tartalmazza.

A névvel ellátott értékattribútumokról az API Management REST API-referenciában talál további információt.

Kulcstartó titkos kulcsai

A titkos értékek titkosított sztringekként tárolhatók az API Managementben (egyéni titkos kódok), vagy hivatkozhatnak titkos kulcsokra az Azure Key Vaultban.

A Key Vault titkos kulcsok használata azért ajánlott, mert segít az API Management biztonságának javításában:

  • A kulcstartókban tárolt titkos kulcsok a szolgáltatások között újra felhasználhatók
  • Részletes hozzáférési szabályzatok alkalmazhatók titkos kódokra
  • A kulcstartóban frissített titkos kulcsok automatikusan el lesznek forgatva az API Managementben. A key vault frissítése után az API Management egy elnevezett értéke 4 órán belül frissül. A titkos kód manuálisan is frissíthető az Azure Portalon vagy a felügyeleti REST API-val.

Előfeltételek

A Key Vault integrációjának előfeltételei

A Key Vaulthoz való hozzáférés konfigurálása

  1. A portálon keresse meg a kulcstartót.

  2. A bal oldali menüben válassza az Access-konfigurációt, és jegyezze fel a konfigurált engedélymodellt.

  3. Az engedélymodelltől függően konfiguráljon kulcstartó-hozzáférési szabályzatot vagy Azure RBAC-hozzáférést egy API Management által felügyelt identitáshoz.

    Kulcstartó hozzáférési szabályzatának hozzáadása:

    1. A bal oldali menüben válassza az Access-szabályzatok lehetőséget.
    2. Az Access-szabályzatok lapon válassza a + Létrehozás lehetőséget.
    3. Az Engedélyek lap Titkos engedélyek csoportjában válassza a Beolvasás és a Lista lehetőséget, majd a Tovább gombot.
    4. Az Egyszerű lapon válassza ki az egyszerű nevet, keresse meg a felügyelt identitás erőforrásnevét, majd válassza a Tovább gombot. Ha rendszer által hozzárendelt identitást használ, az egyszerű az API Management-példány neve.
    5. Kattintson ismét a Tovább gombra. A Véleményezés + létrehozás lapon válassza a Létrehozás lehetőséget.

    Az Azure RBAC-hozzáférés konfigurálása:

    1. A bal oldali menüben válassza a Hozzáférés-vezérlés (IAM) lehetőséget.
    2. A Hozzáférés-vezérlés (IAM) lapon válassza a Szerepkör-hozzárendelés hozzáadása lehetőséget.
    3. A Szerepkör lapon válassza a Key Vault tanúsítványfelhasználója lehetőséget.
    4. A Tagok lapon válassza a Felügyelt identitás>+ Tagok kijelölése lehetőséget.
    5. A Felügyelt identitás kiválasztása lapon válassza ki a rendszer által hozzárendelt felügyelt identitást vagy az API Management-példányhoz társított felhasználó által hozzárendelt felügyelt identitást, majd válassza a Kiválasztás lehetőséget.
    6. Válassza az Áttekintés + hozzárendelés lehetőséget.

A Key Vault tűzfalának követelményei

Ha a Key Vault tűzfala engedélyezve van a kulcstartón, a következő további követelmények teljesülnek:

  • A kulcstartó eléréséhez az API Management-példány rendszer által hozzárendelt felügyelt identitását kell használnia.

  • A Key Vault tűzfalában engedélyezze a Megbízható Microsoft-szolgáltatások engedélyezését a tűzfal lehetőség megkerüléséhez.

  • Győződjön meg arról, hogy a helyi ügyfél IP-címe átmenetileg hozzáférhet a kulcstartóhoz, miközben kiválaszt egy tanúsítványt vagy titkos kulcsot, amelyet fel szeretne adni az Azure API Managementbe. További információ: Az Azure Key Vault hálózati beállításainak konfigurálása.

    A konfiguráció befejezése után letilthatja az ügyfél címét a Key Vault tűzfalán.

A virtuális hálózatra vonatkozó követelmények

Ha az API Management-példány virtuális hálózaton van üzembe helyezve, konfigurálja a következő hálózati beállításokat is:

  • Szolgáltatásvégpont engedélyezése az Azure Key Vaultban az API Management alhálózaton.
  • Konfiguráljon egy hálózati biztonsági csoportot (NSG- szabályt) az AzureKeyVault és az AzureActiveDirectory szolgáltatáscímkék kimenő forgalmának engedélyezéséhez.

További információ: Hálózati konfiguráció az Azure API Management virtuális hálózaton való beállításakor.

Névvel ellátott érték hozzáadása vagy szerkesztése

Kulcstartó titkos kulcsának hozzáadása az API Managementhez

Tekintse meg a Key Vault integrációjának előfeltételeit.

Fontos

Amikor kulcstartó-titkos kulcsot ad hozzá az API Management-példányhoz, rendelkeznie kell a kulcstartó titkos kulcsainak listázásához szükséges engedélyekkel.

Figyelemfelhívás

Ha kulcstartó-titkos kulcsot használ az API Managementben, ügyeljen arra, hogy ne törölje a kulcstartó eléréséhez használt titkos kulcsot, kulcstartót vagy felügyelt identitást.

  1. Az Azure Portalon keresse meg az API Management-példányt.

  2. Az API-k alatt válassza az Elnevezett értékek>+Hozzáadás lehetőséget.

  3. Adjon meg egy névazonosítót, és adjon meg egy megjelenítendő nevet, amellyel a házirendekben hivatkozhat a tulajdonságra.

  4. Az Érték típusban válassza a Key Vault lehetőséget.

  5. Adja meg a kulcstartó titkos kulcsának azonosítóját (verzió nélkül), vagy válassza a Kiválasztás lehetőséget a kulcstartó titkos kulcsának kiválasztásához.

    Fontos

    Ha saját maga adja meg a key vault titkos azonosítóját, győződjön meg arról, hogy nem rendelkezik verzióinformációval. Ellenkező esetben a titkos kód nem forog automatikusan az API Managementben a kulcstartó frissítését követően.

  6. Az ügyfélidentitásban válasszon ki egy rendszer által hozzárendelt vagy egy meglévő, felhasználó által hozzárendelt felügyelt identitást. Megtudhatja, hogyan vehet fel vagy módosíthat felügyelt identitásokat az API Management szolgáltatásban.

    Feljegyzés

    Az identitásnak engedélyekre van szüksége a kulcstartó titkos kulcsainak lekéréséhez és listázásához. Ha még nem konfigurálta a kulcstartóhoz való hozzáférést, az API Management kéri, hogy automatikusan konfigurálhassa az identitást a szükséges engedélyekkel.

  7. Adjon hozzá egy vagy több választható címkét a névvel ellátott értékek rendszerezéséhez, majd a Mentés parancshoz.

  8. Válassza a Létrehozás lehetőséget.

    Kulcstartó titkos kulcsértékének hozzáadása

Egyszerű vagy titkos érték hozzáadása az API Managementhez

  1. Az Azure Portalon keresse meg az API Management-példányt.
  2. Az API-k alatt válassza az Elnevezett értékek>+Hozzáadás lehetőséget.
  3. Adjon meg egy névazonosítót, és adjon meg egy megjelenítendő nevet, amellyel a házirendekben hivatkozhat a tulajdonságra.
  4. Az Érték típusban válassza az Egyszerű vagy a Titkos elemet.
  5. Az Érték mezőbe írjon be egy sztringet vagy egy szabályzatkifejezést.
  6. Adjon hozzá egy vagy több választható címkét a névvel ellátott értékek rendszerezéséhez, majd a Mentés parancshoz.
  7. Válassza a Létrehozás lehetőséget.

A névvel ellátott érték létrehozása után a név kiválasztásával szerkesztheti azt. Ha módosítja a megjelenített nevet, a névvel ellátott értékre hivatkozó házirendek automatikusan frissülnek az új megjelenítendő név használatára.

Névvel ellátott érték használata

Az ebben a szakaszban szereplő példák az alábbi táblázatban látható elnevezett értékeket használják.

Név szerint Érték Titkos
ContosoHeader TrackingId Hamis
ContosoHeaderValue •••••••••••••••••••••• Igaz
ExpressionProperty @(DateTime.Now.ToString()) Hamis
ContosoHeaderValue2 This is a header value. Hamis

Ha elnevezett értéket szeretne használni egy szabályzatban, helyezze a megjelenítendő nevét egy dupla zárójelpárba, például {{ContosoHeader}}a következő példában látható módon:

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

Ebben a példában ContosoHeader a szabályzat fejlécének set-header neveként használatos, és ContosoHeaderValue az adott fejléc értékeként használatos. Ha a szabályzat kiértékelése az API Management-átjáróra irányuló kérés vagy válasz során történik, {{ContosoHeader}} és {{ContosoHeaderValue}} a rendszer lecseréli a megfelelő értékeket.

Az elnevezett értékek használhatók teljes attribútumként vagy elemértékként az előző példában látható módon, de a literális szövegkifejezések egy részével is beilleszthetők vagy kombinálhatók az alábbi példában látható módon:

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

A névvel ellátott értékek szabályzatkifejezéseket is tartalmazhatnak. Az alábbi példában a ExpressionProperty kifejezés használatos.

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

A szabályzat kiértékelése {{ExpressionProperty}} után a rendszer lecseréli annak értékét. @(DateTime.Now.ToString()) Mivel az érték egy szabályzatkifejezés, a rendszer kiértékeli a kifejezést, és a szabályzat végrehajtása folytatódik.

Ezt az Azure Portalon vagy a fejlesztői portálon tesztelheti úgy, hogy meghív egy olyan műveletet, amelynek szabályzata nevesített értékekkel rendelkezik a hatókörben. Az alábbi példában a rendszer meghív egy műveletet az előző két példaszabályzattal set-header nevesített értékekkel. Figyelje meg, hogy a válasz két egyéni fejlécet tartalmaz, amelyek nevesített értékekkel rendelkező szabályzatok használatával lettek konfigurálva.

API-válasz tesztelése

Ha egy olyan hívás kimenő API-nyomkövetését tekinti meg, amely tartalmazza a két korábbi, névvel ellátott mintaszabályzatot, láthatja a két set-header szabályzatot a beszúrt névvel ellátott értékekkel, valamint a szabályzatkifejezést tartalmazó névvel ellátott érték szabályzatkifejezés-kiértékelését.

API Inspector nyomkövetése

A sztring interpolációja névvel ellátott értékekkel is használható.

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

Az érték a CustomHeader következő lesz The URL encoded value is This+is+a+header+value.: .

Figyelemfelhívás

Ha egy szabályzat egy titkos kódra hivatkozik az Azure Key Vaultban, a kulcstartóból származó érték látható lesz azoknak a felhasználóknak, akik hozzáférnek az API-kérések nyomon követéséhez engedélyezett előfizetésekhez.

Bár a névvel ellátott értékek tartalmazhatnak szabályzatkifejezéseket, más elnevezett értékeket nem tartalmazhatnak. Ha névvel ellátott értékhivatkozást tartalmazó szöveget használ egy értékhez, például Text: {{MyProperty}}, a hivatkozás nem lesz feloldva és lecserélve.

Névvel ellátott érték törlése

Névvel ellátott érték törléséhez jelölje ki a nevet, majd válassza a Törlés lehetőséget a helyi menüből (...).

Fontos

Ha az elnevezett értékre bármely API Management-szabályzat hivatkozik, nem törölheti, amíg el nem távolítja az elnevezett értéket az azt használó összes szabályzatból.

Következő lépések