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

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.

Named values in the Azure portal

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.

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

  1. Pour connaître la procédure de création d’un coffre de clés, consultez Démarrage rapide : Créer un coffre de clés avec le portail Azure.
  2. Activer une identité managée attribuée par le système ou par l’utilisateur dans l’instance Gestion des API.
  3. Affectez une stratégie d’accès Key Vault à l’identité managée avec les autorisations pour récupérer et répertorier les secrets du coffre. Pour ajouter la stratégie :
    1. Dans le portail, accédez à votre coffre de clés.
    2. Sélectionnez Paramètres > Stratégies d’accès > +Ajouter une stratégie d’accès.
    3. Sélectionnez Autorisations du secret, puis Get (Obtenir) et List (Lister).
    4. Dans Sélectionner le principal, sélectionnez le nom de ressource de votre identité managée. Si vous utilisez une identité attribuée par le système, le principal est le nom de votre instance Gestion des API.
  4. Créez ou importez un secret dans le coffre de clés. Consultez Démarrage rapide : Définir et récupérer un secret depuis Azure Key Vault à l’aide du portail Azure.

Pour utiliser le secret du coffre de clés, ajoutez ou modifiez une valeur nommée, puis spécifiez un type de coffre de clés. Sélectionnez le secret dans le coffre de clés.

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.

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 de coffre de clés

Voir Conditions préalables à l’intégration d’un 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).

    Add key vault secret value

Ajouter une valeur brute ou secrète

  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

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.

Test API response

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.

API Inspector trace

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