Abonnementen maken in Azure API Management

VAN TOEPASSING OP: Alle niveaus van API Management

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 eenvoudig API-toegang 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:

• OAuth2.0
• Clientcertificaten
• Ip-adressen van bellers beperken

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 gebruikmaakt van de service kan overschakelen van sleutel A naar sleutel B en sleutel A opnieuw genereren met minimale onderbrekingen en vice versa.

In plaats van sleutels opnieuw te genereren, kunt u specifieke sleutels instellen door het Azure API Management-abonnement aan te roepen: Azure REST API maken of bijwerken. Stel properties.primaryKey en/of properties.secondaryKey in het HTTP-aanvraaglichaam in.

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.
• Om tijdgebonden toegang tot API's af te dwingen, 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

U kunt abonnementen koppelen aan verschillende bereiken: product, alle API's of een afzonderlijke API.

Abonnementen voor een product

Normaal gesproken koppelt u abonnementen in API Management aan één productbereik . Ontwikkelaars:

• Zoek de lijst met producten in de ontwikkelaarsportal.
• Verzend abonnementsaanvragen voor de producten die ze willen gebruiken.
• Open de API's in het product met behulp van de sleutels in die abonnementen die automatisch of door API-uitgevers worden goedgekeurd.

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

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

Met het allesomvattend abonnement heeft u toegang tot elke API in de API Management-instance. Alleen geautoriseerde gebruikers moeten dit abonnement gebruiken. 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 zoals 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.

Notitie

U kunt geen abonnementen in API Management rechtstreeks toewijzen aan Microsoft Entra ID-beveiligingsgroepen. Als u abonnementstoegang wilt bieden aan meerdere gebruikers in een groep, maakt u een zelfstandig abonnement en distribueert u de abonnementssleutels naar groepsleden of integreert u met Microsoft Entra-id voor verificatie en gebruikt u beleid om API-toegang te beheren op basis van groepslidmaatschap.

Abonnementen maken en beheren in Azure Portal

API-uitgevers (beheerders of ontwikkelaars met de juiste machtigingen) kunnen rechtstreeks in Azure Portal abonnementen maken door zich aan te melden bij hun API Management-exemplaar. API-gebruikers kunnen geen abonnementen maken via Azure Portal; ze vragen doorgaans abonnementen aan via de ontwikkelaarsportal of ontvangen ze van API-uitgevers.

Wanneer u een abonnement in de portal maakt, heeft dit de status Actief . Dit 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

Abonnees kunnen een API Management-abonnementssleutel op twee manieren 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 op het tabblad Instellingen van een API in de portal.

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 deze gegevens gevoelig zijn, 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. Als u een product maakt, is standaard een abonnementssleutel vereist voor toegang tot elke API die u aan het product toevoegt. 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

Wees voorzichtig bij het configureren van een product of API waarvoor geen abonnement is vereist. Deze configuratie is mogelijk te permissief en kan een API kwetsbaarder maken voor bepaalde API-beveiligingsrisico's.

Notitie

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

U kunt de abonnementsvereiste uitschakelen wanneer u een API of product maakt of later.

Als u de abonnementsvereiste wilt uitschakelen met behulp van de portal:

• Uitschakelen van abonnementvereiste voor product - Schakel op de Instellingen pagina van het product de optie 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 de sleutel geldig is en is gekoppeld aan een actief abonnement, gedefinieerd als:

   • Een abonnement dat is gericht op de API.
   • Een abonnement dat is gericht op een product dat is toegewezen aan de API.
   • Een abonnement dat is gericht op alle API's.
   • Het service-gebaseerde abonnement (onderdeel van het allesomvattende toegangsabonnement).

   Als de sleutel geldig is voor een actief abonnement binnen een geschikt bereik, verleent API Management toegang. Het past beleidsregels toe, afhankelijk van de configuratie van de beleidsdefinitie binnen dat bereik.

2. Als de sleutel niet geldig is, maar er een product bestaat dat de API bevat zonder een abonnement (een open product), negeert API Management de sleutel en verwerkt de aanvraag als een API-aanvraag zonder een abonnementssleutel (zie de volgende sectie).

3. Anders weigert API Management de toegang (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. Er wordt gecontroleerd op het bestaan van een product dat de API bevat, maar er is geen abonnement (een open product) vereist. Als het geopende product bestaat, verwerkt API Management de aanvraag in de context van de API's, beleidsregels en toegangsregels die zijn geconfigureerd voor het open product. Een API kan aan maximaal één open product worden gekoppeld.
2. Als een open product met inbegrip van de API niet wordt gevonden, controleert API Management of de API een abonnement vereist. Als een abonnement niet vereist is, verwerkt API Management de aanvraag in de context van die API en bewerking.
3. Als er geen geconfigureerd product of API wordt gevonden, weigert API Management de toegang (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. In de tabel worden configuraties weergegeven die onbedoelde, anonieme API-toegang mogelijk kunnen maken.

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: • Productgebaseerde sleutel • Api-scoped sleutel • Alle API-gerichte sleutel • Servicespecifieke sleutel Toegang geweigerd: • Andere sleutel die niet is afgestemd op het toepasselijke product of de API	Toegang geweigerd	Beveiligde API-toegang via een productgerichte of API-gerichte abonnement.
✔️	❌	Toegang toegestaan: • Productgebaseerde sleutel • Api-scoped sleutel • Alle API-gerichte sleutel • Servicespecifieke sleutel • Andere sleutel die niet is afgestemd op het toepasselijke product of de API	Toegang toegestaan (API-context)	• Beveiligde API-toegang met een productgerichte abonnementsvorm • 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: • Productgebaseerde sleutel • Api-scoped sleutel • Alle API-gerichte sleutel • Servicespecifieke sleutel Toegang geweigerd: • Andere sleutel die niet is afgestemd op het toepasselijke product of de API	Toegang toegestaan (productcontext openen)	• Beveiligde API-toegang met abonnement met API-bereik • Anonieme toegang tot API. Als anonieme toegang niet is bedoeld, configureert u met productbeleid om verificatie en autorisatie af te dwingen
❌ 1	❌	Toegang toegestaan: • Productgebaseerde sleutel • Api-scoped sleutel • Alle API-gerichte sleutel • Servicespecifieke sleutel • 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

¹ 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.
• Als voor een API geen abonnementsverificatie is vereist, wordt een API-aanvraag met een abonnementssleutel hetzelfde behandeld als een aanvraag zonder abonnementssleutel. De abonnementssleutel wordt genegeerd.
• API-toegang 'context' betekent het beleid en toegangscontroles die worden toegepast op een bepaalde reikwijdte (bijvoorbeeld API of product).

Verwante inhoud

Meer informatie over API Management:

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