Partage via

Abonnements dans Gestion des API Azure

  • Article

S’APPLIQUE À : Tous les niveaux de Gestion des API

Dans Azure API Management, les abonnements sont la manière la plus courante pour des consommateurs d’API d’accéder aux API publiées via une instance de Gestion des API. Cet article fournit une vue d’ensemble du concept.

Notes

Un abonnement API Management est utilisé spécifiquement pour appeler des API via API Management à l'aide d'une clé d'abonnement. Ce n’est pas la même chose qu’un abonnement Azure.

Qu’est-ce qu’un abonnement ?

En publiant des API via Gestion des API, vous pouvez facilement sécuriser l’accès aux API à l’aide de clés d’abonnement. Les développeurs qui doivent utiliser les API publiées doivent inclure une clé d’abonnement valide dans les requêtes HTTP lorsqu’ils appellent ces API. Sans une clé d’abonnement valide, les appels :

  • Sont immédiatement rejetés par la passerelle Gestion des API.
  • Ne sont pas transférés aux services principaux.

Pour accéder aux API, les développeurs doivent disposer d’un abonnement et d’une clé d’abonnement. Un abonnement est un conteneur nommé pour une paire de clés d’abonnement.

De plus :

  • Les développeurs peuvent obtenir des abonnements sans l’approbation des éditeurs d’API.
  • Les éditeurs d’API peuvent également créer des abonnements directement pour les consommateurs d’API.

Conseil

La Gestion des API prend également en charge d’autres mécanismes de protection de l’accès aux API, entre autres :

Gérer les clés d’abonnement

La régénération régulière des clés est une mesure de sécurité courante. Comme la plupart des services Azure nécessitant une clé d’abonnement, Gestion des API génère des clés par paires. Chaque application qui utilise le service peut passer de la clé A à la clé B, et régénérer la clé A avec une interruption minimale, et vice versa.

Vous pouvez définir des clés spécifiques au lieu de les régénérer en appelant l’Abonnement API Management Azure - Créer ou mettre à jour l’API REST Azure. Plus précisément, le properties.primaryKey et/ou le properties.secondaryKey doivent être définis dans le corps de la requête HTTP.

Remarque

  • Gestion des API ne fournit pas de fonctionnalités intégrées pour gérer le cycle de vie des clés d’abonnement, telles que la définition des dates d’expiration ou la rotation automatique des clés. Vous pouvez développer des workflows pour automatiser ces processus à l’aide d’outils tels qu’Azure PowerShell ou les Kits de développement logiciel (SDK) Azure.
  • Pour appliquer un accès limité dans le temps aux API, les éditeurs d’API peuvent être en mesure d’utiliser des stratégies avec des clés d’abonnement ou d’utiliser un mécanisme qui fournit une expiration intégrée, comme l’authentification basée sur des jetons.

Étendue des abonnements

Les abonnements peuvent être associés à différentes étendues : un produit, toutes les API ou une API individuelle.

Abonnements pour un produit

Habituellement, les abonnements dans Gestion des API sont associés à une seule étendue de produit. Développeurs :

  • Ont trouvé la liste des produits sur le portail des développeurs.
  • Ont soumis des demandes d’abonnement pour les produits qu’ils souhaitent utiliser.
  • Utilisent les clés de ces abonnements (approuvées automatiquement ou par des serveurs de publication d’API) pour accéder à toutes les API dans le produit.

Actuellement, le portail des développeurs affiche uniquement les abonnements dans l’étendue du produit dans la section Profil utilisateur.

Abonnements de produit

Abonnements pour toutes les API ou une API individuelle

Vous pouvez également créer des clés qui accordent l’accès à :

  • une seule API ; ou
  • toutes les API dans une instance de Gestion des API.

Dans ces cas, il n’est pas nécessaire de créer un produit et d’y ajouter des API au préalable.

Abonnement avec accès complet

Chaque instance de gestion des API est livrée avec un abonnement intégré à accès total qui accorde l'accès à toutes les API. Cet abonnement à l'étendue du service permet aux propriétaires de services de tester et de déboguer facilement les API dans la console de test.

Avertissement

L’abonnement à tous les accès permet d’accéder à chaque API de l’instance Gestion des API et ne doit être utilisé que par les utilisateurs autorisés. N’utilisez jamais cet abonnement pour l’accès aux API de routine ou incorporez la clé d’abonnement tout accès dans les applications clientes.

Remarque

Si vous utilisez un abonnement dont l’étendue est basée sur l’API, un abonnement basé sur tout les APIs ou le ou l’abonnement avec accès complet incorporé, les stratégies configurées dans l’étendue du produit ne sont pas appliquées aux requêtes provenant de cet abonnement.

Abonnements autonomes

La Gestion des API autorise également les abonnements autonomes, qui ne sont pas associés à un compte de développeur. Cette fonctionnalité s’avère utile dans des scénarios tels que ceux où plusieurs développeurs ou équipes partagent un abonnement.

La création d’un abonnement sans attribution de propriétaire en fait un abonnement autonome. Pour permettre aux développeurs et au reste de votre équipe d’accéder à la clé d’abonnement autonome, vous pouvez :

  • Partager manuellement la clé d’abonnement.
  • Utiliser un système personnalisé pour mettre la clé d’abonnement à la disposition de votre équipe.

Créer et gérer des abonnements dans le portail Azure

Les éditeurs d’API peuvent créer des abonnements directement dans le portail Azure.

Quand il est créé dans le portail, un abonnement est à l’état Actif, ce qui signifie qu’un abonné peut appeler une API associée en utilisant une clé d’abonnement valide. Vous pouvez modifier l'état de l'abonnement si nécessaire. Par exemple, vous pouvez suspendre, annuler ou supprimer tout abonnement (y compris l'abonnement tout accès intégré) pour empêcher l'accès à l'API.

Utiliser une clé d’abonnement

Un abonné peut utiliser une clé d’abonnement à la Gestion des API de deux manières :

  • Ajoutez l’en-tête HTTP Ocp-Apim-Subscription-Key à la requête, en transmettant la valeur d’une clé d’abonnement valide.

  • Incluez le paramètre de requête subscription-key et une valeur valide dans l’URL. Le paramètre de requête est vérifié uniquement si l’en-tête n’est pas présent.

Conseil

Ocp-Apim-Subscription-Key est le nom par défaut de l’en-tête de clé d’abonnement, et subscription-key est le nom par défaut du paramètre de requête. Si vous le souhaitez, vous pouvez modifier ces noms dans les paramètres de chaque API. Par exemple, dans le portail, mettez à jour ces noms sous l’onglet Paramètres d’une API.

Remarque

La clé d’abonnement est transmise par défaut au back-end lorsqu’elle est incluse dans l’en-tête d’une requête ou dans un paramètre de requête. Elle peut être exposée dans les journaux de surveillance du back-end ou dans d’autres systèmes. Si ces données sont considérées comme sensibles, vous pouvez configurer une stratégie à la fin de la section inbound pour supprimer l’en-tête de la clé d’abonnement (set-header) ou le paramètre de requête (set-query-parameter).

Activer ou désactiver l’exigence d’abonnement pour l’accès à l’API ou au produit

Par défaut, quand vous créez une API, une clé d’abonnement est requise pour l’accès à l’API. De même, quand vous créez un produit, une clé d’abonnement est requise par défaut pour accéder à toute API ajoutée au produit. Dans certains scénarios, un éditeur d’API peut parfois souhaiter publier un produit ou une API particulière à destination du public, sans passer par les abonnements. Bien qu’un éditeur puisse choisir d’activer l’accès non sécurisé (anonyme) à certaines API, il est recommandé de configurer un autre mécanisme pour sécuriser l’accès client.

Attention

Faites attention lors de la configuration d’un produit ou d’une API ne nécessitant pas d’abonnement. Cette configuration peut être trop permissive et rendre une API plus vulnérable à certaines menaces de sécurité des API.

Remarque

Les produits ouverts ont le Nécessite un paramètre d’abonnement désactivé, ce qui signifie que les utilisateurs n’ont pas besoin de s’y abonner. Pour cette raison, les produits ouverts ne sont pas affichés sur la page Produits du portail des développeurs.

Vous pouvez désactiver l’exigence d’abonnement au moment de la création d’une API ou d’un produit, ou à une date ultérieure.

Pour désactiver l’obligation d’abonnement à l’aide du portail :

  • Désactiver l’obligation pour le produit : dans la page Paramètres du produit, désactivez Nécessite un abonnement.
  • Désactiver l’obligation pour l’API : dans la page Paramètres de l’API, désactivez Nécessite un abonnement.

Après avoir désactivé l’obligation d’abonnement, vous pouvez accéder aux API sélectionnées sans clé d’abonnement.

Traitement des requêtes par Gestion des API avec ou sans clé d’abonnement

Demande d’API avec une clé d’abonnement

Quand Gestion des API reçoit une demande d’API d’un client avec une clé d’abonnement, le service traite la demande conformément aux règles suivantes :

  1. Cela vérifie d’abord s’il s’agit d’une clé valide associée à un abonnement actif, qui peut être :

    • Un abonnement étendu à l’API
    • Un abonnement étendu à un produit affecté à l’API
    • Un abonnement étendu à toutes les API
    • L’abonnement étendu au service (abonnement avec accès complet intégré)

    Si une clé valide pour un abonnement actif dans une étendue appropriée est fournie, l’accès est autorisé. Les stratégies sont appliquées en fonction de la configuration de la définition de stratégie au niveau de cette étendue.

  2. Si la clé n’est pas valide, mais qu’un produit existant inclut l’API, mais ne nécessite pas d’abonnement (un produit ouvrir), ignorez la clé et gérez-le en tant que demande d’API sans clé d’abonnement (voir ci-dessous).

  3. Sinon, l’accès est refusé (erreur 401 Accès refusé).

Demande d’API sans clé d’abonnement

Lorsque Gestion des API reçoit une demande d’API d’un client sans clé d’abonnement, le service traite la demande conformément aux règles suivantes :

  1. Vérifiez tout d’abord l’existence d’un produit qui inclut l’API, mais qui ne nécessite pas d’abonnement (produit ouvert). Si le produit ouvert existe, traitez la demande dans le contexte des API, des stratégies et des règles d’accès configurées pour le produit ouvert. Une API peut être associée au maximum à un produit ouvert.
  2. Si aucun produit ouvert incluant l’API n’est trouvé, vérifiez si l’API nécessite un abonnement. Si un abonnement n’est pas nécessaire, traitez la demande dans le contexte de cette API et de cette opération.
  3. Si aucun produit ni aucune API configurés ne sont trouvés, l’accès est refusé (erreur 401 Accès refusé).

Tableau récapitulatif

Le tableau suivant récapitule la façon dont la passerelle gère les demandes d’API avec ou sans clés d’abonnement dans différents scénarios. Les configurations susceptibles de permettre un accès involontaire et anonyme à l’API sont signalées.

Tous les produits affectés à l’API nécessitent un abonnement L’API nécessite un abonnement Appel d’API avec clé d’abonnement Appel d’API sans clé d’abonnement Scénarios classiques
✔️ ✔️ Accès autorisé :

• Clé étendue au produit
• Clé étendue à l’API
• Clé étendue à toutes les API
• Clé étendue au service

Accès refusé :

• Autre clé non étendue au produit ou à l’API applicable		 Accès refusé Accès à l’API protégé au moyen d’un abonnement étendu au produit ou à l’API
✔️ ❌ Accès autorisé :

• Clé étendue au produit
• Clé étendue à l’API
• Clé étendue à toutes les API
• Clé étendue au service
• Autre clé non étendue au produit ou à l’API applicable		 Accès autorisé (contexte d’API) • Accès à l’API protégé avec un abonnement étendu au produit

• Accès anonyme à l’API. Si l’accès anonyme n’est pas prévu, configurez des stratégies au niveau de l’API pour appliquer l’authentification et l’autorisation.
❌1 ✔️ Accès autorisé :

• Clé étendue au produit
• Clé étendue à l’API
• Clé étendue à toutes les API
• Clé étendue au service

Accès refusé :

• Autre clé non étendue au produit ou à l’API applicable		 Accès autorisé (contexte de produit ouvert) • Accès à l’API protégé avec un abonnement étendu à l’API

• Accès anonyme à l’API. Si l’accès anonyme n’est pas prévu, effectuez une configuration avec des stratégies de produit pour appliquer l’authentification et l’autorisation.
❌1 ❌ Accès autorisé :

• Clé étendue au produit
• Clé étendue à l’API
• Clé étendue à toutes les API
• Clé étendue au service
• Autre clé non étendue au produit ou à l’API applicable		 Accès autorisé (contexte de produit ouvert) Accès anonyme à l’API. Si l’accès anonyme n’est pas prévu, effectuez une configuration avec des stratégies de produit pour appliquer l’authentification et l’autorisation.

1 Il existe un produit ouvert associé à l’API.

Considérations

  • L’accès à l’API dans un contexte de produit est identique, que le produit soit publié ou non. L’annulation de la publication du produit le masque dans le portail des développeurs, mais elle n’invalide pas les clés d’abonnement nouvelles ou existantes.
  • Si une API ne nécessite pas d’authentification d’abonnement, toute demande d’API qui inclut une clé d’abonnement est traitée comme une demande sans clé d’abonnement. La clé d’abonnement est ignorée.
  • Le « contexte » de l’accès à l’API désigne les stratégies et les contrôles d’accès qui sont appliqués dans une étendue particulière (par exemple, API ou produit).

Étapes suivantes

Sachez-en plus sur la Gestion des API :

  • Découvrez de quelle façon les stratégies de Gestion des API sont appliquées à différentes étendues.
  • Découvrez les autres concepts de la Gestion des API.
  • Suivez nos tutoriels sur la Gestion des API.
  • Consultez notre page de FAQ pour prendre connaissance des questions courantes.