Créer des abonnements dans Gestion des API Azure
Quand vous publiez une API avec Gestion des API, vous définissez qui peut accéder à l’API via la passerelle.
Pour votre application météorologique, vous voulez garantir que seuls les clients qui sont abonnés à votre service peuvent accéder à l’API et utiliser vos données de prévision. Pour obtenir ce contrôle d’accès, vous devez émettre des clés d’abonnement.
Important
Dans ce contexte, les abonnements ne sont pas liés aux abonnements Azure utilisés pour gérer votre compte Azure.
Ici, vous allez découvrir comment utiliser des clés d’abonnement pour sécuriser vos API.
Abonnements et clés
Vous pouvez choisir de rendre vos API et les informations qu’elles contiennent disponibles gratuitement. Mais en règle générale, vous souhaitez restreindre l’accès aux utilisateurs qui ont payé ou aux organisations avec lesquelles vous entretenez une relation de travail. Une façon de contrôler l’accès à vos API est d’utiliser des abonnements. Les abonnements sont utilisés pour segmenter les accès des utilisateurs à une API.
Les clés d’abonnement forment l’autorisation permettant d’accéder à ces abonnements. Chaque fois qu’un client envoie une demande à une API protégée, une clé d’abonnement valide doit être ajoutée à la requête HTTP, sinon l’appel est rejeté.
Une clé d’abonnement est une clé unique générée automatiquement qui peut être passée dans le cadre d’un appel d’API. La clé est directement liée à un abonnement, qui peut être limité à différentes zones. Les abonnements vous offrent un moyen de contrôle granulaire sur les autorisations et les stratégies.
Les trois étendues principales des abonnements sont :
| Étendue | Détails |
|---|---|
| Toutes les API | S’applique à toutes les API accessibles à partir de la passerelle. |
| API unique | S’applique à une seule API importée et tous ses points de terminaison. |
| Produit | Un produit est une collection contenant une ou plusieurs API que vous configurez dans Gestion des API. Vous pouvez affecter des API à plusieurs produits. Les produits peuvent avoir des règles d’accès, des quotas d’utilisation et des conditions d’utilisation différents. Par conséquent, si vous voulez que vos partenaires et fournisseurs aient des droits d’accès différents à votre API WeatherData, attribuez l’API à un produit, puis utilisez le portail Azure pour associer des API à un produit. |
Les applications qui appellent une API protégée doivent ajouter la clé dans chaque demande.
Vous pouvez regénérer ces clés d’abonnement à tout moment, par exemple, si vous pensez qu’une clé a été partagée avec des utilisateurs non autorisés, vous pouvez en créer une autre.
Chaque abonnement a deux clés : une clé primaire et une clé secondaire. Le fait d’avoir deux clés facilite la regénération d’une clé quand c’est nécessaire. Par exemple, si vous voulez changer la clé principale et éviter les temps d’arrêt, vous pouvez utiliser la clé secondaire dans vos applications.
Pour les produits dans lesquels des abonnements sont activés, les clients doivent fournir une clé dans les appels aux API de ces produits. Les développeurs peuvent obtenir une clé en envoyant une demande d’abonnement. Si vous approuvez la demande, vous devez leur envoyer la clé d’abonnement de façon sécurisée, par exemple, dans un message chiffré. Cette étape est un élément fondamental du workflow de Gestion des API.
Appeler une API avec la clé d’abonnement
Les applications doivent ajouter une clé valide dans toutes les requêtes HTTP quand elles envoient des appels aux points de terminaison d’API qui sont protégés par un abonnement. Les clés peuvent être passées dans l’en-tête de la demande ou sous la forme d’un paramètre de chaîne de requête dans l’URL.
Le nom de l’en-tête de clé d’abonnement par défaut est Ocp-Apim-Subscription-Key et celui de la chaîne de requête par défaut est subscription-key.
Pour tester vos appels d’API, vous pouvez utiliser une console de test dans le portail Azure, le portail des développeurs ou des outils en ligne de commande, comme curl. Voici un exemple de requête GET effectuée avec le portail des développeurs, qui montre l’en-tête de la clé d’abonnement :
Voici un exemple qui explique comment passer une clé dans un en-tête de demande en utilisant curl :
curl --header "Ocp-Apim-Subscription-Key: <key string>" https://<apim gateway>.azure-api.net/api/path
Voici un exemple qui explique comment utiliser une commande curl pour passer une clé comme chaîne de requête dans une URL :
curl https://<apim gateway>.azure-api.net/api/path?subscription-key=<key string>
Si une clé requise n’est pas passée dans l’en-tête ou sous la forme d’une chaîne de requête dans l’URL, vous obtenez une réponse 401 Accès refusé de la passerelle d’API.