Publier des API Microsoft Azure Data Manager for Energy sur une passerelle d’API sécurisée
Gestion des API Azure sert d’intermédiaire crucial entre les applications clientes et les API principales. Il facilite l’accès des clients aux services en masquant les détails techniques et en donnant aux organisations le contrôle de la sécurité des API.
En publiant des API Azure Data Manager for Energy via Gestion des API Azure, vous pouvez utiliser Azure Data Manager pour Energy Private Link fonctionnalité pour le trafic privé et supprimer complètement l’accès public direct à votre instance.
Cet article explique comment configurer Gestion des API Azure pour sécuriser les API Azure Data Manager pour Energy.
Prérequis
Vous avez besoin des composants, outils et informations suivants disponibles pour effectuer cette procédure pas à pas :
un réseau virtuel avec deux sous-réseaux disponibles, l’un pour le point de terminaison privé Azure Data Manager for Energy et l’autre pour l’injection de réseau virtuel Gestion des API Azure.
Azure Data Manager for Energy configuré avec liaison privée déployée dans le sous-réseau.
Gestion des API Azure provisionnée et déployée dans le réseau virtuel à l’aide de injection de réseau virtuel. Sélectionnez mode externe ou consultez la section Autres options pour mode interne.
Un éditeur de code tel que Visual Studio Code pour modifier les spécifications Azure Data Manager for Energy OpenAPI pour chacune des API publiées.
Téléchargez les spécifications Azure Data Manager for Energy OpenAPI à partir des adme-samples dépôt GitHub. Accédez au répertoire rest-apis et sélectionnez la version appropriée pour votre application.
À partir de l’inscription de l’application Azure Data Manager for Energy utilisée au moment de l’approvisionnement, notez l’ID de locataire et l’ID client:
Préparer l’instance Gestion des API
Procédez comme suit pour apporter des modifications de configuration à votre instance Gestion des API Azure :
Dans le volet Toutes les ressources , choisissez l’instance Gestion des API Azure utilisée pour cette procédure pas à pas.
Accédez à la page Paramètres des produits en la choisissant dans le regroupement des paramètres d’API :
Dans la page Produits, sélectionnez le bouton Ajouter pour créer un produit. produits de gestion des API Azure vous permettent de créer un regroupement faiblement couplé d’API qui peut être régi et géré ensemble. Nous créons un produit pour nos API Azure Data Manager for Energy.
Sur la page Ajouter un produit, entrez les valeurs décrites dans le tableau suivant pour créer le produit.
Paramètre Valeur Nom d’affichage « Azure Data Manager for Energy Product » id « adme-product » Description Entrez une description qui indique aux développeurs les API que nous groupons Publiée Cochez cette case pour publier le produit que nous créons Nécessite un abonnement Cochez cette case pour fournir une autorisation de base pour nos API Nécessite une approbation Sélectionnez éventuellement si vous souhaitez qu’un administrateur examine et accepte ou rejette les tentatives d’abonnement à ce produit. S’il n’est pas sélectionné, les tentatives d’abonnement sont automatiquement approuvées. Limite du nombre d’abonnements Si vous le souhaitez, limitez le nombre d’abonnements simultanés. Conditions légales Définissez éventuellement les conditions d’utilisation du produit que les abonnés doivent accepter pour utiliser le produit. API Nous pouvons ignorer cette fonctionnalité. Nous allons associer des API plus loin dans cet article Sélectionnez Créer pour créer le produit.
Une fois la création du produit terminée, le portail vous renvoie à la page Produits. Sélectionnez notre produit nouvellement créé Azure Data Manager for Energy Product pour accéder à la page des ressources du produit. Sélectionnez les Stratégies élément de menu paramètre dans le menu paramètres.
Dans le volet Traitement entrant, sélectionnez l’icône </>, qui vous permet de modifier des stratégies pour le produit. Vous ajoutez trois ensembles de stratégies pour améliorer la sécurité de la solution :
- Valider le jeton d’ID Entra pour vous assurer que les requêtes non authentifiées sont interceptées sur la passerelle d’API
- quota et limite de débit pour contrôler le taux de demandes et les demandes/données totales transférées
- définir l’en-tête pour supprimer les en-têtes retournés par les API back-end, ce qui peut révéler des détails sensibles aux acteurs potentiels malveillants
Ajoutez la stratégie de jeton validate-azure-ad-token suivante à notre configuration au sein des balises de entrantes et en dessous de la balise de base . Veillez à mettre à jour le modèle avec les détails de l’application Microsoft Entra ID indiqués dans les conditions préalables.
<validate-azure-ad-token tenant-id="INSERT_TENANT_ID"> <client-application-ids> <application-id>INSERT_APP_ID</application-id> </client-application-ids> </validate-azure-ad-token>Sous la stratégie validate-azure-ad-token , ajoutez les stratégies de de quota de suivantes et stratégies de de limite de débit. Mettez à jour les valeurs de configuration de stratégie selon les besoins de vos consommateurs.
<rate-limit calls="20" renewal-period="90" remaining-calls-variable-name="remainingCallsPerSubscription"/> <quota calls="10000" bandwidth="40000" renewal-period="3600" />Dans la section sortante de l’éditeur de stratégie et sous la balise de base , ajoutez les stratégies set-header suivantes.
<set-header name="x-envoy-upstream-service-time" exists-action="delete" /> <set-header name="x-internal-uri-pattern" exists-action="delete" />Sélectionnez Enregistrer pour valider vos modifications.
Revenez à la ressource Gestion des API dans le portail Azure. Sélectionnez l’élément de menu backends, puis sélectionnez le bouton + Ajouter .
Dans le backend modal, entrez les valeurs décrites dans le tableau suivant pour créer le serveur principal.
Paramètre Valeur Nom « adme-backend » Description Entrez une description qui indique aux développeurs que ce back-end est lié aux API Azure Data Manager for Energy Type URL personnalisée URL du Runtime Entrez votre URI Azure Data Manager pour l’énergie _ex. https://INSERT_ADME_NAME.energy.azure.com/Valider la chaîne de certificats Activée Valider le nom du certificat Activée 
Sélectionnez Créer pour créer le serveur principal. Ce serveur principal nouvellement créé sera utilisé dans la section suivante lorsque nous publions des API.
Importer des API Azure Data Manager for Energy
Procédez comme suit pour importer, configurer et publier des API Azure Data Manager pour Energy dans la passerelle Gestion des API Azure :
Revenez à l’instance Gestion des API Azure utilisée dans la dernière section.
Sélectionnez API élément de menu dans le menu, puis sélectionnez le bouton + Ajouter une API .
Sélectionnez OpenAPI sous le titre Créer à partir de la définition titre.
Dans la Créer à partir de la spécification OpenAPI fenêtre modale, sélectionnez le bouton bascule Full .
Recherchez les spécifications OpenAPI que vous avez téléchargées dans le cadre des prérequis et ouvrez la spécification Schéma à l’aide de l’éditeur de code de votre choix. Recherchez le mot « serveur » et notez l’URL du serveur dans le fichier ex. /api/schema-service/v1/.
Sélectionnez Sélectionnez un fichier, puis sélectionnez la spécification de l’API schéma. Une fois le chargement terminé, la fenêtre modale charge certaines valeurs à partir de la spécification.
Pour les autres champs, entrez les valeurs décrites dans le tableau suivant :
Paramètre Valeur Inclure les paramètres de requête requis dans les modèles d’opération Activée Nom d’affichage Entrez un nom complet qui est logique pour les développeurs d’applications ex. Azure Data Manager for Energy Schema Service Nom Gestion des API suggère un nom kebab-cased. Si vous le souhaitez, le nom peut être modifié, mais il doit être unique pour l’instance Description La spécification OpenAPI peut définir une description, si c’est le cas, la description remplit automatiquement. Si vous le souhaitez, mettez à jour la description selon votre cas d’usage. Modèle d’URL Sélectionnez « Les deux » Suffixe de l’URL de l’API Entrez un suffixe pour toutes les API Azure Data Manager for Energy (ex. adme). Entrez ensuite l’URL du serveur à l’étape 5. La valeur finale doit ressembler à /adme/api/schema-service/v1/. Un suffixe nous permet d’être conforme aux clients existants et aux kits de développement logiciel qui se connectent normalement aux API Azure Data Manager for Energy directement Balises Si vous le souhaitez, entrez des balises PRODUITS Sélectionnez le produit « Azure Data Manager for Energy » créé dans la section précédente Important
Valider le suffixe d’URL de l’API, c’est une cause courante d’erreurs lors de la publication des API Azure Data Manager for Energy
Sélectionnez Créer pour créer la façade d’API.
Sélectionnez la façade de l’API schéma nouvellement créée dans la liste des API, puis sélectionnez toutes les opérations dans la liste des opérations. Dans le volet traitement entrant , sélectionnez l’icône </> pour modifier le document de stratégie.
Pour configurer l’API, ajoutez deux ensembles de stratégies :
- définir le service principal pour acheminer les demandes vers l’instance Azure Data Manager for Energy
- réécrire l’URI pour supprimer le préfixe adme et générer la requête à l’API back-end. Cette instruction de stratégie utilise expressions de stratégie pour ajouter dynamiquement la valeur du modèle d’URL de l’opération actuelle à notre URL de serveur.
Notez l’URL du serveur à partir de l’étape 5. Sous la balise de base , dans la section entrante, insérez les deux instructions de stratégie suivantes.
<set-backend-service backend-id="adme-backend" /><!-- replace the '/api/schema-service/v1' with the server URL for this API specification you noted in step 5 --> <rewrite-uri template="@{return "/api/schema-service/v1"+context.Operation.UrlTemplate;}" />Sélectionnez Enregistrer pour valider vos modifications.
Testez l’API en sélectionnant les informations GET Version opération dans la liste des opérations. Sélectionnez ensuite l’onglet Test pour accéder à la console de test Gestion des API Azure.
Entrez les valeurs décrites dans le tableau suivant. Générez un jeton d’authentification pour votre azure Data Manager for Energy. Sélectionnez Envoyer pour tester l’API.
Paramètre Valeur data-partition-id ID de partition de données pour votre instance Azure Data Manager for Energy Produit Sélectionnez le produit Azure Data Manager for Energy créé précédemment Autorisation « Porteur » et le jeton d’authentification que vous avez générés 
Si l’API est correctement configurée, vous devez voir une HTTP 200 - OK réponse qui ressemble à la capture d’écran. Si ce n’est pas le cas, consultez la section Résolution des problèmes.
Répétez les étapes ci-dessus pour chaque API Azure Data Manager for Energy et la spécification associée.
Dépannage
Pendant vos tests d’API via Gestion des API Azure, si vous rencontrez des erreurs, elles pointent généralement vers des problèmes de configuration. En fonction de l’erreur, passez en revue les étapes de résolution potentielles.
| Code | Message d’erreur | Détails |
|---|---|---|
HTTP 401 Unauthorized |
Invalid Azure AD JWT |
Vérifiez que vous disposez d’un en-tête d’authentification valide pour le locataire Microsoft Entra ID et l’application cliente pour votre instance Azure Data Manager for Energy. |
HTTP 401 Unauthorized |
Azure AD JWT not present |
Vérifiez que l’en-tête d’authentification est ajouté à votre demande de test. |
HTTP 404 Not Found |
Cette erreur signifie généralement que la requête adressée à l’API back-end est effectuée à l’URL incorrecte. Trace votre demande d’API dans Gestion des API pour comprendre l’URL générée pour la requête back-end et vérifier qu’elle est valide. Si ce n’est pas le cas, vérifiez la stratégie de réécriture d’URL ou back-end . | |
HTTP 500 Internal Server Error |
Internal server error |
Cette erreur reflète généralement un problème qui émet des demandes à l’API back-end. En règle générale, dans ce scénario, le problème est lié aux services de noms de domaine (DNS). Vérifiez qu’il existe une zone DNS privée configurée dans votre réseau virtuel ou que votre résolution DNS personnalisée dispose des redirecteurs appropriés. Trace votre demande d’API dans Gestion des API pour comprendre quelle demande back-end a été effectuée et quelles erreurs gestion des API signale lors de la tentative d’effectuer la requête. |
Autres considérations
Mode de mise en réseau virtuel interne gestion des API
mode interne isole complètement le gestion des API Azure au lieu d’exposer les points de terminaison via une adresse IP publique. Dans cette configuration, les organisations peuvent s’assurer que tous les gestionnaires de données Azure pour Energy sont internes. Étant donné qu’Azure Data Manager for Energy est une solution de collaboration pour travailler avec des partenaires et des clients, ce scénario peut ne pas être bénéfique tel quel.
App Gateway avec pare-feu d’applications web
Au lieu d’utiliser le mode de réseau virtuel interne seul, de nombreuses organisations choisissent d' appliquer un mécanisme de proxy inverse sécurisé pour exposer le mode interne l’instance de gestion des API Azure aux partenaires et clients externes. L’instance en mode interne reste entièrement isolée avec une entrée étroitement contrôlée qui doit passer par le proxy.
Azure App Gateway est un service courant à utiliser comme proxy inverse. Azure App Gateway dispose également d’une fonctionnalité pare-feu d’applications web (WAF), qui détecte activement les attaques potentielles contre les vulnérabilités dans vos applications et API.
Configuration de gestion des API Azure avec un domaine personnalisé
Une autre fonctionnalité courante de cette architecture consiste à appliquer un domaine personnalisé aux API. Bien qu’Azure Data Manager for Energy ne prend pas en charge cette fonctionnalité, vous pouvez configurer un domaine personnalisé sur Gestion des API Azure à la place.
Un certificat pour le domaine est un prérequis. Toutefois, Gestion des API Azure prend en charge la création de certificats managés gratuits pour votre domaine personnalisé.