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.
• Avoir configuré une méthode d'authentification pour le plan de données OKMS.

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

Authentifiez-vous à l'aide d'un jeton d'accès personnel, d'un compte de service ou d'un certificat d'accès. Pour l'utilisation de l'API REST, un jeton d'accès personnel (PAT) ou un compte de service est recommandé.

Pour tester les appels API de manière interactive, utilisez l'interface Swagger OKMS à l'adresse https://<region>.okms.ovh.net/swagger/.

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

Méthodes d'authentification OKMS

Échangez avec notre communauté d'utilisateurs.