Configurer un nom de domaine personnalisé pour votre instance de Gestion des API Azure

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

Lorsque vous créez une instance de service Gestion des API Azure dans le cloud Azure, Azure lui attribue un sous-domaine azure-api.net (par exemple, apim-service-name.azure-api.net). Vous pouvez également exposer vos points de terminaison de Gestion des API à l'aide de votre propre nom de domaine personnalisé, tel que contoso.com. Cet article explique comment mapper un nom DNS personnalisé existant à des points de terminaison exposés par une instance Gestion des API.

Important

Gestion des API accepte uniquement les demandes dont les valeurs d’en-tête d’hôte correspondant :

  • Nom de domaine par défaut de la passerelle
  • N’importe quel nom de domaine personnalisé configuré de la passerelle

Note

Actuellement, les noms de domaine personnalisés ne sont pas pris en charge dans une passerelle d’espace de travail.

Important

Les modifications apportées à l’infrastructure de votre service Gestion des API (telles que la configuration de domaines personnalisés, l’ajout de certificats d’autorité de certification, la mise à l’échelle, la configuration du réseau virtuel, les modifications de zone de disponibilité et les ajouts de régions) peuvent prendre 15 minutes ou plus, en fonction du niveau de service et de la taille du déploiement. Attendez-vous à des temps plus longs pour une instance avec un plus grand nombre d’unités d’échelle ou une configuration multirégion (passerelles dans plusieurs emplacements). Les modifications propagées apportées à Gestion des API sont exécutées avec soin pour préserver la capacité et la disponibilité.

Pendant la mise à jour du service, d’autres modifications de l’infrastructure de service ne peuvent pas être apportées. Toutefois, vous pouvez configurer des API, des produits, des stratégies et des paramètres utilisateur. Le service n’aura pas de temps d’arrêt de passerelle et Gestion des API continuera à traiter les demandes d’API sans interruption (sauf dans le niveau Développeur).

Prerequisites

  • Une instance APIM. Pour plus d’informations, consultez Créer une instance de Gestion des API Azure.

  • Un nom de domaine personnalisé qui vous appartient ou à votre organisation. Cet article ne fournit aucune instruction sur la manière de se procurer un nom de domaine personnalisé.

  • (Facultatif) Un certificat valide avec une clé publique et privée (.PFX). Le sujet ou l’autre nom du sujet (SAN) doit correspondre au nom de domaine. Cela permet à l’instance de Gestion des API d’exposer les URL de manière sécurisée sur TLS.

    Voir Options de certificat de domaine.

  • Des enregistrements DNS hébergés sur un serveur DNS pour mapper le nom de domaine personnalisé au nom de domaine par défaut de votre instance Gestion des API. Cette rubrique ne fournit aucune instruction sur l’hébergement des enregistrements DNS.

    Pour plus d’informations sur les enregistrements requis, voir Configuration DNS plus loin dans cet article.

Points de terminaison pour les domaines personnalisés

Il existe plusieurs points de terminaison Gestion des API auxquels vous pouvez attribuer un nom de domaine personnalisé. Actuellement, les points de terminaison disponibles sont les suivants :

Endpoint Default
Gateway La valeur par défaut est <apim-service-name>.azure-api.net. La passerelle est le seul point de terminaison pouvant être configuré dans le niveau Consommation.

La configuration du point de terminaison de passerelle par défaut reste disponible après l’ajout d’un domaine de passerelle personnalisé.
Portail des développeurs (tous les niveaux à l’exception de la consommation) La valeur par défaut est <apim-service-name>.developer.azure-api.net.
Gestion (niveaux classiques uniquement) La valeur par défaut est <apim-service-name>.management.azure-api.net.
API de configuration de passerelle auto-hébergée (v2) La valeur par défaut est <apim-service-name>.configuration.azure-api.net.
SCM (niveaux classiques uniquement) La valeur par défaut est <apim-service-name>.scm.azure-api.net.

Considerations

  • Vous pouvez mettre à jour n’importe lequel des points de terminaison pris en charge dans votre niveau de service. En règle générale, les clients mettent à jour les points de terminaison Passerelle (cette URL est utilisée pour appeler les API exposées via Gestion des API) et Portail des développeurs (URL du portail des développeurs).
  • Le point de terminaison de passerelle par défaut reste disponible après la configuration d’un nom de domaine de passerelle personnalisé et ne peut pas être supprimé. Pour les autres points de terminaison Gestion des API (tels que le Portail des développeurs) que vous configurez avec un nom de domaine personnalisé, le point de terminaison par défaut n’est plus disponible.
  • Seuls les propriétaires d’instance API Management peuvent utiliser des points de terminaison Gestion et SCM en interne. Ces points de terminaison sont moins souvent affectés à un nom de domaine personnalisé.
  • Toutefois, les niveaux Premium et Developerprennent en charge la définition de plusieurs noms d’hôte pour le point de terminaison Passerelle.
  • Les noms de domaine génériques, *.contoso.com par exemple, sont pris en charge à tous les niveaux, à l’exception du niveau Consommation. Un certificat spécifique du sous-domaine (par exemple, api.contoso.com) est prioritaire sur un certificat générique (*.contoso.com) pour les requêtes vers api.contoso.com.
  • Lors de la configuration d’un domaine personnalisé pour le portail des développeurs, vous pouvez activer CORS pour le nouveau nom de domaine. Cela est nécessaire pour que les visiteurs du portail des développeurs utilisent la console interactive dans les pages de référence de l’API.

Options de certificat de domaine

Gestion des API prend en charge les certificats TLS personnalisés ou les certificats importés à partir de Azure Key Vault. Vous pouvez également activer un certificat géré gratuit.

Warning

Si vous avez besoin d'ancrage de certificat, utilisez un nom de domaine personnalisé et un certificat personnalisé ou un certificat Key Vault, et non le certificat par défaut ou le certificat managé gratuit. Nous vous déconseillons de prendre une dépendance dure sur un certificat que vous ne gérez pas.

Si vous disposez déjà d’un certificat privé provenant d’un fournisseur tiers, vous pouvez le charger dans votre instance Gestion des API. Il doit répondre aux exigences suivantes. (Si vous activez le certificat gratuit géré par Gestion des API, il répond déjà à ces exigences.)

  • Être exporté en tant que fichier PFX, chiffré par Triple-DES et protégé par un mot de passe facultatif.
  • Contenir une clé privée d’au moins 2048 bits de long
  • Contient tous les certificats intermédiaires et le certificat racine dans la chaîne de certificats.

Définir un nom de domaine personnalisé (portail)

Choisissez les étapes en fonction du certificat de domaine que vous souhaitez utiliser.

  1. Accédez à votre instance Gestion des API dans le portail Azure.
  2. Dans le volet de navigation de gauche, sélectionnez Domaines personnalisés.
  3. Sélectionnez +Ajouter ou sélectionnez un point de terminaison existant que vous souhaitez mettre à jour.
  4. Dans la fenêtre de droite, sélectionnez le Type de point de terminaison pour le domaine personnalisé.
  5. Dans la zone Nom d’hôte, spécifiez le nom que vous souhaitez utiliser. Par exemple : api.contoso.com.
  6. Sous Certificat, sélectionnez Personnalisé.
  7. Sélectionnez Fichier de certificat pour sélectionner et charger un certificat.
  8. Chargez un fichier .PFX valide et fournissez son Mot de passe si le certificat est protégé par un mot de passe.
  9. Lors de la configuration d’un point de terminaison de passerelle, sélectionnez ou désélectionnez d’autres options si nécessaire, notamment Négocier le certificat client ou Liaison SSL par défaut. Configurer le domaine de passerelle avec un certificat personnalisé
  10. Sélectionnez Ajouter ou Mettre à jour pour un point de terminaison existant.
  11. Cliquez sur Enregistrer.

Configuration de DNS

Configurez votre fournisseur DNS pour mapper votre nom de domaine personnalisé au nom de domaine par défaut de votre instance Gestion des API.

CNAME record

Configurez un enregistrement CNAME qui pointe de votre nom de domaine personnalisé (par exemple, api.contoso.com) vers le nom d’hôte de votre service Gestion des API (par exemple, yourapim-service-name.azure-api.net). Un enregistrement CNAME est plus stable qu’un enregistrement A au cas où l’adresse IP change. Pour plus d’informations, consultez les adresses IP d'Gestion des API Azure et la FAQ sur l'API Management.

Note

Certains registrars de domaines vous permettent uniquement de mapper des sous-domaines à l’aide d’un enregistrement CNAME, comme www.contoso.com, et non des noms racines, comme contoso.com. Pour plus d’informations sur les enregistrements CNAME, consultez la documentation fournie par votre registrar ou le document Domain Names – Implementation and Specification d’IETF.

Synchronisation et résolution des problèmes de certificat pour les certificats Azure Key Vault-backed

Lorsque vous utilisez un certificat Azure Key Vault-backed pour un domaine personnalisé, Gestion des API fournit des contrôles et des diagnostics pour vous aider à conserver les certificats synchronisés et à résoudre rapidement les problèmes d’accès.

Par exemple, en raison d’un changement de configuration ou d’un problème de connectivité, votre instance Gestion des API peut ne pas pouvoir extraire un certificat de nom d’hôte à partir de Azure Key Vault après la mise à jour ou la rotation d’un certificat. Lorsque cela se produit, votre instance Gestion des API continue d’utiliser un certificat mis en cache jusqu’à ce qu’elle reçoive un certificat mis à jour. Si le certificat mis en cache expire, le trafic d’exécution vers la passerelle est bloqué. Tout service en amont tel qu’Application Gateway qui utilise la configuration du certificat de nom d’hôte peut également bloquer le trafic d’exécution vers la passerelle lorsqu’un certificat mis en cache expiré est utilisé.

Utilisez les contrôles et diagnostics suivants pour synchroniser vos certificats et éviter ou réduire les temps d’arrêt.

Synchroniser des certificats

Sélectionnez Synchroniser des certificats dans la barre de commandes pour démarrer manuellement la synchronisation des certificats lorsque les empreintes de certificat ont changé. Cette option vous permet d’éviter d’attendre la tâche de synchronisation automatisée, qui s’exécute généralement toutes les 3 à 4 heures.

Screenshot de la commande pour synchroniser les certificats de nom d’hôte à partir de Azure Key Vault dans le portail.

Afficher les journaux de synchronisation

Sélectionnez Afficher les journaux de synchronisation dans la barre de commandes pour ouvrir un panneau avec des informations détaillées sur la cause racine lors de l’échec de la synchronisation des certificats. Ces journaux de logs vous aident à diagnostiquer et à résoudre les problèmes de synchronisation plus rapidement.

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

Gestion des API affiche des avertissements proactifs lorsqu’il détecte les problèmes d’accès entre votre instance Gestion des API et le coffre de clés utilisé par le domaine personnalisé. Ces problèmes d’accès provoquent souvent des échecs de synchronisation de certificats.

Si un avertissement s’affiche, sélectionnez Restaurer pour corriger automatiquement l’accès en fonction de votre modèle d’autorisation key vault. Selon le modèle, Gestion des API effectue l’une des actions suivantes pour restaurer l’accès :

  • Attribue le rôle Utilisateur des secrets du coffre de clés Azure pour un coffre de clés basé sur RBAC dans Azure.
  • Octroie l’autorisation GET pour un coffre de clés basé sur une stratégie d’accès.

Conseils de dépannage supplémentaires pour la rotation des certificats ayant échoué à partir de Azure Key Vault

  • Vérifiez que l’identité managée utilisée pour accéder au coffre de clés existe.

  • Si votre instance Gestion des API est déployée dans un réseau virtuel, confirmez la connectivité sortante à la balise de service AzureKeyVault.

Réponse du serveur proxy Gestion des API avec les certificats SSL durant l’établissement d’une liaison TLS

Lorsque vous configurez un domaine personnalisé pour le point de terminaison de passerelle, vous pouvez définir des propriétés supplémentaires qui déterminent la façon dont Gestion des API répond avec un certificat de serveur, en fonction de la requête du client.

Clients appelant avec l’en-tête Indication du nom du serveur (SNI)

Si vous avez un ou plusieurs domaines personnalisés configurés pour le point de terminaison de passerelle, Gestion des API peut répondre aux requêtes HTTPS à partir de l’un ou l’autre :

  • Domaine personnalisé (par exemple, contoso.com)
  • Domaine par défaut (par exemple, apim-service-name.azure-api.net).

En fonction des informations contenues dans l’en-tête SNI, API Management répond avec le certificat de serveur approprié.

Clients appelant sans l’en-tête SNI

Si vous utilisez un client qui n’envoie pas l’en-tête SNI, API Management crée des réponses en fonction de la logique suivante :

  • Si le service n’a qu’un seul domaine personnalisé configuré pour la passerelle, le certificat par défaut est le certificat émis pour le domaine personnalisé de la passerelle.

  • Si le service a configuré plusieurs domaines personnalisés pour la passerelle (pris en charge dans les niveaux Développeur et Premium), vous pouvez désigner le certificat par défaut en définissant la propriété defaultSslBinding sur true ("defaultSslBinding":"true"). Dans le portail, cochez la case Liaison SSL par défaut.

    Si vous ne définissez pas la propriété, le certificat par défaut est le certificat émis pour le domaine de passerelle par défaut hébergé sur *.azure-api.net.

Prise en charge pour la requête PUT/POST avec une charge utile de grande taille

Le serveur proxy de Gestion des API prend en charge les requêtes avec des charges utiles de grande taille (>40 ko) lors de l’utilisation de certificats côté client dans le protocole HTTPS. Pour éviter que la requête du serveur ne gèle, vous pouvez définir la propriété negotiateClientCertificate sur true ("negotiateClientCertificate": "true") sur le nom d’hôte de la passerelle. Dans le portail, cochez la case Négocier le certificat client.

Si la propriété est définie sur true, le certificat client est demandé au moment de la connexion SSL/TLS, avant tout échange de requête HTTP. Étant donné que le paramètre s’applique au niveau du nom d’hôte de la passerelle, toutes les demandes de connexion demandent le certificat client. Vous pouvez contourner cette limitation et configurer jusqu’à 20 domaines personnalisés pour la passerelle (uniquement pris en charge dans le niveau Premium).

Limitation du nom de domaine personnalisé dans les niveaux v2

Actuellement, dans les niveaux Standard v2 et Premium v2, Gestion des API nécessite un nom DNS résolvable publiquement pour autoriser le trafic vers le point de terminaison de passerelle. Si vous configurez un nom de domaine personnalisé pour le point de terminaison de passerelle, ce nom doit être résolu publiquement, et non limité à une zone DNS privée.

Pour contourner ce problème dans les scénarios où vous limitez l’accès public à la passerelle et que vous configurez un nom de domaine privé, vous pouvez configurer Application Gateway pour recevoir le trafic au niveau du nom de domaine privé et le router vers le point de terminaison de passerelle de l’instance Gestion des API. Pour obtenir un exemple d’architecture, consultez ce dépôt GitHub.

Contenu connexe

  • Last updated on