Dela via

Publicera Api:er för Microsoft Azure Data Manager för energi till en säker API-gateway

  • Artikel

Azure API Management fungerar som en viktig mellanhand mellan klientprogram och serverdels-API:er. Det gör det enklare för klienter att komma åt tjänster genom att dölja teknisk information och ge organisationer kontroll över API-säkerhet.

Genom att publicera Azure Data Manager for Energy-API:er via Azure API Management kan du använda Azure Data Manager for Energy Private Link-funktionen för privat trafik och helt ta bort direkt offentlig åtkomst till din instans.

Den här artikeln beskriver hur du konfigurerar Azure API Management för att skydda Azure Data Manager för energi-API:er.

Förutsättningar

Du behöver följande komponenter, verktyg och information för att slutföra den här genomgången:

  • Ett virtuellt nätverk med två tillgängliga undernät, ett för den privata slutpunkten Azure Data Manager for Energy och det andra för inmatning av virtuella Azure API Management-nätverk.

  • Azure Data Manager for Energy konfigurerat med privat länk distribuerad till undernätet.

  • Azure API Management har etablerats och distribuerats till det virtuella nätverket med hjälp av en virtuell nätverksinmatning. Välj Externt läge eller se avsnittet Andra alternativ för Internt läge.

  • En kodredigerare som Visual Studio Code för att ändra Azure Data Manager for Energy OpenAPI-specifikationerna för var och en av de API:er som publiceras.

  • Ladda ned Azure Data Manager for Energy OpenAPI-specifikationerna från GitHub-lagringsplatsen adme-samples . Gå till rest-apis-katalogen och välj lämplig version för ditt program.

  • Observera klient-ID:t och klient-ID:t från appregistreringen för Azure Data Manager for Energy-appen som användes vid etableringstillfället:

    Skärmbild av information om appregistreringar.

Förbereda API Management-instansen

Använd följande steg för att göra konfigurationsändringar i din Azure API Management-instans:

  1. I fönstret Alla resurser väljer du den Azure API Management-instans som används för den här genomgången.

  2. Gå till sidan Produktinställningar genom att välja den från gruppering av API-inställningar:

    Skärmbild av fliken Produkter på API Management-instansen.

  3. På sidan Produkter väljer du knappen Lägg till för att skapa en ny produkt. Med Azure API Management-produkter kan du skapa en löst kopplad gruppering av API:er som kan styras och hanteras tillsammans. Vi skapar en produkt för våra Azure Data Manager for Energy-API:er.

  4. På sidan Lägg till produkt anger du värden som beskrivs i följande tabell för att skapa produkten.

    Skärmbild av sidan Lägg till produkter på API Management-instansen.

    Inställning Värde
    Visningsnamn "Azure Data Manager for Energy Product"
    ID "adme-product"
    beskrivning Ange en beskrivning som anger för utvecklare vilka API:er vi grupperar
    Publicerad Markera den här kryssrutan om du vill publicera den produkt vi skapar
    Prenumeration krävs Markera den här kryssrutan om du vill ange grundläggande auktorisering för våra API:er
    Godkännande krävs Du kan också välja om du vill att en administratör ska granska och godkänna eller avvisa prenumerationsförsök till den här produkten. Om du inte har valt det godkänns prenumerationsförsök automatiskt.
    Antal tillåtna prenumerationer Du kan också begränsa antalet samtidiga prenumerationer.
    Juridiska villkor Alternativt kan du definiera användningsvillkor för den produkt som prenumeranter måste acceptera för att kunna använda produkten.
    API:er Vi kan ignorera den här funktionen. Vi associerar API:er senare i den här artikeln

  5. Välj Skapa för att skapa den nya produkten.

  6. När produktskapandet är klart returnerar portalen dig till sidan Produkter. Välj vår nyskapade produkt Azure Data Manager for Energy Product för att gå till sidan Produktresurs. Välj menyalternativet Principinställning på inställningsmenyn.

    Skärmbild av konfigurationssidan För produktprinciper på API Management-instansen.

  7. I fönstret Inkommande bearbetning väljer du <ikonen /> , som gör att du kan ändra principer för produkten. Du lägger till tre uppsättningar principer för att förbättra säkerheten för lösningen:

    • Verifiera entra-ID-token för att säkerställa att oautentiserade begäranden fångas på API-gatewayen
    • Kvot - och hastighetsgräns för att styra antalet begäranden och totalt antal begäranden/data som överförs
    • Ange Rubrik för att ta bort rubriker som returneras av API:er för serverdelen, vilket kan avslöja känslig information för potentiella dåliga aktörer

  8. Lägg till följande policy för valid-azure-ad-token i vår konfiguration inom de inkommande taggarna och under bastaggen. Se till att uppdatera mallen med information om Microsoft Entra-ID-appen som anges i förhandskraven.

    <validate-azure-ad-token tenant-id="INSERT_TENANT_ID">
    <client-application-ids>
        <application-id>INSERT_APP_ID</application-id>
    </client-application-ids>
</validate-azure-ad-token>

  9. Under policyn validate-azure-ad-token lägger du till följande kvot - och hastighetsbegränsningsprinciper . Uppdatera principkonfigurationsvärdena efter behov för dina konsumenter.

    <rate-limit calls="20" renewal-period="90" remaining-calls-variable-name="remainingCallsPerSubscription"/>
<quota calls="10000" bandwidth="40000" renewal-period="3600" />

  10. I avsnittet utgående i principredigeraren och under bastaggen lägger du till följande principer för set-header.

    <set-header name="x-envoy-upstream-service-time" exists-action="delete" />
<set-header name="x-internal-uri-pattern" exists-action="delete" />

  11. Välj Spara för att införa ändringarna.

    Skärmbild av det fullständiga principdokumentet.

  12. Gå tillbaka till API Management-resursen i Azure-portalen. Välj menyalternativet Serverdelar och välj knappen + Lägg till.

    Skärmbild av sidan Serverdelar.

  13. På serverdelsmodalen anger du värden som beskrivs i följande tabell för att skapa serverdelen.

    Inställning Värde
    Name "adme-backend"
    beskrivning Ange en beskrivning som anger för utvecklare att den här serverdelen är relaterad till Azure Data Manager for Energy-API:er
    Typ Anpassad URL
    Körnings-URL Ange din Azure Data Manager for Energy URI-_ex. https://INSERT_ADME_NAME.energy.azure.com/
    Verifiera certifikatkedjan Kontrollerad
    Verifiera certifikatnamnet Kontrollerad

    Skärmbild av serverdelsmodalen.

  14. Välj Skapa för att skapa serverdelen. Den här nyligen skapade serverdelen används i nästa avsnitt när vi publicerar API:er.

Importera Azure Data Manager för Energi-API:er

Använd följande steg för att importera, konfigurera och publicera Azure Data Manager for Energy-API:er till Azure API Management-gatewayen:

  1. Gå tillbaka till Azure API Management-instansen som användes i det sista avsnittet.

  2. Välj menyalternativet API:er på menyn och välj sedan knappen + Lägg till API .

  3. Välj OpenAPI under rubriken Skapa från definition .

    Skärmbild av OpenAPI-importskärmen.

  4. I fönstret Skapa från OpenAPI-specifikationsmodal väljer du växlingsknappen Fullständig .

  5. Leta upp OpenAPI-specifikationerna som du laddade ned som en del av förhandskraven och öppna schemaspecifikationen med valfri kodredigerare. Sök efter ordet "server" och anteckna server-URL:en i filen t.ex. /api/schema-service/v1/.

  6. Välj Välj en fil och välj schema-API-specifikationen. När uppladdningen är klar läser modal-fönstret in några värden från specifikationen.

  7. För de andra fälten anger du värden som beskrivs i följande tabell:

    Inställning Värde
    Inkludera obligatoriska frågeparametrar i åtgärdsmallar Kontrollerad
    Visningsnamn Ange ett visningsnamn som passar apputvecklare , till exempel Azure Data Manager för Energy Schema Service
    Name API Management föreslår ett kebab-cased namn. Alternativt kan namnet ändras men det måste vara unikt för instansen
    beskrivning OpenAPI-specifikationen kan definiera en beskrivning, i så fall fylls beskrivningen automatiskt i. Du kan också uppdatera beskrivningen per användningsfall.
    URL-schema Välj "Båda"
    API:ets webbadressuffix Ange ett suffix för alla Azure Data Manager for Energy-API:er (t.ex. adme). Ange sedan server-URL:en från steg 5. Det slutliga värdet bör se ut som /adme/api/schema-service/v1/. Med ett suffix kan vi vara kompatibla med befintliga klienter och programutvecklingspaket som normalt ansluter till Azure Data Manager för energi-API:er direkt
    Taggar Du kan också ange taggar
    Produkter Välj produkten "Azure Data Manager for Energy" som skapades i föregående avsnitt

    Viktigt!

    Verifiera API URL-suffixet, det här är en vanlig orsak till fel vid publicering av Azure Data Manager for Energy-API:er

  8. Välj Skapa för att skapa API-fasaden.

    Skärmbild av skärmen Skapa från OpenAPI-specifikation.

  9. Välj den nyligen skapade Schema API-fasaden i listan över API:er och välj på Alla åtgärder i driftlistan. I fönstret Inkommande bearbetning väljer du <ikonen /> för att redigera principdokumentet.

    Skärmbild av skärmen API-princip.

  10. Om du vill konfigurera API:et lägger du till två uppsättningar principer:

    • Ställ in Backend Service för att dirigera begäranden till Azure Data Manager for Energy-instansen
    • Skriv om URI :n för att ta bort adme-prefixet och skapa begäran till serverdels-API:et. Den här principuttrycket använder principuttryck för att dynamiskt lägga till värdet för den aktuella åtgärdens URL-mall till vår server-URL.

  11. Anteckna server-URL:en från steg 5. Under bastaggen i avsnittet inkommande infogar du följande två principinstruktioner.

    <set-backend-service backend-id="adme-backend" />

    <!-- replace the '/api/schema-service/v1' with the server URL for this API specification you noted in step 5 -->
<rewrite-uri template="@{return "/api/schema-service/v1"+context.Operation.UrlTemplate;}" />

  12. Välj Spara för att införa ändringarna.

  13. Testa API:et genom att välja åtgärden HÄMTA versionsinformation från åtgärdslistan. Välj sedan fliken Test för att navigera till Testkonsolen för Azure API Management.

  14. Ange värden som beskrivs i följande tabell. Generera en autentiseringstoken för Azure Data Manager for Energy. Välj Skicka för att testa API:et.

    Inställning Värde
    data-partition-id Datapartitions-ID:t för din Azure Data Manager for Energy-instans
    Produkt Välj den Azure Data Manager for Energy-produkt som skapades tidigare
    Auktorisering "Bearer" och den autentiseringstoken som du genererade

    Skärmbild av testkonsolen Skapa från API.

  15. Om API:et är korrekt konfigurerat bör du se ett HTTP 200 – OK-svar som ser ut ungefär som skärmbilden. Om inte kontrollerar du felsökningsavsnittet.

  16. Upprepa stegen ovan för varje Azure Data Manager för Energy API och tillhörande specifikation.

Felsökning

När du testar API:er via Azure API Management pekar de vanligtvis på konfigurationsproblem om du stöter på fel. Granska de potentiella lösningsstegen baserat på felet.

Kod Felmeddelande Details
HTTP 401 Unauthorized Invalid Azure AD JWT Kontrollera att du har ett giltigt autentiseringshuvud för Microsoft Entra ID-klient- och klientappen för din Azure Data Manager for Energy-instans.
HTTP 401 Unauthorized Azure AD JWT not present Kontrollera att autentiseringshuvudet har lagts till i testbegäran.
HTTP 404 Not Found Det här felet innebär vanligtvis att begäran till serverdels-API:et görs till fel URL. Spåra din API-begäran i API Management för att förstå vilken URL som genereras för serverdelsbegäran och se till att den är giltig. Annars dubbelkollar du url-omskrivningsprincipen eller serverdelen.
HTTP 500 Internal Server Error Internal server error Det här felet återspeglar vanligtvis ett problem med att göra begäranden till serverdels-API:et. I det här scenariot är problemet vanligtvis DNS-relaterade (Domain Name Services). Kontrollera att det finns en privat DNS-zon som har konfigurerats i ditt virtuella nätverk eller att din anpassade DNS-matchning har lämpliga vidarebefordrare. Spåra din API-begäran i API Management för att förstå vad serverdelsbegäran har gjorts och vilka fel SOM API Management rapporterar när du försöker göra begäran.

Övriga beaktanden

Internt virtuellt nätverksläge för API Management

Internt läge isolerar Helt Azure API Management i stället för att exponera slutpunkterna via offentlig IP-adress. I den här konfigurationen kan organisationer se till att alla Azure Data Manager for Energy är interna. Eftersom Azure Data Manager for Energy är en samarbetslösning för att arbeta med partner och kunder kanske det här scenariot inte är fördelaktigt som det är.

App Gateway med brandvägg för webbprogram

I stället för att använda internt virtuellt nätverksläge ensamt väljer många organisationer att använda en skyddad mekanism för omvänd proxy för att exponera Azure API Management-instansen för internt läge för externa partner och kunder. Den interna lägesinstansen förblir helt isolerad med en strikt kontrollerad ingress som måste gå igenom proxyn.

Azure App Gateway är en vanlig tjänst som ska användas som omvänd proxy. Azure App Gateway har också en waf-funktion (web application firewall), som aktivt identifierar potentiella attacker mot sårbarheter i dina program och API:er.

Konfigurera Azure API Management med en anpassad domän

En annan vanlig funktion i den här arkitekturen är att tillämpa en anpassad domän på API:erna. Även om Azure Data Manager for Energy inte stöder den här funktionen kan du konfigurera en anpassad domän i Azure API Management i stället.

Ett certifikat för domänen är en förutsättning. Azure API Management har dock stöd för att skapa kostnadsfria hanterade certifikat för din anpassade domän.

Relaterat innehåll