Partager via

Utiliser des valeurs nommées dans les stratégies Gestion des API Azure

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

Les stratégies Gestion des API sont une fonctionnalité puissante du système qui permet à l’éditeur de modifier le comportement de l’API grâce à la configuration. Les stratégies sont un ensemble d'instructions qui sont exécutées dans l'ordre sur demande ou sur réponse d'une API. Les instructions de la stratégie peuvent être construites à l’aide de valeurs de texte littéral, d’expressions de stratégie et de valeurs nommées.

Les valeurs nommées représentent une collection globale de paires nom/valeur dans chaque instance Gestion des API. Vous pouvez utiliser des valeurs nommées pour gérer les valeurs de chaîne et les secrets constants dans toutes les configurations et stratégies d’API.

Valeurs nommées dans le portail Azure

Types valeur

Type Descriptif
Plain Chaîne littérale ou expression de stratégie
Secret Chaîne littérale ou expression de stratégie chiffrée par Gestion des API
Coffre-fort de clés Identificateur d’un secret stocké dans un coffre de clés Azure.

Les valeurs brutes ou les secrets peuvent contenir des expressions de stratégie. Par exemple, l’expression @(DateTime.Now.ToString()) retourne une chaîne contenant la date et l’heure actuelles.

Pour plus d’informations sur les attributs de valeurs nommées, consultez les informations de référence sur l’API REST dans Gestion des API.

Secrets Key Vault

Les valeurs de secret peuvent être stockées en tant que chaînes chiffrées dans Gestion des API (secrets personnalisés) ou en référençant les secrets dans Azure Key Vault.

Nous vous recommandons d’utiliser des secrets key vault, car ils aident à améliorer la sécurité gestion des API :

Remarque

Actuellement, l’intégration avec Key Vault pour ce scénario n'est pas disponible dans les espaces de travail.

  • Vous pouvez réutiliser les secrets stockés dans des coffres de clés entre les services.
  • Vous pouvez appliquer des stratégies d’accès granulaires aux secrets.
  • Les secrets mis à jour dans le coffre de clés sont automatiquement permutés dans Gestion des API. Après la mise à jour dans le coffre de clés, une valeur nommée dans Gestion des API est mise à jour dans les quatre heures. Vous pouvez également actualiser manuellement le secret à l’aide du portail Azure ou par le biais de l’API REST de gestion.

Remarque

Les secrets stockés dans Azure Key Vault doivent être compris entre 1 et 4 096 caractères, car gestion des API ne peut pas récupérer les valeurs qui dépassent cette limite.

Prérequis

Conditions préalables à l’intégration d’un coffre de clés

Remarque

Cette fonctionnalité n’est actuellement pas disponible dans les espaces de travail.

Configurer l’accès au coffre de clés

  1. Dans le portail, allez à votre coffre-fort de clés.
  2. Dans le menu de gauche, sélectionnez Configurationd’accès aux>. Notez le modèle d’autorisation configuré.
  3. Selon le modèle d’autorisation, configurez une stratégie d’accès au coffre de clés ou un accès RBAC Azure pour une identité managée Gestion des API.

Pour ajouter une stratégie d’accès au coffre de clés :

  1. Dans le menu de gauche, sélectionnez Stratégies d’accès.
  2. Dans la page Stratégies d’accès, sélectionnez + Créer.
  3. Sous l’onglet Autorisations , sous Autorisations secrètes, sélectionnez Obtenir et Liste, puis sélectionnez Suivant.
  4. Sous l’onglet Principal , recherchez le nom de la ressource de votre identité managée, puis sélectionnez Suivant. Si vous utilisez une identité attribuée par le système, le principal est le nom de votre instance Gestion des API.
  5. Sélectionnez Suivant de nouveau. Sous l’onglet Review + create (Vérifier + créer), sélectionnez Créer.

Pour configurer l’accès RBAC Azure :

  1. Dans le menu de gauche, sélectionnez Contrôle d’accès (IAM).
  2. Sur la page Contrôle d’accès (IAM), sélectionnez Ajout de l’attribution de rôle.
  3. Sous l’onglet Rôle , sélectionnez Utilisateur des secrets Key Vault, puis Sélectionnez Suivant.
  4. Sous l’onglet Membres, sélectionnez Identité managée>+ Sélectionner des membres.
  5. Dans la page Sélectionner l’identité managée, sélectionnez l’identité managée affectée par le système ou une identité managée affectée par l’utilisateur associée à votre instance Gestion des API, puis sélectionnez Sélectionner.
  6. Sélectionnez Vérifier + affecter.

Exigences pour le pare-feu Key Vault

Si le pare-feu Key Vault est activé sur votre coffre de clés, vous devez répondre à ces exigences :

  • Vous devez utiliser l’identité managée affectée par le système de l’instance Gestion des API pour accéder au coffre de clés.

  • Vérifiez que votre instance de Gestion de l'API dispose d'un accès réseau vers le Key Vault. Selon vos scénarios, configurez l’une des options d’accès réseau suivantes sur le coffre de clés :

    • Autoriser l’accès public à partir de tous les réseaux.

    • Définissez une règle de sécurité réseau pour autoriser le trafic Gestion des API en fonction de l’adresse IP ou de la connectivité de réseau virtuel.

    • Sécuriser le trafic à partir de la gestion des API avec la connectivité Private Link.

    • Utilisez un périmètre de sécurité réseau pour sécuriser votre coffre de clés et autoriser le trafic à partir de Gestion des API.

  • Vérifiez que votre adresse IP du client local est autorisée à accéder temporairement au coffre de clés pendant que vous sélectionnez un certificat ou un secret à ajouter à Gestion des API Azure. Pour plus d’informations, consultez Configurer les paramètres de mise en réseau du Coffre de clés Azure.

    Une fois la configuration terminée, vous pouvez bloquer votre adresse client dans le pare-feu du coffre de clés.

Important

À compter de mars 2026, la connectivité des services de confiance à Azure Key Vault depuis API Management, en activant l'option Permettre aux services Microsoft approuvés de contourner ce paramètre de pare-feu du coffre de clés, ne sera plus prise en charge. Pour continuer à utiliser Key Vault avec Gestion des API après cette modification, veillez à choisir une option d’accès réseau prise en charge, comme décrit ci-dessus. En savoir plus.

Conditions requises pour le réseau virtuel

Si l’instance Gestion des API est déployée dans un réseau virtuel, configurez également les paramètres réseau suivants :

  • Activez un point de terminaison de service sur Key Vault sur le sous-réseau Gestion des API.
  • Configurez une règle de groupe de sécurité réseau (NSG) pour autoriser le trafic sortant vers les balises de service AzureKeyVault et AzureActiveDirectory.

Pour plus d’informations, consultez Configuration réseau lors de la configuration de gestion des API dans un réseau virtuel.

Ajouter ou modifier une valeur nommée

Ajouter un secret du coffre de clés à Gestion des API

Voir Conditions préalables à l’intégration d’un coffre de clés.

Important

Lorsque vous ajoutez un secret de coffre de clés à votre instance Gestion des API, vous devez disposer des autorisations nécessaires pour répertorier les secrets du coffre de clés.

Attention

Lorsque vous utilisez un secret de coffre de clés dans Gestion des API, veillez à ne pas supprimer le secret, le coffre de clés ou l’identité managée utilisée pour accéder au coffre de clés.

  1. Dans le portail Azure, accédez à votre instance APIM.

  2. Sous APIs, sélectionnez Valeurs nommées>+ Ajouter.

  3. Entrez un identificateur de nom, puis un nom d’affichage utilisé pour référencer la propriété dans les stratégies.

  4. Ajoutez une ou plusieurs balises facultatives pour faciliter l’organisation de vos valeurs nommées.

  5. Dans la liste déroulante Type , sélectionnez Coffre de clés.

  6. Entrez l’identificateur d’un secret de coffre de clés (sans version), ou choisissez Sélectionner pour choisir un secret dans un coffre de clés.

    Important

    Si vous entrez vous-même un identificateur de secret de coffre de clés, assurez-vous qu’il ne contient pas d’informations de version. Sinon, le secret n’est pas automatiquement permuté dans Gestion des API après une mise à jour dans le coffre de clés.

  7. Dans Identité du client, sélectionnez une entité managée affectée par le système ou une entité managée existante affectée par l’utilisateur. Découvrez comment ajouter ou modifier des identités managées dans votre service Gestion des API.

    Remarque

    L’identité a besoin d’autorisations pour obtenir et lister les secrets du coffre de clés. Si vous n’avez pas encore configuré l’accès au coffre de clés, Gestion des API vous invite à configurer automatiquement l’identité avec les autorisations nécessaires.

  8. Sélectionnez Enregistrer, puis sélectionnez Créer.

    Ajouter une valeur de secret de coffre de clés

Ajouter une valeur brute ou secrète à Gestion des API

  1. Dans le portail Azure, accédez à votre instance APIM.
  2. Sous API, sélectionnez Valeurs nommées>Ajouter.
  3. Entrez un identificateur de nom, puis un nom d’affichage utilisé pour référencer la propriété dans les stratégies.
  4. Dans la liste déroulante Type , sélectionnez Plain ou Secret.
  5. Dans Valeur, entrez une chaîne ou une expression de stratégie.
  6. Ajoutez une ou plusieurs balises facultatives pour faciliter l’organisation de vos valeurs nommées, puis sélectionnez Enregistrer.
  7. Sélectionnez Create (Créer).

Une fois la valeur nommée créée, vous pouvez la modifier en sélectionnant son nom. Si vous modifiez le nom d’affichage, toutes les stratégies qui font référence à cette valeur nommée sont automatiquement mises à jour pour utiliser le nouveau nom d’affichage.

Utiliser une valeur nommée

Les exemples de cette section utilisent les valeurs nommées affichées dans le tableau suivant.

Nom Valeur Secret
ContosoHeader TrackingId False
ContosoHeaderValue •••••••••••••••••••••• Vrai
ExpressionProperty @(DateTime.Now.ToString()) False
ContosoHeaderValue2 This is a header value. False

Pour utiliser une valeur nommée dans une stratégie, placez son nom d’affichage dans une paire d’accolades telle que {{ContosoHeader}}, comme illustré dans l’exemple suivant :

<set-header name="{{ContosoHeader}}" exists-action="override">
  <value>{{ContosoHeaderValue}}</value>
</set-header>

Dans cet exemple, ContosoHeader est utilisé comme nom d’en-tête d’une stratégie set-header, et ContosoHeaderValue comme valeur de cet en-tête. Lorsque cette stratégie est évaluée lors d’une demande ou d’une réponse à la passerelle Gestion des API, {{ContosoHeader}} et {{ContosoHeaderValue}} sont remplacés par leurs valeurs respectives.

Vous pouvez utiliser des valeurs nommées comme attribut complet ou valeurs d’élément comme indiqué dans l’exemple précédent, mais elles peuvent également être insérées dans ou combinées avec une partie d’une expression de texte littérale, comme illustré dans l’exemple suivant :

<set-header name = "CustomHeader{{ContosoHeader}}" ...>

Les valeurs nommées peuvent également contenir des expressions de stratégie. Dans l’exemple suivant, l’expression ExpressionProperty est utilisée.

<set-header name="CustomHeader" exists-action="override">
    <value>{{ExpressionProperty}}</value>
</set-header>

Lorsque cette stratégie est évaluée, {{ExpressionProperty}} est remplacé par sa valeur, @(DateTime.Now.ToString()). Étant donné que la valeur est une expression de stratégie, l’expression est évaluée et la stratégie se poursuit avec son exécution.

Vous pouvez tester cette opération dans le portail Azure ou dans le portail des développeurs en appelant une opération qui a une stratégie dont l’étendue inclut des valeurs nommées. Dans l’exemple suivant, une opération est appelée avec les deux stratégies set-header de l’exemple précédent incluant des valeurs nommées. Notez que la réponse contient deux en-têtes personnalisés configurés à l’aide de stratégies et de valeurs nommées.

Capture d’écran d’une réponse d’API de test.

Si vous examinez le suivi de l’API sortant pour un appel qui inclut les deux exemples de stratégies précédents incluant des valeurs nommées, vous pouvez voir les deux stratégies set-header avec les valeurs nommées insérées, ainsi que l’évaluation de l’expression de stratégie pour la valeur nommée contenant l’expression de stratégie.

Capture d’écran d’une trace d’inspecteur d’API.

Vous pouvez également utiliser l’interpolation de chaîne avec des valeurs nommées.

<set-header name="CustomHeader" exists-action="override">
    <value>@($"The URL encoded value is {System.Net.WebUtility.UrlEncode("{{ContosoHeaderValue2}}")}")</value>
</set-header>

La valeur de CustomHeader sera The URL encoded value is This+is+a+header+value..

Attention

Si une stratégie fait référence à un secret dans Azure Key Vault, la valeur du coffre de clés est visible pour les utilisateurs qui ont accès aux abonnements activés pour le suivi des demandes d’API.

Alors que les valeurs nommées peuvent contenir des expressions de stratégie, elles ne peuvent pas contenir d’autres valeurs nommées. Si le texte contenant une référence de valeur nommée est utilisé pour une valeur, telle que Text: {{MyProperty}}, cette référence ne sera pas résolue et remplacée.

Supprimer une valeur nommée

Pour supprimer une valeur nommée, sélectionnez le nom, puis sélectionnez Supprimer dans le menu contextuel (...).

Important

Si la valeur nommée est référencée par des stratégies Gestion des API, vous ne pouvez pas la supprimer tant que vous ne l’avez pas supprimée de toutes les stratégies qui l’utilisent.

Contenu connexe

En savoir plus sur l’utilisation des stratégies :

  • Last updated on