Een API aanroepen met een abonnementssleutel
Wanneer u een API publiceert, wilt u vaak een bepaald niveau van controle hebben over wie toegang heeft tot de API via de gateway. Abonnementssleutels zijn een manier om de toegang tot een API te beperken.
Hier leert u hoe u abonnementssleutels gebruikt om uw API's te beveiligen.
Abonnementen en sleutels
U kunt u een abonnementssleutel gebruiken om uw API's te beschermen.
Notitie
In productie-API Management-omgevingen combineert u doorgaans een abonnementssleutel met andere mechanismen om uw API's te beschermen tegen onbevoegd gebruik, zoals certificaatverificatie of OAuth 2.0-autorisatie. Deze vallen buiten het bereik van deze module.
Een abonnementssleutel is een unieke automatisch gegenereerde tekenreeks, die wordt doorgegeven in de headers van de clientaanvraag of als een querytekenreeks in de URL. De sleutel is rechtstreeks gerelateerd aan een abonnement, dat kan worden afgestemd op verschillende gebieden, waardoor gedetailleerde controle wordt gegeven over machtigingen en beleidsregels. De belangrijkste abonnementsbereiken zijn:
- Alle API’s
- Eén API
- Een product
Een toepassing die een beveiligde API aanroept, moet de sleutel in de aanvraag bevatten.
U kunt deze abonnementssleutels op elk gewenst moment opnieuw genereren. Genereer bijvoorbeeld abonnementssleutels opnieuw als u vermoedt dat een sleutel is gedeeld met onbevoegde gebruikers.
Elk abonnement heeft twee sleutels, een primaire en een secundaire. Als u twee sleutels hebt, is het eenvoudiger wanneer u een sleutel opnieuw moet genereren. Als u bijvoorbeeld de primaire sleutel wilt wijzigen en downtime wilt voorkomen, gebruikt u de secundaire sleutel in uw apps.
Voor producten waarvoor abonnementen zijn ingeschakeld, moet u een sleutel opgeven bij het aanroepen van API's voor dat product. Als ontwikkelaar kunt u een sleutel verkrijgen door een abonnementsaanvraag te verzenden. Dit proces is een belangrijk onderdeel van de API Management-werkstroom.
Notitie
Nieuwe gebruikers maken en hun abonnementssleutels geven zodat ze toegang hebben tot de API, is een belangrijk onderdeel van de API Management-werkstroom, maar valt buiten het bereik van deze module.
Een API aanroepen met een abonnementssleutel
Toepassingen moeten een geldige sleutel bevatten in alle HTTP-aanvragen wanneer ze aanroepen doen naar API-eindpunten die worden beveiligd door een abonnement. Sleutels kunnen worden doorgegeven in de header van de aanvraag of als een queryreeks in de URL.
De standaard headernaam is Ocp-Apim-Subscription-Key en de standaard queryreeks is subscription-key.
Als u uw API-aanroepen wilt testen, kunt u de ontwikkelaarsportal gebruiken (als deze beschikbaar is in uw servicelaag), een opdrachtregelprogramma zoals curl of andere REST-clienthulpprogramma's.
Hier volgt een voorbeeld van een GET-aanvraag die een sleutel in de aanvraagheader doorgeeft met behulp van de curl-opdracht :
curl --header "Ocp-Apim-Subscription-Key: <key string>" https://<apim gateway>.azure-api.net/api/path
Hier is een voorbeeld van een cURL-opdracht die een sleutel in de URL doorgeeft als een queryreeks:
curl https://<apim gateway>.azure-api.net/api/path?subscription-key=<key string>
Als de sleutel niet wordt doorgegeven in de header of als een querytekenreeks in de URL, krijgt u een antwoord van 401 Toegang geweigerd van de API-gateway.