Comment sécuriser les API à l'aide d'une authentification par certificat client dans la Gestion des API

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

Le service Gestion des API permet de sécuriser l’accès aux API (client vers Gestion des API) à l’aide de certificats clients et d’une authentification TLS mutuelle. Vous pouvez valider les certificats présentés par le client qui se connecte, et vérifier les propriétés de certificat par rapport aux valeurs souhaitées à l’aide d’expressions de stratégie.

Pour savoir comment sécuriser l’accès au service back-end d’une API à l’aide de certificats clients (Gestion des API vers le back-end), consultez Sécuriser les services back-end à l’aide d’une authentification par certificat client.

Pour obtenir une vue d’ensemble conceptuelle de l’autorisation des API, consultez Authentification et autorisation aux API dans le service Gestion des API.

Options de certificat

Pour la validation des certificats, le service Gestion des API peut effectuer une vérification par rapport aux certificats gérés dans votre instance Gestion des API. Si vous choisissez d’utiliser Gestion des API pour gérer les certificats clients, vous disposez des options suivantes :

• Référencer un certificat géré dans Azure Key Vault
• Ajouter un fichier de certificat directement dans Gestion des API

L’utilisation de certificats de coffre de clés est recommandée, car elle permet d’améliorer la sécurité de Gestion des API :

• Les certificats stockés dans des coffres de clés peuvent être réutilisés entre les services.
• Des stratégies d’accès granulaires peuvent être appliquées à des certificats stockés dans des coffres de clés.
• Les certificats 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, un certificat dans Gestion des API est mis à jour dans un délai de quatre heures. Vous pouvez également actualiser manuellement le certificat à l’aide du portail Azure ou par le biais de l’API REST de gestion.

Prérequis

• Si vous n’avez pas encore créé d’instance de service Gestion des API, consultez la page Créer une instance de service Gestion des API.

• Vous devez avoir accès au certificat et au mot de passe pour la gestion dans un coffre de clés Azure ou les charger sur le service Gestion des API. Le certificat doit être au format CER ou PFX. Les certificats auto-signés sont autorisés.

  Si vous utilisez un certificat auto-signé, installez également des certificats d’autorités de certification intermédiaires et racines de confiance dans votre instance Gestion des API.

  Notes

  Les certificats d’autorités de certification ne sont pas pris en charge dans le niveau Consommation.

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

1. Si vous n’avez pas encore de coffre de clés, créez-en un. 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.

   Pour créer ou importer un certificat dans le coffre de clés, consultez Démarrage rapide : Définir et récupérer un certificat dans Azure Key Vault à l’aide du portail Azure.

2. Activer une identité managée attribuée par le système ou par l’utilisateur dans l’instance Gestion des API.

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

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

Important

Lorsque vous ajoutez un certificat 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 certificat de coffre de clés dans Gestion des API, veillez à ne pas supprimer le certificat, le coffre de clés ou l’identité managée utilisée pour accéder au coffre de clés.

Pour ajouter un certificat de coffre de clés à Gestion des API :

1. Dans le portail Azure, accédez à votre instance APIM.

2. Sous Sécurité, sélectionnez Certificats.

3. Sélectionnez Certificats>+ Ajouter.

4. Dans ID, entrez le nom de votre choix.

5. Dans Certificat, sélectionnez Coffre de clés.

6. Entrez l’identificateur d’un certificat de coffre de clés ou choisissez Sélectionner pour choisir un certificat dans un coffre de clés.

   Important

   Si vous entrez vous-même l’identificateur d’un certificat de coffre de clés, assurez-vous qu’il ne contient pas d’informations de version. Sinon, le certificat n’est pas automatiquement permuté dans Gestion des API après une mise à jour dans le coffre de clés.

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

8. Sélectionnez Ajouter.

   

9. Sélectionnez Enregistrer.

Téléchargement d'un certificat

Pour charger un certificat client dans Gestion des API :

1. Dans le portail Azure, accédez à votre instance APIM.

2. Sous Sécurité, sélectionnez Certificats.

3. Sélectionnez Certificats>+ Ajouter.

4. Dans ID, entrez le nom de votre choix.

5. Dans Certificat, sélectionnez Personnalisé.

6. Accédez au fichier .pfx du certificat, sélectionnez-le et entrez son mot de passe.

7. Sélectionnez Ajouter.

   

8. Sélectionnez Enregistrer.

Notes

Si vous souhaitez uniquement utiliser le certificat pour authentifier le client avec Gestion des API, vous pouvez charger un fichier CER.

Activer une instance Gestion des API instance pour recevoir et vérifier les certificats clients

Niveau Développeur, De base, Standard ou Premium

Pour recevoir et vérifier des certificats clients avec HTTP/2 dans les niveaux Développeur, Essentiel, Essentiel v2, Standard, Standard v2 ou Premium, vous devez activer le paramètre Négocier le certificat client dans le panneau Domaines personnalisés comme indiqué ci-dessous.

Niveau de consommation

Pour recevoir et vérifier des certificats clients dans le niveau Consommation, vous devez activer le paramètre Demande de certificat client dans le panneau Domaines personnalisés comme indiqué ci-dessous.

Stratégie pour valider le certificat client

Utilisez la stratégie validate-client-certificate pour valider un ou plusieurs attributs d’un certificat client utilisé pour accéder aux API hébergées dans votre instance Gestion des API.

Configurez la stratégie pour valider un ou plusieurs attributs, notamment l’émetteur du certificat, l’objet, l’empreinte, si le certificat est validé par rapport à la liste de révocation en ligne, etc.

Validation de certificat avec des variables de contexte

Vous pouvez également créer des expressions de stratégie avec la context variable pour vérifier les certificats clients. Les exemples des sections suivantes montrent des expressions qui utilisent la propriété context.Request.Certificate et d’autres propriétés context.

Remarque

L’authentification par certificat mutuel peut ne pas fonctionner correctement quand le point de terminaison de la passerelle Gestion des API est exposé via la passerelle applicative. Ceci est dû au fait qu’Application Gateway fonctionne comme un équilibreur de charge de couche 7, établissant une connexion SSL distincte avec le service Gestion des API back-end. Par conséquent, le certificat attaché par le client dans la requête HTTP initiale n’est pas transféré à APIM. Cependant, pour contourner ce problème, vous pouvez transmettre le certificat en utilisant l’option des variables de serveur. Pour obtenir des instructions détaillées, consultez Variables de serveur d’authentification mutuelle.

Important

• À compter de mai 2021, la propriété context.Request.Certificate exige le certificat uniquement lorsque hostnameConfiguration de l’instance de Gestion des API affecte la valeur True à la propriété negotiateClientCertificate. Par défaut, la valeur de negotiateClientCertificate est définie sur False.
• Si la renégociation TLS est désactivée dans votre client, vous pouvez rencontrer des erreurs TLS lorsque vous demandez le certificat à l’aide de la propriété context.Request.Certificate. Si cela se produit, activez les paramètres de renégociation TLS dans le client.
• La renégociation de certification n’est pas prise en charge dans les niveaux Gestion des API v2.

Vérification de l’émetteur et du sujet

Les stratégies suivantes peuvent être configurées pour vérifier l’émetteur et le sujet d’un certificat client :

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify() || context.Request.Certificate.Issuer != "trusted-issuer" || context.Request.Certificate.SubjectName.Name != "expected-subject-name")" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Notes

Pour désactiver la vérification de la liste de révocation de certificats, utilisez context.Request.Certificate.VerifyNoRevocation() et non context.Request.Certificate.Verify(). Si le certificat client est auto-signé, le ou les certificats de l’autorité de certification racine (ou intermédiaire) doivent être chargés dans la Gestion des API pour context.Request.Certificate.Verify() et context.Request.Certificate.VerifyNoRevocation() pour fonctionner.

Vérification de l’empreinte numérique

Les stratégies suivantes peuvent être configurées pour vérifier l’empreinte d’un certificat client :

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify() || context.Request.Certificate.Thumbprint != "DESIRED-THUMBPRINT-IN-UPPER-CASE")" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Notes

Pour désactiver la vérification de la liste de révocation de certificats, utilisez context.Request.Certificate.VerifyNoRevocation() et non context.Request.Certificate.Verify(). Si le certificat client est auto-signé, le ou les certificats de l’autorité de certification racine (ou intermédiaire) doivent être chargés dans la Gestion des API pour context.Request.Certificate.Verify() et context.Request.Certificate.VerifyNoRevocation() pour fonctionner.

Vérification d’une empreinte par rapport aux certificats téléchargés dans la gestion des API

L’exemple suivant montre comment vérifier l’empreinte d’un certificat client par rapport aux certificats téléchargés dans la gestion des API :

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify()  || !context.Deployment.Certificates.Any(c => c.Value.Thumbprint == context.Request.Certificate.Thumbprint))" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Notes

Pour désactiver la vérification de la liste de révocation de certificats, utilisez context.Request.Certificate.VerifyNoRevocation() et non context.Request.Certificate.Verify(). Si le certificat client est auto-signé, le ou les certificats de l’autorité de certification racine (ou intermédiaire) doivent être chargés dans la Gestion des API pour context.Request.Certificate.Verify() et context.Request.Certificate.VerifyNoRevocation() pour fonctionner.

Conseil

Le problème de blocage de certificat client décrit dans cet article peut se manifester de différentes manières, notamment par des demandes qui se figent, des demandes qui génèrent un code d’état 403 Forbidden après une expiration du délai, context.Request.Certificate qui a la valeur null. Ce problème affecte généralement les demandes POST et PUT avec une longueur de contenu d’environ 60 Ko ou plus. Pour éviter que ce problème ne se reproduise, activez le paramètre « Négocier le certificat client » pour les noms d’hôte souhaités dans le panneau « Domaines personnalisés », comme indiqué dans la première image de ce document. Cette fonctionnalité n’est pas disponible dans le niveau Consommation.

Étapes suivantes

• Comment sécuriser les services back-end à l’aide d’une authentification par certificat client
• Guide pratique pour ajouter un certificat d’autorité de certification personnalisé dans la Gestion des API Azure
• En savoir plus sur les stratégies dans Gestion des API