Abonnementen maken in Azure API Management

  • Artikel

VAN TOEPASSING OP: Alle API Management-lagen

In Azure API Management zijn abonnementen de meest voorkomende manier voor API-gebruikers om toegang te krijgen tot API's die zijn gepubliceerd via een API Management-exemplaar. Dit artikel bevat een overzicht van het concept.

Notitie

Een API Management-abonnement wordt specifiek gebruikt om API's aan te roepen via API Management met behulp van een abonnementssleutel. Dit is niet hetzelfde als een Azure-abonnement.

Wat zijn abonnementen?

Door API's te publiceren via API Management, kunt u API-toegang eenvoudig beveiligen met behulp van abonnementssleutels. Ontwikkelaars die de gepubliceerde API's moeten gebruiken, moeten een geldige abonnementssleutel in HTTP-aanvragen opnemen wanneer ze deze API's aanroepen. Zonder een geldige abonnementssleutel worden de aanroepen:

  • Onmiddellijk geweigerd door de API Management-gateway.
  • Niet doorgestuurd naar de back-endservices.

Ontwikkelaars hebben een abonnement en abonnementssleutel nodig om toegang te krijgen tot API's. Een abonnement is een benoemde container voor een paar abonnementssleutels.

Bovendien

  • Ontwikkelaars kunnen abonnementen verkrijgen zonder goedkeuring van API-uitgevers.
  • API-uitgevers kunnen rechtstreeks abonnementen maken voor API-consumenten.

Tip

API Management biedt ook ondersteuning voor andere mechanismen voor het beveiligen van toegang tot API's, waaronder de volgende voorbeelden:

Abonnementssleutels beheren

Het regelmatig regenereren van sleutels is een algemene voorzorgsmaatregel voor beveiliging. Net als bij de meeste Azure-services waarvoor een abonnementssleutel is vereist, genereert API Management sleutels in paren. Elke toepassing die de service gebruikt, kan overschakelen van sleutel A naar sleutel B en sleutel A opnieuw genereren met minimale onderbreking en omgekeerd.

Het instellen van specifieke sleutels in plaats van het opnieuw genereren van sleutels kan worden uitgevoerd door het Azure API Management-abonnement aan te roepen: Azure REST API maken of bijwerken. Met name de properties.primaryKey en/of properties.secondaryKey moeten worden ingesteld in de hoofdtekst van de HTTP-aanvraag.

Notitie

  • API Management biedt geen ingebouwde functies voor het beheren van de levenscyclus van abonnementssleutels, zoals het instellen van vervaldatums of het automatisch roteren van sleutels. U kunt werkstromen ontwikkelen om deze processen te automatiseren met behulp van hulpprogramma's zoals Azure PowerShell of de Azure SDK's.
  • Als u tijdgebonden toegang tot API's wilt afdwingen, kunnen API-uitgevers mogelijk beleidsregels gebruiken met abonnementssleutels of een mechanisme gebruiken dat ingebouwde vervaldatum biedt, zoals verificatie op basis van tokens.

Bereik van abonnementen

Abonnementen kunnen worden gekoppeld aan verschillende bereiken: product, alle API's of een afzonderlijke API.

Abonnementen voor een product

Van oudsher werden abonnementen in API Management gekoppeld aan één productbereik . Ontwikkelaars:

  • De lijst met producten in de ontwikkelaarsportal gevonden.
  • Ingediende abonnementsaanvragen voor de producten die ze wilden gebruiken.
  • Gebruik de sleutels in deze abonnementen (automatisch of door API-uitgevers goedgekeurd) voor toegang tot alle API's in het product.

Op dit moment worden in de ontwikkelaarsportal alleen de abonnementen voor het productbereik weergegeven in de sectie Gebruikersprofiel .

Productabonnementen

Abonnementen voor alle API's of een afzonderlijke API

U kunt ook sleutels maken die toegang verlenen tot:

  • Eén API, of
  • Alle API's binnen een API Management-exemplaar.

In dergelijke gevallen hoeft u geen product te maken en eerst API's eraan toe te voegen.

Abonnement voor alle toegang

Elk API Management-exemplaar wordt geleverd met een ingebouwd abonnement voor alle toegang dat toegang verleent tot alle API's. Dit abonnement op servicebereik maakt het eenvoudig voor service-eigenaren om API's in de testconsole te testen en fouten op te sporen.

Waarschuwing

Het abonnement voor alle toegang maakt toegang tot elke API in het API Management-exemplaar mogelijk en mag alleen worden gebruikt door geautoriseerde gebruikers. Gebruik dit abonnement nooit voor routine-API-toegang of sluit de abonnementssleutel voor alle toegang in client-apps in.

Notitie

Als u een abonnement met API-bereik, een abonnement met alle API's of het ingebouwde abonnement voor alle toegang gebruikt, worden beleidsregels die zijn geconfigureerd op het productbereik, niet toegepast op aanvragen van dat abonnement.

Zelfstandige abonnementen

API Management staat ook zelfstandige abonnementen toe, die niet zijn gekoppeld aan een ontwikkelaarsaccount. Deze functie is handig in scenario's die vergelijkbaar zijn met verschillende ontwikkelaars of teams die een abonnement delen.

Als u een abonnement maakt zonder een eigenaar toe te wijzen, wordt het een zelfstandig abonnement. Als u ontwikkelaars en de rest van uw team toegang wilt verlenen tot de zelfstandige abonnementssleutel, kunt u het volgende doen:

  • Deel de abonnementssleutel handmatig.
  • Gebruik een aangepast systeem om de abonnementssleutel beschikbaar te maken voor uw team.

Abonnementen maken en beheren in Azure Portal

API-uitgevers kunnen rechtstreeks abonnementen maken in Azure Portal.

Wanneer u een abonnement in de portal maakt, heeft een abonnement de status Actief , wat betekent dat een abonnee een gekoppelde API kan aanroepen met behulp van een geldige abonnementssleutel. U kunt de status van het abonnement zo nodig wijzigen. U kunt bijvoorbeeld een abonnement onderbreken, annuleren of verwijderen (inclusief het ingebouwde abonnement voor alle toegang) om API-toegang te voorkomen.

Een abonnementssleutel gebruiken

Een abonnee kan op twee manieren een API Management-abonnementssleutel gebruiken:

  • Voeg de HTTP-header Ocp-Apim-Subscription-Key toe aan de aanvraag, waarbij de waarde van een geldige abonnementssleutel wordt doorgegeven.

  • Neem de queryparameter voor de abonnementssleutel en een geldige waarde op in de URL. De queryparameter wordt alleen gecontroleerd als de header niet aanwezig is.

Tip

Ocp-Apim-Subscription-Key is de standaardnaam van de header van de abonnementssleutel en de abonnementssleutel is de standaardnaam van de queryparameter. Desgewenst kunt u deze namen wijzigen in de instellingen voor elke API. Werk deze namen bijvoorbeeld bij in de portal op het tabblad Instellingen van een API.

Notitie

Wanneer de abonnementssleutel is opgenomen in een aanvraagheader of queryparameter, wordt de abonnementssleutel standaard doorgegeven aan de back-end en kan deze worden weergegeven in back-endbewakingslogboeken of andere systemen. Als dit wordt beschouwd als gevoelige gegevens, kunt u een beleid aan het einde van de inbound sectie configureren om de header van de abonnementssleutel () of queryparameter (set-headerset-query-parameter) te verwijderen.

Abonnementsvereiste voor API- of producttoegang in- of uitschakelen

Wanneer u een API maakt, is standaard een abonnementssleutel vereist voor API-toegang. Wanneer u een product maakt, is standaard een abonnementssleutel vereist voor toegang tot elke API die aan het product wordt toegevoegd. In bepaalde scenario's wil een API-uitgever mogelijk een product of een bepaalde API publiceren naar het publiek zonder dat er abonnementen nodig zijn. Hoewel een uitgever ervoor kan kiezen om onbeveiligde (anonieme) toegang tot bepaalde API's in te schakelen, wordt het configureren van een ander mechanisme voor het beveiligen van clienttoegang aanbevolen.

Let op

Zorg ervoor dat u een product of API configureert waarvoor geen abonnement is vereist. Deze configuratie is mogelijk te slecht en kan een API kwetsbaarder maken voor bepaalde API-beveiligingsrisico's.

Notitie

Voor open producten is de abonnementsinstelling Vereist uitgeschakeld, wat betekent dat gebruikers zich er niet op hoeven te abonneren. Open producten worden daarom niet weergegeven op de pagina Producten van de ontwikkelaarsportal.

U kunt de abonnementsvereiste uitschakelen op het moment dat u een API of product maakt, of op een latere datum.

De abonnementsvereiste uitschakelen met behulp van de portal:

  • Vereiste voor product uitschakelen - Schakel op de pagina Instellingen van het product het abonnement Vereist uit
  • Vereiste voor API uitschakelen: schakel op de pagina Instellingen van de API het vereiste abonnement uit.

Nadat de abonnementsvereiste is uitgeschakeld, kunnen de geselecteerde API's of API's zonder abonnementssleutel worden geopend.

Hoe API Management aanvragen verwerkt met of zonder abonnementssleutels

API-aanvraag met een abonnementssleutel

Wanneer in API Management een API-aanvraag wordt ontvangen van een client met een abonnementssleutel, wordt de aanvraag verwerkt volgens deze regels:

  1. Er wordt gecontroleerd of er een geldige sleutel is gekoppeld aan een actief abonnement met een van de volgende bereiken:

    • Een abonnement op de API
    • Een abonnement op een product dat is toegewezen aan de API
    • Een abonnement op alle API's
    • Het serviceabonnement (ingebouwd abonnement voor volledige toegang)

    Als er een geldige sleutel voor een actief abonnement met een geschikt bereik wordt opgegeven, wordt de toegang toegestaan. Beleidsregels worden toegepast op basis van de configuratie van de beleidsdefinitie voor dat bereik.

  2. Anders wordt de toegang geweigerd (fout 401 Toegang geweigerd).

API-aanvraag zonder een abonnementssleutel

Wanneer in API Management een API-aanvraag wordt ontvangen van een client zonder een abonnementssleutel, wordt de aanvraag verwerkt volgens deze regels:

  1. Controleer eerst of er een product bestaat dat de API bevat, maar waarvoor geen abonnement is vereist (een open product). Als het open product bestaat, verwerkt u de aanvraag in de context van de API's, beleidsregels en toegangsregels die voor het product zijn geconfigureerd. Een API kan aan maximaal één open product worden gekoppeld.
  2. Als er geen open product met de API wordt gevonden, controleert u of voor de API een abonnement vereist is. Als een abonnement niet vereist is, verwerkt u de aanvraag in de context van die API en bewerking.
  3. Als er geen geconfigureerd product of API wordt gevonden, wordt de toegang geweigerd (fout 401 Toegang geweigerd).

Samenvattingstabel

De volgende tabel bevat een overzicht van hoe de gateway API-aanvragen verwerkt met of zonder abonnementssleutels in verschillende scenario's. Configuraties die onbedoelde, anonieme API-toegang kunnen inschakelen, worden genoteerd.

Alle producten die zijn toegewezen aan DE API vereisen een abonnement Api vereist een abonnement API-aanroep met abonnementssleutel API-aanroep zonder abonnementssleutel Typische scenario's
✔️ ✔️ Toegang toegestaan:

• Productbereikcode
• Api-scoped sleutel
• Alle API's-scoped sleutel
• Sleutel voor servicebereik

Toegang geweigerd:

• Andere sleutel die niet is afgestemd op het toepasselijke product of de API		 Toegang geweigerd Beveiligde API-toegang met behulp van een abonnement op productbereik of API-bereik
✔️ ❌ Toegang toegestaan:

• Productbereikcode
• Api-scoped sleutel
• Alle API's-scoped sleutel
• Sleutel voor servicebereik

Toegang geweigerd:

• Andere sleutel die niet is afgestemd op het toepasselijke product of de API		 Toegang toegestaan (API-context) • Beveiligde API-toegang met een abonnement op productbereik

• Anonieme toegang tot API. Als anonieme toegang niet is bedoeld, configureert u beleid op API-niveau om verificatie en autorisatie af te dwingen.
❌1 ✔️ Toegang toegestaan:

• Productbereikcode
• Api-scoped sleutel
• Alle API's-scoped sleutel
• Sleutel voor servicebereik

Toegang geweigerd:

• Andere sleutel die niet is afgestemd op het toepasselijke product of de API		 Toegang toegestaan (productcontext openen) • Beveiligde API-toegang met api-bereikabonnement

• Anonieme toegang tot API. Als anonieme toegang niet is bedoeld, configureert u met productbeleid om verificatie en autorisatie af te dwingen
❌1 ❌ Toegang toegestaan:

• Productbereikcode
• Api-scoped sleutel
• Alle API's-scoped sleutel
• Sleutel voor servicebereik

Toegang geweigerd:

• Andere sleutel die niet is afgestemd op het toepasselijke product of de API		 Toegang toegestaan (productcontext openen) Anonieme toegang tot API. Als anonieme toegang niet is bedoeld, configureert u met productbeleid om verificatie en autorisatie af te dwingen

1 Er bestaat een geopend product dat is gekoppeld aan de API.

Overwegingen

  • API-toegang in een productcontext is hetzelfde, ongeacht of het product is gepubliceerd of niet. Als u de publicatie van het product ongedaan maakt, wordt het verborgen in de ontwikkelaarsportal, maar worden nieuwe of bestaande abonnementssleutels niet ongeldig gemaakt.
  • Zelfs als een product of API geen abonnement vereist, kan een geldige sleutel van een actief abonnement waarmee toegang tot het product of de API nog steeds kan worden gebruikt.
  • API-toegang 'context' betekent het beleid en de besturingselementen voor toegang die worden toegepast op een bepaald bereik (bijvoorbeeld API of product).

Volgende stappen

Meer informatie over API Management:

  • Meer informatie over hoe API Management-beleid wordt toegepast op verschillende bereiken.
  • Meer informatie over andere concepten in API Management.
  • Volg onze zelfstudies voor meer informatie over API Management.
  • Raadpleeg onze pagina Veelgestelde vragen voor veelgestelde vragen.