Appeler une API avec une clé d’abonnement

  • 5 minutes

Quand vous publiez une API, vous souhaitez souvent un certain niveau de contrôle sur l’accès à l’API par le biais de la passerelle. Les clés d’abonnement permettent de restreindre l’accès à une API.

Ici, vous allez découvrir comment utiliser des clés d’abonnement pour sécuriser vos API.

Abonnements et clés

Pour protéger vos API, vous pouvez utiliser une clé d’abonnement.

Remarque

Dans les environnements de production de Gestion des API, vous combinez généralement une clé d’abonnement à d’autres mécanismes pour protéger vos API contre toute utilisation non autorisée, comme l’authentification par certificat ou l’autorisation OAuth 2.0. Ces points ne sont pas traités dans ce module.

Une clé d’abonnement est une chaîne générée automatiquement et transmise dans les en-têtes de la requête du client ou sous forme de chaîne de requête dans l’URL. La clé est directement liée à un abonnement qui peut être étendu à différentes zones : ceci offre un contrôle granulaire sur les autorisations et les stratégies. Les étendues principales des abonnements sont :

  • Toutes les API
  • Une seule API
  • Un produit

Une application qui appelle une API protégée doit inclure la clé dans la requête.

Vous pouvez regénérer ces clés d’abonnement à tout moment. Par exemple, régénérez les clés d’abonnement si vous suspectez qu’une clé a été partagée avec des utilisateurs non autorisés.

Clés d’abonnement.

Chaque abonnement a deux clés : une clé principale et une clé secondaire. Le fait d’avoir deux clés facilite la régé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 où des abonnements sont activés, vous devez fournir une clé lors des appels aux API de ce produit. En tant que développeur, vous pouvez obtenir une clé en envoyant une demande d’abonnement. Ce processus est un élément fondamental du workflow de Gestion des API.

Notes

Le fait de créer des utilisateurs et de leur donner leurs clés d’abonnement afin qu’ils puissent accéder à l’API est un élément fondamental du workflow de Gestion des API, mais il n’est pas couvert par ce module.

Appeler une API avec la clé d’abonnement

Les applications doivent inclure une clé valide dans toutes les requêtes HTTP quand elles effectuent 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’une chaîne de requête dans l’URL.

Le nom de l’en-tête par défaut est Ocp-Apim-Subscription-Key, et la chaîne de requête par défaut est subscription-key.

Pour tester vos appels d'API, vous pouvez utiliser le portail des développeurs (s'il est disponible dans votre niveau de service), un outil de ligne de commande tel que curl ou d'autres outils clients REST.

Voici un exemple de requête GET qui transmet une clé dans l’en-tête de demande à l’aide de la commande curl :

curl --header "Ocp-Apim-Subscription-Key: <key string>" https://<apim gateway>.azure-api.net/api/path

Voici un exemple de commande curl qui passe une clé dans l’URL sous la forme d’une chaîne de requête :

curl https://<apim gateway>.azure-api.net/api/path?subscription-key=<key string>

Si la clé n’est pas transmise 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 API.