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

  • Article

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. Il n’existe aucune limite imposée quant au nombre d’éléments que peut contenir une collection. Les valeurs nommées peuvent être utilisées pour gérer les valeurs de chaîne constantes et les secrets dans l’ensemble des stratégies et de la configuration des API.

Valeurs nommées dans le portail Azure

Types de valeur

Type Description
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
Key vault 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.

L’utilisation de secrets Key Vault est recommandée car elle permet d’améliorer la sécurité de Gestion des API :

  • Les secrets stockés dans les coffres de clés peuvent être réutilisés dans les services
  • Des stratégies d’accès granulaires peuvent être appliquées 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 4 heures. Vous pouvez également actualiser manuellement le secret à l’aide du portail Azure ou par le biais de l’API REST de gestion.

Prérequis

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

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

  1. Dans le portail, accédez à votre coffre de clés.

  2. Dans le menu de gauche, sélectionnez Configuration de l’accès et 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. Sur la page Stratégies d’accès, sélectionnez + Créer.
    3. Sous l’onglet Autorisations, sous Autorisations du secret, sélectionnez Get et List, puis sélectionnez Suivant.
    4. Sous l’onglet Principal, sélectionnez Sélectionner le principal, recherchez le nom de 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 de secrets Key Vault.
    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 + attribuer.

Exigences pour le pare-feu Key Vault

Si le pare-feu Key Vault est activé sur votre coffre de clés, les conditions suivantes sont requises :

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

  • Dans le pare-feu Key Vault, activez l’option Autoriser les services Microsoft approuvés à contourner ce pare-feu.

  • 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.

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 pour Azure 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 du réseau lors de la configuration de Gestion des API Azure 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 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 Type de valeur, sélectionnez Coffre de clés.

  5. 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.

  6. 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.

    Notes

    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.

  7. Ajoutez une ou plusieurs balises facultatives pour faciliter l’organisation de vos valeurs nommées, puis sélectionnez Enregistrer.

  8. Sélectionnez Create (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 Type de valeur, sélectionnez Plain (Brute) ou Secret (Secrète).
  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 Faux
ContosoHeaderValue •••••••••••••••••••••• True
ExpressionProperty @(DateTime.Now.ToString()) Faux
ContosoHeaderValue2 This is a header value. Faux

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.

Les valeurs nommées peuvent être utilisées comme attribut complet ou valeurs d’élément, comme indiqué dans l’exemple précédent. Elles peuvent également être insérées dans ou combinés avec une partie d’une expression de texte littéral, 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 poursuit 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.

Tester la réponse de l’API

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.

Suivi de l’inspecteur d’API

L’interpolation de chaîne peut également être utilisée 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 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 son nom, puis choisissez 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.

Étapes suivantes