Azure API Management Gateway

Gateway (brána) v Azure API Management je komponent, ktorý funguje ako sprostredkovateľ medzi klientmi a backendovými službami. Jej hlavnou úlohou je prijať požiadavku od klienta, aplikovať definované pravidlá (napr. autentifikácia, limity, transformácie) a následne požiadavku smerovať do cieľovej služby.

K dispozícii sú dva hlavné typy gateway:

SaaS (hostovaná) Gateway – beží priamo v Azure ako súčasť služby API Management.
Self-hosted Gateway – kontajnerizovaná verzia gateway, ktorú si môžeš nasadiť v on-premise prostredí, v inej cloudovej platforme alebo v edge lokalitách. Umožňuje tak jednotné riadenie API aj mimo Azure.

Na čo slúži API Management Gateway?

Centralizované riadenie API – všetky volania API prechádzajú cez bránu, kde sa uplatňujú pravidlá definované v politike (policy).
Bezpečnosť – podpora OAuth 2.0, IP filtrácia, šifrované spojenie, validácia tokenov a ochrana proti zneužitiu.
Transformácia požiadaviek/odpovedí – možnosť prepísať hlavičky, URL cesty, formát tela požiadavky/odpovede (napr. z XML do JSON).
Rate limiting a throttling – ochrana backendu pred zahltením cez limity požiadaviek.
Monitoring a logging – integrované nástroje pre sledovanie používania API a identifikáciu problémov.
Verzionovanie a publikácia API – možnosť riadiť rôzne verzie API, publikovať testovacie a produkčné prostredia.

Kde sa Azure API Management hodí?

Organizácie s viacerými internými a externými API, ktoré potrebujú jednotný prístup a dohľad.
Firmy, ktoré potrebujú zabezpečiť komunikáciu medzi frontend aplikáciami a backend systémami.
Scenáre, kde sa kombinuje on-premise infraštruktúra s cloudovými službami.
Projekty s požiadavkou na API monetizáciu, monitoring alebo bezpečný prístup pre tretie strany.

Úvod do modernej správy API

V čase, keď aplikácie rastú na zložitosti a čoraz viac služieb komunikuje cez API rozhrania, stáva sa centrálne riadenie týchto rozhraní nevyhnutnosťou. Práve na tento účel slúži API Gateway – komponent, ktorý funguje ako jednotný vstupný bod pre všetky volania smerované do backendových služieb.

Na obrázku vyššie vidíme typický scenár využitia API Gateway:

Actor (používateľ alebo klientská aplikácia) zasiela požiadavky.
Požiadavky prechádzajú cez API GW (API Gateway) – táto brána najskôr zabezpečí autentifikáciu používateľa alebo aplikácie.
Po úspešnom overení identít API Gateway následne smeruje požiadavku na príslušný backend (napr. mikroservisu, databázu, REST API a pod.).

Ako nainštalovať a nakonfigurovať Azure API Gateway (API Management)

Krok 1 – Prihlásenie do Azure portálu

Ako prvý krok sa vyžaduje prihlásenie do portálu https://portal.azure.com.

Krok 2 – Vytvorenie novej služby API Management

Klikni na „Create a resource“ (vľavo hore).
Vyhľadajte API Management.
Kliknite na API Management a následne „Create“.

Krok 3 – Vyplnenie parametrov služby

Vo formulári sa vyplnia nasledovné polia:

Subscription – zvolí sa aktívne predplatné.
Resource group – vyberie sa existujúca skupina zdrojov alebo sa vytvorí nová (napr. api-gw-group).
Resource Name –zadá sa názov služby (napr. moja-api-gateway).
Region – vyberie sa preferovaný geografický región (napr. West Europe).
Organization name – uvedie sa názov organizácie alebo tímu.
Administrator email – zadá sa emailová adresa správcu, na ktorú budú zasielané notifikácie.

Po vyplnení údajov sa pokračuje kliknutím na Review + create a následne na Create, čím sa spustí nasadenie služby.

Sekcia Networking v Azure API Management – možnosti a nastavenie konektivity

Služba Azure API Management (APIM) ponúka viacero spôsobov, ako môže byť API Gateway sprístupnená klientskym aplikáciám – buď verejne prostredníctvom internetu, alebo súkromne len v rámci zabezpečeného sieťového prostredia. Výber režimu pripojenia má zásadný vplyv na bezpečnosť, architektúru a spôsob integrácie riešenia.

External (verejná konektivita)
- API Gateway je dostupná cez verejnú IP adresu – prístupná z internetu bez potreby špeciálneho sieťového pripojenia
- Použitie:
  - Webové/mobilné aplikácie bežiace mimo Azure
  - Externí partneri alebo zákazníci
  - Rýchle testovanie alebo vývoj
Internal (vnútorná konektivita – VNet Integration)
- Prístup len z Azure Virtual Network
  Gateway beží v privátnom režime – dostupná len pre zdroje v tej istej VNet alebo cez privátne pripojenie (napr. VPN, ExpressRoute).
- Použitie:
  - Systémy s citlivými dátami
  - Firemné API rozhrania neprístupné z verejného internetu
  - Hybridné scenáre (on-premise + cloud)
Hybridný model – kombinácia Public + VNet
- Niektoré časti API môžu byť verejné (napr. open API pre tretie strany), iné len pre interné systémy.
  Možné v režime Premium Tier, kde môžeš konfigurovať viaceré regionálne inštancie a zmiešanú konektivitu.
- Použitie:
  - Veľké organizácie s viacerými požiadavkami na prístup
  - API rozhrania pre verejnosť aj interné tímy

Krok 1: Vytvorenie Azure Virtual Network

Ak ešte nie je vytvorená Virtual Network, je potrebné ju zriadiť nasledovne:

V prostredí Azure Portal sa vyberie možnosť Create a resource.
Do vyhľadávacieho poľa sa zadá výraz Virtual Network a vyberie sa príslušná služba.
Sieť sa pomenuje (napr. apim-vnet).
V časti IP Addressing sa pridá adresný rozsah, napríklad 10.1.0.0/16.
V sekcii Subnets sa vytvorí subnet s názvom apim-subnet, napríklad 10.1.0.0/24.

Krok 2: Zriadenie verejnej IP adresy

Následne je potrebné vytvoriť verejnú IP adresu, ktorá bude slúžiť ako vstupný bod pre prichádzajúce požiadavky:

V Azure Portal sa opäť vyberie možnosť Create a resource.
Vyhľadá sa služba Public IP address.
IP adresa sa pomenuje (napr. apim-public-ip).
V časti SKU sa zvolí možnosť Standard (vyžadovaná pri integrácii s VNet).
V sekcii priradenia sa vyberie Static – IP adresa sa po vytvorení nebude meniť.

Táto verejná IP adresa bude neskôr priradená k službe API Management a bude slúžiť ako verejný prístupový bod pre klientov.

Krok 3: Priradenie VNet a verejnej IP k APIM

Po vytvorení siete a IP adresy sa konfigurácia dokončí nasledovne:

V Azure Portáli sa otvorí existujúca služba API Management (APIM).
V ľavom menu sa prejde do časti Network → Virtual Network → Configure.
Zvolí sa režim External.
Vyberie sa vytvorená sieť apim-vnet a subnet apim-subnet.
V sekcii Public IP address sa vyberie adresa apim-public-ip.
Zmeny sa potvrdia kliknutím na Apply.
Poznámka: Zmena môže trvať 15–45 minút.

Ako vytvoriť API v Azure API Management

Po nasadení API Gateway do Azure API Management (APIM) je ďalším krokom vytvorenie samotného API rozhrania, cez ktoré budú chodiť požiadavky od klientov a aplikácií. APIM umožňuje jednoducho vytvoriť nové API, alebo importovať už existujúce špecifikácie (napr. OpenAPI / Swagger / WSDL).

Možnosti ako vytvoriť API

V prostredí Azure API Management je možné API rozhranie vytvoriť niekoľkými spôsobmi:

Import existujúcej OpenAPI špecifikácie (Swagger)
Import SOAP služby na základe WSDL definície
Prepojenie s existujúcou službou v Azure App Service alebo Azure Functions
Vytvorenie prázdneho API (Blank API) a manuálne pridanie operácií

Krok 1: Otvor Azure API Management a prejdite do časti „APIs“

V Azure portáli sa otvorí vytvorená služba API Management.
V ľavom paneli navigácie sa klikne na položku „APIs“.
Pre pridanie nového API sa zvolí možnosť „+ Add API“ alebo „Create from scratch“, v závislosti od preferovaného spôsobu vytvorenia rozhrania.

Na obrázku vyššie je zobrazené rozhranie pre návrh a úpravu API v službe Azure API Management. Ide o priestor, v ktorom sa konfiguruje správanie API brány – vrátane spracovania vstupných požiadaviek, úprav odpovedí, definovania jednotlivých operácií a aplikovania politiky (policies). Pomocou tohto rozhrania je možné podrobne riadiť spôsob, akým sa spracúvajú požiadavky od klientov ešte pred ich odoslaním na backend, ako aj upraviť odpovede pred ich vrátením klientovi.

Rozhranie je rozdelené do štyroch hlavných sekcií (zľava doprava):

Navigačný panel (ľavá strana)
- Search APIs / operations – umožňuje vyhľadávať v zozname tvojich API alebo ich operácií.
- Add API – tlačidlo na pridanie nového API do služby.
- All APIs – zoznam všetkých API, ktoré máš vytvorené.
- V príklade je zobrazené Echo API – vzorové/testovacie API dostupné po inštalácii.
Frontend definícia operácie
- Zobrazuje detaily aktuálnej operácie, v tomto prípade:
  - GET /resource
  - Operácia má query parametre: param1 (string) a param2 (number)
- Odpoveď z operácie je indikovaná ako 200 OK (úspešná odpoveď).
- Tu sa definuje:
  - Metódu (GET, POST, atď.)
  - Cestu (/resource)
  - Parametre
  - Typ odpovede (napr. JSON, XML)
Inbound processing (vstupné spracovanie)
- Táto sekcia definuje, čo sa má stať so žiadosťou od klienta, predtým než sa pošle na backend.
- Tu sa definuje politika (policies) ako napríklad:
  - Overenie JWT tokenu (validate-jwt)
  - Limitovanie prístupov (rate-limit)
  - Úprava hlavičiek alebo URL (rewrite-uri, set-header)
- Na obrázku vidíme, že je tu pridaná základná politika označená ako base.
Backend sekcia
- Zobrazuje HTTP(S) endpoint, kam sa má požiadavka smerovať.
- V tomto prípade: http://echoapi.cloudapp.net/api
- To znamená, že požiadavky, ktoré prejdú cez gateway, sa posielajú na tento backend.
- V tejto časti môžu byť pridané politiky, napríklad na úpravu URL adresy alebo na zabezpečenie požiadaviek.
Outbound processing (výstupné spracovanie)
- Táto sekcia určuje, ako sa má upraviť odpoveď z backendu predtým, ako sa pošle klientovi.
- Príklady použitia:
  - Odstránenie alebo pridanie hlavičiek
  - Transformácia XML na JSON
  - Logovanie odpovedí
- Na obrázku je použitá základná politika base.

Vytvorenie nového HTTP API

Na obrázku vyššie vidíme formulár, ktorý sa zobrazí po kliknutí na „+ Add API“ a následne výbere možnosti HTTP API. Tento formulár slúži na základné nastavenie nového API rozhrania, ktoré bude sprístupnené cez API Gateway.

Nižšie sú uvedené vysvetlenia jednotlivých polí:

Display name:
- Viditeľný názov API, ktorý sa zobrazí v rozhraní APIM.
- Môže byť akýkoľvek – v tomto prípade:
  - Returns the requester’s IP Address
Name:
- Interný identifikátor API – používa sa v URL a v systémových záznamoch.
- Automaticky sa generuje z názvu, ale môžete ho upraviť (napr. bez medzier, malé písmená).
- V príklade:
  - returns-the-requester-s-ip-address
Description:
- Krátky popis API – nepovinné, ale odporúčané pre prehľadnosť.
- Tu slúži na vysvetlenie účelu:
  - Returns the requester’s IP Address
Web service URL:
- Najdôležitejšie pole – sem zadávate reálnu URL adresu backendovej služby, kam má byť požiadavka smerovaná.
- V tomto prípade ide o verejne dostupné testovacie API:
  - https://httpbin.org
URL scheme:
- Vyberáš, či bude API fungovať cez HTTP, HTTPS, alebo oboje.
- Odporúčané je používať len HTTPS pre zabezpečenú komunikáciu.
API URL suffix:
- Sufix, ktorý sa pripojí k doméne APIM – tvorí finálnu adresu API.
- Napr. ak zvolíš ip, výsledný endpoint bude:
  - https://mhi...api.azure-api.net/ip
Base URL (automaticky vygenerované):
- Základná adresa tvojej API Management brány – nedá sa upravovať.
- V tomto prípade:
  - https://mhi...azure-api.net
Tags:
- Nepovinné pole – slúži na kategorizáciu a filtrovanie API.
- Užitočné pri veľkom počte API (napr. internal, external, booking, atď.)
Products:
- API musí byť pridelené aspoň jednému produktu, inak nebude publikované.
- Produkt je „balík“ API, ktorý sa poskytuje používateľom (napr. Free Tier, Premium APIs).

Pridanie operácie: GET `/ip` – návrh požiadavky a odpovede

Na obrázku vyššie vidíme obrazovku, kde práve prebieha konfigurácia konkrétnej API operácie typu GET. Táto operácia sa volá Returns the requester's IP Address a bude slúžiť na získanie IP adresy volajúceho klienta. Táto požiadavka bude presmerovaná na testovaciu službu https://httpbin.org/ip.

Display name:
- Interný identifikátor operácie – bez medzier a diakritiky.
- Používa sa v interných API exportoch a systémových volaniach.
- V príklade:
  - returns-the-requester-s-ip-address
URL:
- Tu je možné definovať:
  - Metódu: GET
  - Cestu: /ip
- Kombináciou API suffixu a tejto cesty vznikne finálny endpoint, napríklad:
  - https://<tvoje-apim>.azure-api.net/ip
Sekcia Responses:
- V tejto časti sa definujú očakávané odpovede od backendu, ktoré sú spracovávané bránou (gateway).
- V tomto prípade je zadefinovaná odpoveď:
  - Status code: 200 OK
  - Popis (vpravo) – zatiaľ prázdny, ale môže obsahovať JSON príklad odpovede, schému alebo poznámky.

Ako otestovať API cez cURL príkaz

Po vytvorení a nasadení API v službe Azure API Management je vhodné vykonať testovanie mimo portálu – napríklad prostredníctvom príkazového riadku pomocou nástroja cURL.

V predvolenom nastavení Azure API Management vyžaduje, aby každá požiadavka bola autorizovaná pomocou tzv. subscription key. Tento kľúč sa pridáva buď vo forme HTTP hlavičky (Ocp-Apim-Subscription-Key), alebo ako parameter priamo v URL (?subscription-key=...).

Ak je však anonymný prístup povolený, API je možné testovať aj bez použitia subscription key. Tento režim sa využíva najmä pre verejne dostupné API rozhrania alebo na účely testovania.

Zapnutie overovania pomocou subscription key

Azure API Management umožňuje viacero spôsobov overovania požiadaviek, ktoré smerujú na publikované API. Výber konkrétnej metódy závisí od požiadaviek na bezpečnosť, typ klienta, ako aj účel samotného API (verejné vs. interné). Overovanie zabezpečuje, že API môže volať len oprávnený používateľ alebo aplikácia.

Subscription key (predvolená metóda) – Každé API je možné zabezpečiť pomocou tzv. subscription key, ktorý sa vkladá do požiadavky:

buď do HTTP hlavičky:
- Ocp-Apim-Subscription-Key: <key>
alebo ako parameter v URL:
- ?subscription-key=

Subscription key v službe Azure API Management je bezpečnostný token, ktorý slúži na identifikáciu a autorizáciu klientov pristupujúcich k publikovaným API rozhraniam. Ide o jednoduchý, ale efektívny spôsob zabezpečenia API pred neautorizovaným prístupom. Subscription key má podobu náhodne generovaného reťazca, zvyčajne dlhého 32 až 40 znakov, napríklad 1a2b3c4d5e6f7g8h9i0jklmnopqrstuv, a neobsahuje žiadne špeciálne znaky.

Každý kľúč je viazaný na konkrétnu subscription (predplatné), ktoré patrí k vybranému produktu v rámci služby APIM. Pre každé subscription sa automaticky generujú dva kľúče – primárny a sekundárny, pričom ich platnosť je rovnaká a môžu byť kedykoľvek obnovené (regenerované). Okrem autorizácie požiadaviek umožňuje subscription key aj sledovanie spotreby, aplikovanie kvót, obmedzení rýchlosti (rate limiting) a evidenciu prístupu podľa používateľov alebo aplikácií. V prostredí s viacerými klientmi alebo partnermi poskytuje efektívny spôsob správy a zabezpečenia prístupu k rozhraní bez nutnosti zložitej autentifikačnej logiky.

Martin Hasin

CEO at mhite S.R.O. | martin.hasin@gmail.com | Website | + posts

Odborník na kybernetickú bezpečnosť, správu Azure Cloud a VMware onprem. Využíva technológie, ako Checkmk a MRTG, na monitorovanie siete a zvyšovanie efektívnosti a bezpečnosti IT infraštruktúry. Kontakt: hasin(at)mhite.sk