Azure APIM : diagnostiquer le TLS backend avant de désactiver la validation du certificat

Une API publiée par Azure API Management commence à retourner des 500 ou 502 alors que le backend répond lorsqu’il est appelé directement. Le certificat a été renouvelé quelques heures plus tôt. La correction proposée arrive vite : désactiver la validation de la chaîne ou du nom dans la configuration du backend APIM.

Cette option peut rétablir le trafic, mais elle supprime précisément le contrôle qui prouve qu’APIM parle au bon serveur. Le cas fil rouge est une API interne dont le backend HTTPS utilise un certificat d’entreprise. Le runbook doit distinguer chaîne incomplète, autorité non reconnue, hostname incorrect, certificat expiré, problème de protocole ou erreur applicative, puis décider entre correction du certificat, ajustement borné du backend, restauration de la version précédente ou rollback APIM.

Figer un appel témoin et la fenêtre de changement

Commencez par un appel reproductible sans données sensibles. Conservez son chemin, son opération APIM, son CorrelationId, la région de gateway, le code client, le code backend s’il existe et les horodatages UTC. Ajoutez un appel témoin vers une opération saine du même backend, ou vers la même opération sur une région non affectée.

incident: INC-APIM-214
first_seen_utc: 2026-09-05T13:20:00Z
last_known_success_utc: 2026-09-05T12:48:00Z

apim:
service: apim-platform-prod
api: orders-v2
operation: GET /orders/{id}
backend_id: orders-api-prod
gateway_region: westeurope

backend:
configured_url: https://orders-api.internal.example.net
expected_hostname: orders-api.internal.example.net
recent_change: backend-certificate-renewal

evidence:
- APIM gateway log and CorrelationId
- backend entity before and after the change
- certificate leaf and presented chain
- DNS answer from an approved probe path
- backend access log for the same timestamp
- last known APIM configuration and certificate version

Ne modifiez pas encore skipCertificateChainValidation ni skipCertificateNameValidation. Capturez leur valeur actuelle. Une exception déjà active change le diagnostic : APIM peut atteindre le backend tout en ne vérifiant plus une partie de son identité.

Prouver que l’échec se produit pendant le handshake

Un 502 vu par le client n’est pas une preuve TLS. APIM peut échouer avant l’appel backend, pendant la connexion, dans une policy, sur timeout, ou après une réponse invalide. Les journaux de gateway permettent de séparer ces étapes.

let incidentStart = datetime(2026-09-05T13:10:00Z);
let incidentEnd = datetime(2026-09-05T14:00:00Z);
ApiManagementGatewayLogs
| where TimeGenerated between (incidentStart .. incidentEnd)
| where ApiId == "orders-v2" or BackendId == "orders-api-prod"
| project TimeGenerated, CorrelationId, Region, OperationId,
        ResponseCode, BackendResponseCode, BackendTime, BackendUrl,
        LastErrorSource, LastErrorReason, LastErrorMessage
| order by TimeGenerated desc

Cherchez une erreur de connexion backend cohérente avec le renouvellement et comparez-la aux logs du serveur. Si le backend possède une requête portant le même identifiant ou le même instant, le handshake a probablement abouti : contrôlez alors le code HTTP, la policy et l’application. Si aucun BackendResponseCode n’existe et que l’erreur de gateway désigne la connexion ou le certificat, la piste TLS devient prioritaire.

Évitez de filtrer uniquement sur le texte exact d’une erreur. Les messages peuvent évoluer. La combinaison LastErrorSource, LastErrorReason, absence de réponse backend, région et début de l’incident est une preuve plus robuste.

Lire la configuration backend réellement déployée

Le backend effectif peut venir d’une entité APIM appelée par set-backend-service, d’une URL définie directement sur l’API, ou d’une policy conditionnelle. Exportez l’entité et les policies aux scopes global, produit, API et opération avant de conclure.

SUBSCRIPTION_ID="<subscription-id>"
RG="rg-api-platform-prod"
APIM="apim-platform-prod"
BACKEND_ID="orders-api-prod"
API_VERSION="2024-05-01"

BACKEND_URI="https://management.azure.com/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${RG}/providers/Microsoft.ApiManagement/service/${APIM}/backends/${BACKEND_ID}?api-version=${API_VERSION}"

az rest --method get --url "$BACKEND_URI" --query '{id:id,url:properties.url,protocol:properties.protocol,tls:properties.tls,credentials:properties.credentials}' --output json

az apim api policy show --resource-group "$RG" --service-name "$APIM" --api-id "orders-v2" --output json

Vérifiez l’URL complète, pas seulement le certificat attendu. Un backend configuré avec une IP, un alias DNS différent ou un ancien hostname peut présenter un certificat valide dont le nom ne correspond pas. Vérifiez aussi qu’une policy ne redirige pas certaines opérations vers une autre entité backend.

Séparer nom, chaîne, validité et protocole

Traitez le handshake comme quatre contrôles indépendants :

• le nom demandé doit correspondre au SAN du certificat présenté ;
• la chaîne présentée doit remonter vers une autorité approuvée par la gateway ;
• chaque certificat utile doit être dans sa période de validité et adapté à l’usage serveur ;
• le backend et APIM doivent partager une version et des paramètres TLS compatibles.

Depuis une machine de diagnostic autorisée à suivre un chemin réseau comparable, inspectez la résolution DNS et le certificat présenté avec le hostname réel. Ce test ne reproduit pas l’environnement managé d’APIM, mais il détecte rapidement un mauvais endpoint, un SAN absent ou une chaîne incomplète.

HOST="orders-api.internal.example.net"
PORT="443"

getent ahosts "$HOST"

openssl s_client -connect "${HOST}:${PORT}" -servername "$HOST" -showcerts -verify_return_error </dev/null

openssl s_client -connect "${HOST}:${PORT}" -servername "$HOST" </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -serial -dates -ext subjectAltName

Le paramètre -servername est important : sans SNI, un reverse proxy peut présenter le certificat par défaut et fabriquer un faux diagnostic. Testez ensuite avec la chaîne de confiance attendue si elle est privée. Une feuille correcte ne compense pas un intermédiaire absent ; le serveur doit généralement présenter les intermédiaires nécessaires.

Corréler le renouvellement au certificat servi

Un certificat peut être renouvelé dans Key Vault, dans le load balancer ou sur le serveur sans être celui effectivement présenté au trafic APIM. Comparez l’empreinte et la série observées sur chaque endpoint ou région avec l’objet attendu. Contrôlez aussi le moment de la bascule, la propagation et le comportement du pool backend.

Construisez une matrice courte :

Expected certificate
hostname and SAN
issuer and chain
serial or fingerprint
notBefore / notAfter
deployment target and version

Observed from approved probe
resolved IP
hostname sent as SNI
leaf serial or fingerprint
presented intermediates
verify return code

Observed by APIM
gateway region
backend URL and BackendId
first failure UTC
LastErrorReason and LastErrorMessage
backend response present: yes/no

Si une seule région APIM échoue, ne concluez pas immédiatement à un problème de confiance global. Vérifiez la réponse DNS et le certificat servi par les backends de cette région. Si toutes les régions échouent exactement après une modification APIM, comparez d’abord l’entité backend et les policies.

Choisir la correction la plus étroite

La correction dépend du contrôle qui échoue :

Hostname absent du SAN
Corriger l'URL backend ou émettre un certificat pour le hostname réel
Ne pas désactiver la validation du nom pour masquer un alias mal conçu

Chaîne publique incomplète
Configurer le serveur pour présenter les intermédiaires nécessaires
Revalider depuis plusieurs chemins avant remise en trafic

Autorité privée attendue
Configurer la CA personnalisée selon le tier et le type de gateway utilisés
Prouver le périmètre de confiance et conserver la validation du nom

Certificat expiré ou mauvaise version servie
Restaurer le certificat précédent encore valide ou terminer le renouvellement
Vérifier chaque endpoint avant de retirer l'ancienne version

Paramètre TLS incompatible
Restaurer la dernière combinaison connue ou corriger le backend
Tester les clients à certificat séparément avant toute activation TLS 1.3

Erreur HTTP après handshake
Arrêter de modifier les certificats
Diagnostiquer policy, identité, timeout et application

Les mécanismes de CA personnalisée diffèrent entre gateways managées, self-hosted gateways et tiers APIM. Vérifiez le support du tier réel avant de préparer le changement. Une CA ajoutée au service managé ne prouve pas automatiquement que la même confiance existe sur une gateway self-hosted.

Encadrer toute exception temporaire

La désactivation de validation n’est acceptable que si l’architecture impose explicitement un certificat autosigné, que le tier le nécessite, et que le risque est compris. Elle doit cibler une entité backend précise, conserver autant de contrôles que possible et avoir une expiration, un propriétaire et un rollback. Ne désactivez pas simultanément chaîne et nom par commodité.

Avant l’exception, conservez l’objet backend complet. Après le changement, rejouez un appel positif et un appel négatif : le hostname légitime doit fonctionner, tandis qu’un backend voisin ou un nom non prévu ne doit pas devenir une cible valide. L’exception ne doit jamais servir à compenser une chaîne publique cassée ou un certificat expiré.

Valider le rollout et le rollback

Déployez d’abord sur une API ou une révision canari qui suit le même chemin. Corrélez l’appel de bout en bout, puis observez les erreurs TLS et les codes backend par région avant d’élargir.

Validation avant rollout
BackendId, URL et policies exportés
Certificat attendu et certificat servi concordent
SAN, chaîne, dates et protocole vérifiés
Cause visible dans les logs APIM
Appel témoin et test négatif définis
Objet de rollback prêt

Succès
Appel APIM retourne le code applicatif attendu
Backend reçoit le même CorrelationId
Aucun nouveau groupe d'erreurs TLS par région
Validation de chaîne et de nom restent actives, sauf exception approuvée

Rollback immédiat
Une région présente encore un certificat inattendu
Le test négatif devient joignable
Le backend effectif diffère de l'objet validé
L'exception TLS couvre plus d'APIs que prévu
Les erreurs changent de forme sans preuve de handshake réussi

Le rollback consiste à restaurer l’entité backend, la policy ou la version de certificat connue, puis à rejouer les mêmes preuves. Désactiver une API entière peut contenir le risque, mais ce n’est pas le retour arrière du changement TLS.

Conclusion

Une erreur APIM après renouvellement de certificat ne justifie pas de supprimer un contrôle TLS. Il faut d’abord prouver l’étape en échec, lire le backend effectif, tester le hostname avec SNI, reconstruire la chaîne et corréler le certificat réellement servi aux logs de gateway.

La décision devient alors simple à exploiter : corriger le SAN ou la chaîne, configurer une CA privée supportée, restaurer le certificat précédent, revenir sur un paramètre TLS, ou traiter une erreur applicative qui n’avait rien de TLS. La remise en production est valide lorsque l’appel positif passe, le test négatif reste bloqué et la validation du certificat reste explicable.