Tutoriel : Stocker et utiliser des informations d’identification Azure Cosmos DB avec Azure Key Vault

  • Article

S’APPLIQUE À : NoSQL MongoDB Cassandra Gremlin Table

Important

Il est recommandé d’accéder à Azure Cosmos DB en utilisant une identité managée affectée par le système. Si la solution d’identité managée et la solution basée sur le certificat ne répondent pas à vos besoins, utilisez la solution Azure Key Vault mentionnée dans cet article.

Si vous utilisez Azure Cosmos DB comme base de données, vous vous connectez aux bases de données, au conteneur et aux éléments à l’aide d’un SDK, du point de terminaison d’API et de la clé primaire ou secondaire.

Il n’est pas recommandé de stocker l’URI du point de terminaison et les clés en lecture-écriture sensibles directement dans le code de l’application ou le fichier de configuration. L’idéal consiste à lire ces données à partir de variables d’environnement au sein de l’hôte. Dans Azure App Service, les paramètres d’application vous permettent d’injecter des informations d’identification d’exécution pour votre compte Azure Cosmos DB sans que les développeurs n’aient besoin de stocker ces informations d’identification sous forme de texte clair non sécurisé.

Azure Key Vault s’appuie sur cette bonne pratique en vous permettant de stocker ces informations d’identification de manière sécurisée tout en donnant à des services comme Azure App Service un accès managé aux informations d’identification. Azure App Service lit en toute sécurité vos informations d’identification issues d’Azure Key Vault et les injecte dans votre application en cours d’exécution.

Cette bonne pratique permet aux développeurs de stocker les informations d’identification pour des outils comme l’émulateur Azure Cosmos DB ou Essayer Azure Cosmos DB gratuitement pendant le développement. Ensuite, l’équipe des opérations peut veiller à ce que les paramètres de production appropriés soient injectés au moment de l’exécution.

Dans ce tutoriel, vous allez apprendre à :

  • Créer une instance Azure Key Vault
  • Ajouter des informations d’identification Azure Cosmos DB en tant que secrets au coffre de clés
  • Créer et inscrire une ressource Azure App Service et accorder des autorisations de « lecture de clé »
  • Injecter des secrets de coffre de clés dans la ressource App Service

Notes

Ce tutoriel et l’exemple d’application utilisent un compte Azure Cosmos DB for NoSQL. Vous pouvez effectuer la plupart des mêmes étapes à l’aide d’autres API.

Prérequis

Avant de commencer : Obtenir des informations d’identification Azure Cosmos DB

Avant de commencer, vous allez obtenir les informations d’identification de votre compte existant.

  1. Accédez à la page du portail Azure du compte Azure Cosmos DB for NoSQL existant.

  2. Dans la page du compte d’Azure Cosmos DB for NoSQL, sélectionnez l’option de menu de navigation Clés.

    Capture d’écran d’une page de compte d’API SQL Azure Cosmos DB. L’option Clés est mise en surbrillance dans le menu de navigation.

  3. Enregistrez les valeurs des champs URI et CLÉ PRIMAIRE. Vous allez utiliser ces valeurs plus tard dans ce tutoriel.

    Capture d’écran de la page Clés avec diverses informations d’identification pour un compte d’API SQL Azure Cosmos DB.

Créer une ressource Azure Key Vault

Tout d’abord, créez un coffre de clés pour stocker les informations d’identification de votre API pour NoSQL.

  1. Connectez-vous au portail Azure.

  2. Sélectionnez Créer une ressource > Sécurité > Coffre de clés.

  3. Dans la page Créer un coffre de clés, indiquez les informations suivantes :

    Paramètre Description
    Abonnement Sélectionnez l’abonnement Azure à utiliser pour ce compte Azure Cosmos.
    Groupe de ressources Sélectionnez un groupe de ressources ou sélectionnez Créer, puis entrez un nom unique pour le nouveau groupe de ressources.
    Nom du coffre de clés Entrez un nom globalement unique pour votre point de terminaison.
    Région Sélectionnez la zone géographique dans laquelle héberger votre compte Azure Cosmos DB. Utilisez l’emplacement le plus proche de vos utilisateurs pour leur donner l’accès le plus rapide possible aux données.
    Niveau tarifaire Sélectionnez Standard.

  4. Conservez les valeurs par défaut des paramètres restants.

  5. Sélectionnez Revoir + créer.

  6. Passez en revue les paramètres que vous fournissez, puis sélectionnez Créer. La création du compte prend quelques minutes. Attendez que la page du portail affiche Votre déploiement est terminé.

Ajouter des clés d’accès Azure Cosmos DB au coffre de clés

À présent, stockez vos informations d’identification Azure Cosmos DB en tant que secrets dans le coffre de clés.

  1. Sélectionnez Accéder à la ressource pour accéder à la page de la ressource Azure Key Vault.

  2. Dans la page de la ressource Azure Key Vault, sélectionnez l’option de menu Secrets.

  3. Sélectionnez Générer/importer dans le menu.

    Capture d’écran de l’option Générer/importer dans le menu d’un coffre de clés.

  4. Dans la page Créer un secret, indiquez les informations suivantes :

    Paramètre Description
    Options de chargement Manuel
    Nom cosmos-endpoint
    Valeur du secret Entrez l’URI que vous avez copié précédemment dans ce tutoriel.

    Capture d’écran de la boîte de dialogue Créer un secret dans le portail Azure avec les détails du secret d’un URI.

  5. Sélectionnez Créer pour créer le secret cosmos-endpoint.

  6. Sélectionnez une nouvelle fois Générer/importer dans le menu. Dans la page Créer un secret, indiquez les informations suivantes :

    Paramètre Description
    Options de chargement Manuel
    Nom cosmos-readwrite-key
    Valeur du secret Entrez la CLÉ PRIMAIRE que vous avez copiée précédemment dans ce tutoriel.

    Capture d’écran de la boîte de dialogue Créer un secret dans le portail Azure avec les détails du secret d’une CLÉ PRIMAIRE.

  7. Sélectionnez Créer pour créer le secret cosmos-readwrite-key.

  8. Une fois les secrets créés, consultez-les dans la liste des secrets de la page Secrets.

    Capture d’écran de la liste des secrets d’un coffre de clés.

  9. Sélectionnez chaque clé, sélectionnez la dernière version, puis copiez l’identificateur de secret. Vous allez utiliser l’identificateur des secrets cosmos-endpoint et cosmos-readwrite-key plus tard dans ce tutoriel.

    Conseil

    L’identificateur de secret aura le format https://<key-vault-name>.vault.azure.net/secrets/<secret-name>/<version-id>. Par exemple, si le nom du coffre de clés est msdocs-key-vault, le nom de la clé est cosmos-readwrite-key et la version est 83b995e363d947999ac6cf487ae0e12e, alors l’identificateur de secret est https://msdocs-key-vault.vault.azure.net/secrets/cosmos-readwrite-key/83b995e363d947999ac6cf487ae0e12e.

    Capture d’écran d’un identificateur de secret pour un secret de coffre de clés nommé cosmos-readwrite-key.

Créer et inscrire une application web Azure auprès d’Azure Key Vault

Dans cette section, créez une application web Azure, déployez un exemple d’application, puis inscrivez l’identité managée de l’application web auprès d’Azure Key Vault.

  1. Créez un dépôt GitHub à l’aide du modèle cosmos-db-nosql-dotnet-sample-web-environment-variables.

  2. Dans le portail Azure, sélectionnez Créer une ressource > Web > Application web.

  3. Dans la page Créer une application web et sous l’onglet Informations de base, indiquez les informations suivantes :

    Paramètre Description
    Abonnement Sélectionnez l’abonnement Azure à utiliser pour ce compte Azure Cosmos.
    Groupe de ressources Sélectionnez un groupe de ressources ou sélectionnez Créer, puis entrez un nom unique pour le nouveau groupe de ressources.
    Nom Entrez un nom globalement unique pour votre application web.
    Publier Sélectionnez Code.
    Pile d’exécution Sélectionnez .NET 6 (LTS).
    Système d’exploitation Sélectionnez Windows.
    Région Sélectionnez la zone géographique dans laquelle héberger votre compte Azure Cosmos DB. Utilisez l’emplacement le plus proche de vos utilisateurs pour leur donner l’accès le plus rapide possible aux données.

  4. Conservez les valeurs par défaut des paramètres restants.

  5. Sélectionnez Suivant : Déploiement.

  6. Sous l’onglet Déploiement, indiquez les informations suivantes :

    Paramètre Description
    Déploiement continu Sélectionnez Activer.
    Compte GitHub Sélectionnez Autoriser. Suivez les invites d’autorisation de compte GitHub pour accorder à Azure l’autorisation de lire votre dépôt GitHub nouvellement créé.
    Organisation Sélectionnez l’organisation pour votre nouveau dépôt GitHub.
    Référentiel Sélectionnez le nom de votre nouveau dépôt GitHub.
    Branche Sélectionnez principal.

  7. Sélectionnez Revoir + créer.

  8. Passez en revue les paramètres que vous fournissez, puis sélectionnez Créer. La création du compte prend quelques minutes. Attendez que la page du portail affiche Votre déploiement est terminé.

  9. Vous devrez éventuellement attendre quelques minutes supplémentaires pour que l’application web soit initialement déployée. Dans la page de la ressource Azure Web App, sélectionnez Parcourir pour voir l’état par défaut de l’application.

    Capture d’écran de l’application web dans son état par défaut sans informations d’identification.

  10. Sélectionnez l’option de menu de navigation Identité.

  11. Dans la page Identité, sélectionnez Activé pour Identité managée affectée par le système, puis sélectionnez Enregistrer.

    Capture d’écran de l’identité managée affectée par le système en cours d’activation à partir de la page Identité.

Injecter des secrets Azure Key Vault en tant que paramètres de l’application web Azure

Enfin, injectez les secrets stockés dans votre coffre de clés en tant que paramètres d’application dans l’application web. Les paramètres d’application injectent à leur tour les informations d’identification dans l’application au moment de l’exécution sans les stocker en texte clair.

  1. Revenez à la page du coffre de clés dans le portail Azure. Sélectionnez Stratégies d’accès à partir du menu de navigation.

  2. Dans la page Stratégies d’accès, sélectionnez Créer dans le menu.

    Capture d’écran de l’option Créer dans le menu Stratégies d’accès.

  3. Sous l’onglet Autorisations de la page Créer une stratégie d’accès, sélectionnez l’option Obtenir dans la section Autorisations du secret. Sélectionnez Suivant.

    Capture d’écran de l’autorisation Obtenir activée pour les autorisations du secret.

  4. Sous l’onglet Principal, sélectionnez le nom de l’application web que vous avez créée précédemment dans ce tutoriel. Sélectionnez Suivant.

    Capture d’écran d’une identité managée d’application web affectée à une autorisation.

    Notes

    Dans cet exemple de capture d’écran, l’application web porte le nom msdocs-dotnet-web.

  5. Sélectionnez encore Suivant pour ignorer l’onglet Application. Sous l’onglet Vérifier + créer, passez en revue les paramètres que vous avez indiqués, puis sélectionnez Créer.

  6. Revenez à la page de l’application web dans le portail Azure. Sélectionnez Configuration dans le menu de navigation.

  7. Dans la page Configuration, sélectionnez Nouveau paramètre d’application. Dans la boîte de dialogue Ajouter/modifier le paramètre d’application, entrez les informations suivantes :

    Paramètre Description
    Nom CREDENTIALS__ENDPOINT
    Clé Obtenez l’identificateur de secret pour le secret cosmos-endpoint dans votre coffre de clés que vous avez créé précédemment dans ce tutoriel. Entrez l’identificateur au format suivant : @Microsoft.KeyVault(SecretUri=<secret-identifier>).

    Conseil

    Vérifiez que la variable d’environnement a pour valeur un double trait de soulignement (__) au lieu d’un seul. Le double trait de soulignement est un délimiteur de clé pris en charge par .NET sur toutes les plateformes. Pour plus d’informations, consultez la configuration des variables d’environnement.

    Notes

    Par exemple, si l’identificateur de secret est https://msdocs-key-vault.vault.azure.net/secrets/cosmos-endpoint/69621c59ef5b4b7294b5def118921b07, alors la référence est @Microsoft.KeyVault(SecretUri=https://msdocs-key-vault.vault.azure.net/secrets/cosmos-endpoint/69621c59ef5b4b7294b5def118921b07).

    Capture d’écran de la boîte de dialogue Ajouter/modifier le paramètre d’application avec un nouveau paramètre d’application faisant référence à un secret de coffre de clés.

  8. Sélectionnez OK pour conserver le nouveau paramètre d’application.

  9. Sélectionnez encore Nouveau paramètre d’application. Dans la boîte de dialogue Ajouter/modifier le paramètre d’application, entrez les informations suivantes, puis sélectionnez OK :

    Paramètre Description
    Nom CREDENTIALS__KEY
    Clé Obtenez l’identificateur de secret pour le secret cosmos-readwrite-key dans votre coffre de clés que vous avez créé précédemment dans ce tutoriel. Entrez l’identificateur au format suivant : @Microsoft.KeyVault(SecretUri=<secret-identifier>).

  10. Revenez à la page Configuration, puis sélectionnez Enregistrer pour mettre à jour les paramètres de l’application web.

    Capture d’écran de l’option Enregistrer dans le menu de la page Configuration.

  11. Attendez quelques minutes que l’application web redémarre avec les nouveaux paramètres d’application. À ce stade, les nouveaux paramètres d’application doivent indiquer qu’ils correspondent à une référence de coffre de clés.

    Capture d’écran de la désignation Référence du coffre de clés sur deux paramètres d’application dans une application web.

  12. Dans le menu de navigation, sélectionnez Vue d’ensemble. Sélectionnez Parcourir pour voir l’application avec les informations d’identification renseignées.

    Capture d’écran de l’application web avec des informations d’identification de compte Azure Cosmos DB for NoSQL valides.

Étapes suivantes