Utiliser le Secret Manager avec l'API REST

Objectif

L'objectif de ce guide est de présenter l'usage de l'API REST pour le Secret Manager.

Prérequis

• Disposer d'un compte client OVHcloud.
• Avoir commandé un domaine OKMS ou créé un premier secret.

En pratique

Description

Le Secret Manager est un produit vous permettant de stocker de manière sécurisée les credentials, clés d'API, clés SSH ou tout autre type de secret nécessaire au fonctionnement de vos applications.

Un secret est une collection d'une ou plusieurs clés/valeurs regroupées au sein d'une version. Chaque modification d'un secret amène la création d'une nouvelle version de ce secret, permettant de remonter dans l'historique des modifications du secret.

Les API REST sont l'un des deux jeux d'API offerts par le Secret Manager avec les API compatibles Hashicorp Vault KV2. Elles sont conçues pour être similaires à l'ensemble des API OVHcloud ainsi qu'aux API OKMS pour le Key Management Service.

Les API REST peuvent être utilisées soit par les API centralisées OVHcloud, soit directement sur le domaine OKMS en région. La seule différence réside dans le chemin d'API exact :

• API centralisée OVHcloud : /v2/okms/resource/{okmsId}/secret/{path}
• API régionalisée OKMS : /api/{okmsId}/v2/secret/{path}

Cette documentation se concentrera sur les API du domaine OKMS en région.

Communiquer avec le domaine OKMS

La communication avec le domaine OKMS pour les actions de chiffrement et de signature est disponible via l'API.

Le domaine OKMS étant régionalisé, l'accès à l'API se fait directement sur la région de celui-ci : https://my-region.okms.ovh.net.

Par exemple, pour un domaine OKMS créé sur la région eu-west-rbx : https://eu-west-rbx.okms.ovh.net.

Il est possible de communiquer avec le domaine OKMS en utilisant :

• L'interface utilisateur Swagger
• La CLI OKMS : https://github.com/ovh/okms-cli
• Le SDK Golang : https://pkg.go.dev/github.com/ovh/okms-sdk-go

Utilisation de l'API OKMS via l'interface utilisateur Swagger

Il est possible d'accéder au swagger correspondant à votre domaine OKMS en cliquant sur le lien présent dans l'espace client OVHcloud au niveau du dashboard de votre domaine OKMS.

Vous êtes alors redirigé sur la version non authentifiée de l'interface utilisateur Swagger, qui est destinée à la documentation de l'API. Si vous souhaitez utiliser l'interface utilisateur Swagger pour effectuer des requêtes sur votre propre domaine OKMS, vous devez basculer vers la version authentifiée, dont le lien se trouve dans la section description :

Les étapes suivantes vous guideront sur la façon de vous authentifier.

Import de vos informations d'identification OKMS dans le navigateur

Pour accéder à l'interface utilisateur Swagger authentifiée, vous devez charger votre certificat d'accès OKMS dans le gestionnaire de certificats du navigateur.

Pour cela, il faut le convertir au format PKCS#12. PKCS#12 est un format binaire permettant de stocker une chaîne de certificats et une clé privée dans un seul fichier chiffré. Il est couramment utilisé pour importer et exporter des certificats et des clés privées, en particulier dans les environnements qui nécessitent un transport sécurisé de ces éléments, tels que les serveurs Web et les applications clientes.

Pour convertir vos informations d'identification au domaine OKMS (normalement nommées ID_certificate.pem et ID_privatekey.pem) en PKCS#12 avec la CLI openssl, utilisez la commande suivante :

openssl pkcs12 -export -in ID_certificate.pem  -inkey ID_privatekey.pem -out client.p12

Vous serez invité à entrer un mot de passe qui sera utilisé pour le chiffrement symétrique du contenu du fichier. Vous devez ensuite l'importer dans votre navigateur Web.

Sur Firefox

• Tapez about:preferences#privacy dans la barre d'adresse.
• Faites défiler vers le bas jusqu'à atteindre une section intitulée Certificats.

• Cliquez sur Afficher les Certificats... pour ouvrir le gestionnaire de certificats.
• Accédez à l'onglet intitulé Vos Certificats, puis cliquez sur Importer... et sélectionnez l'emplacement de votre fichier client.p12.
• Vous serez invité à entrer le mot de passe que vous avez utilisé lors de la création du fichier PKCS#12.
• Après avoir entré le mot de passe, votre certificat sera importé et prêt à l'emploi.

Sur Chrome/Chromium

• Tapez chrome://settings/certificates dans la barre d'adresse.
• Accédez à l'onglet Vos certificats. Cliquez sur Importer et sélectionnez votre fichier client.p12.
• Vous serez invité à entrer le mot de passe que vous avez utilisé lors de la création du fichier PKCS#12.
• Après avoir entré le mot de passe, votre certificat sera importé et prêt à l'emploi.

Accès à l'interface utilisateur Swagger authentifiée

Une fois votre certificat chargé dans votre navigateur, vous pouvez accéder à l'interface utilisateur Swagger authentifiée.

Vous serez invité à vous identifier avec un certificat. Sélectionnez le certificat PKCS#12 précédemment importé dans la liste déroulante.

Vous pouvez maintenant utiliser l'interface utilisateur Swagger de manière interactive.

Créer un secret

Pour créer un secret il est possible d'utiliser l'API suivante :

L'API attend les valeurs suivantes :

Par exemple :

{
  "metadata": {
    "cas_required": true,
    "custom_metadata": {
      "project": "A",
      "team": "X"
    },
    "deactivate_version_after": "10h30m10s",
    "max_versions": 5
  },
  "path": "prod/database/MySQL",
  "version": {
    "data": {
      "login": "admin",
      "password": "my_secret_password",
      "address": {
        "ip": "1.1.1.1"
      },
      "ports": [
        "30",
        "31"
      ]
    }
  }
}

Gérer les secrets

Mettre à jour les métadonnées et la configuration

Une fois le secret créé, il est possible de mettre à jour les métadonnées du secret ou sa configuration.

L'API attend les valeurs suivantes :

Il est aussi possible de changer la configuration par défaut du domaine OKMS pour les valeurs cas_required, deactivate_version_after et max_versions par l'API :

Créer une nouvelle version

Il est aussi possible de modifier le contenu du secret, ce qui implique la création d'une nouvelle version pour ce secret. Les nouvelles versions peuvent être créées par l'API :

Que la modification des data du secret soit faite par l'API générale de mise à jour du secret ou l'API spécifique, une nouvelle version du secret est créée.

Un secret peut contenir autant de versions que souhaitées dans la limite maximale du paramètre max_versions Si le nombre maximal de versions est atteint, la plus ancienne version est automatiquement supprimée.

Gérer les versions

Il est possible de gérer les différentes versions du secret par l'API :

L'API attendant l'unique valeur :

Aller plus loin

Échangez avec notre communauté d'utilisateurs.