Gestion des secrets de valeur de clé avec l'API Vault

Avec IBM Cloud® Secrets Manager, vous pouvez gérer plusieurs versions par clé et accéder à l'historique et aux métadonnées de votre secret de valeur-clé à l'aide de l'API HTTP de HashiCorp Vault.

Présentation

Si vous utilisez déjà l'API Vault, vous pouvez utiliser son format d'API et ses instructions pour interagir avec Secrets Manager. Secrets Manager prend en charge KV version 2 uniquement. Les noeuds finaux du moteur de secrets clé-valeur qui sont définis dans la documentation Vault sont compatibles avec l'interface de ligne de commande et les autres outils applicables.

Pour plus d'informations sur l'authentification, voir API Voûte.

Pour utiliser l'API REST standard pour Secrets Manager, consultez la référence de l'API Secrets Manager.

Différence entre KV et Secrets Manager

Le moteur de clés de valeurs confidentielles utilisé par Secrets Manager diffère légèrement du moteur de secrets KV de Vault.

Vous ne pouvez pas personnaliser complètement le chemin d'accès. Le chemin d'accès à un secret de valeur de clé doit être :
- {secret_group_id}/{secret_name} pour les secrets qui se trouvent dans un groupe secret personnalisé.
- /{secret_name} pour les secrets qui se trouvent dans le groupe par défaut.
Les méthodes utilisées sur Vault pour configurer le moteur clé-valeur et lire la configuration ne sont pas prises en charge.

Créez ou mettez à jour un secret de valeur-clé

Créez une version d'un secret de valeur-clé.

Exemple de demande

curl -X POST 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/data/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -H 'Content-Type: application/json' \
    -d '{
            "data": {
                "key":"value"
            }
    }'

Créer ou mettre à jour une clé-valeur secrète paramètres de la demande
Paramètre de requête	Description
`instance_id`	L'ID de l'instance Secrets Manager.
`region`	La région dans laquelle l'instance Secrets Manager a été créée.
`secret_name`	Le nom du secret de la valeur-clé.
`Vault-Token`	Le jeton d'authentification extrait de Vault.
`data`	Obligatoire. Les données secrètes au format JSON à affecter au secret. La taille maximale du fichier est de 512 ko.

Exemple de réponse

Une demande de mise à jour d'un secret de valeur clé dans le groupe secret default renvoie la réponse suivante :

{
    "request_id": "9000000d4-f0000-4c000-000000-800000000f",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "created_time": "2022-02-09T23:41:58.888138788Z",
        "deletion_time": "",
        "destroyed": false,
        "version": 2
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

Lisez une version d'un secret de valeur-clé

Récupérez une version d'un secret de valeur-clé. Une demande ayant abouti renvoie les données associées à la version spécifiée de votre secret, ainsi qu'à d'autres métadonnées.

Exemple de demande

curl -X GET 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/data/{secret_name}?version={version}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}'

Lire une version des paramètres d'une demande de clé-valeur secrète
Paramètre de requête	Description
`instance_id`	L'ID de l'instance Secrets Manager .
`region`	La région dans laquelle l'instance Secrets Manager a été créée.
`secret_name`	Le nom du secret de la valeur-clé.
`version`	Les versions que vous voulez lire.
`Vault-Token`	Le jeton d'authentification extrait de Vault.

Exemple de réponse

Une demande pour obtenir une version d'un secret de valeur-clé dans le groupe secret default renvoie la réponse suivante :

{
    "request_id": "400000-60000-8e000-0ad0-00000bc0000caebe",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "data": {
            "key": "value"
        },
        "metadata": {
            "created_time": "2022-01-13T21:31:49.893962888Z",
            "deletion_time": "",
            "destroyed": false,
            "version": 1
        }
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

Supprimez la dernière version d'un secret de valeur-clé

Supprimez la dernière version d'un secret de valeur-clé. Une fois la version supprimée, vous ne pouvez plus l'extraire en utilisant les appels d'API list ou get. Toutefois, il s'agit d'une suppression logicielle et les données sous-jacentes ne sont pas supprimées. Vous pouvez annuler la suppression en appelant la restauration du nœud final de l'API.

Exemple de demande

curl -X DELETE 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/data/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}'

Supprimer la dernière version des paramètres d'une demande de clé-valeur secrète
Paramètre de requête	Description
`instance_id`	L'ID de l'instance Secrets Manager .
`region`	La région dans laquelle l'instance Secrets Manager a été créée.
`secret_name`	Le nom du secret de la valeur-clé.
`Vault-Token`	Le jeton d'authentification extrait de Vault.

Exemple de réponse

Une demande de suppression de la dernière version d'une valeur confidentielle de la valeur de clé dans le groupe secret default renvoie une réponse vide avec un code d'état 204 pour confirmer que la dernière version a été supprimée.

Supprimez les versions spécifiées d'un secret de valeur-clé

Supprimez les versions spécifiées d'un secret de valeur-clé. Après avoir supprimé les versions, vous ne pouvez plus les récupérer en utilisant des appels d'API listou get. Toutefois, il s'agit d'une suppression logicielle et les données sous-jacentes ne sont pas supprimées. Vous pouvez annuler la suppression en appelant la restauration du nœud final de l'API.

Exemple de demande

curl -X POST 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/delete/test-kv' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -d '{
            "versions": [1, 2]
            }'

Supprimer les versions spécifiées d'une clé-valeur secrète paramètres de la demande
Paramètre de requête	Description
`instance_id`	L'ID de l'instance Secrets Manager .
`region`	La région dans laquelle l'instance Secrets Manager a été créée.
`secret_name`	Le nom du secret de la valeur-clé.
`Vault-Token`	Le jeton d'authentification extrait de Vault.
`versions`	Les versions spécifiées qui doivent être supprimées.

Exemple de réponse

Une demande pour obtenir la suppression des versions spécifiées d'un secret de valeur clé dans le groupe secret default renvoie la réponse suivante :

{
    "request_id": "43abde16-6a33-971f-1690-469eccc00d91",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": null,
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

Restaurer un secret de valeur-clé

Restaurez une version précédemment supprimée d'un secret de valeur-clé.

Exemple de demande

curl -X POST 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/undelete/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -H 'Content-Type: application/json' \
    -d '{
            "versions": [
                1, 2
                ]
            }

Suppression d'une version des paramètres d'une demande de secret clé-valeur
Paramètre de requête	Description
`instance_id`	L'ID de l'instance Secrets Manager .
`region`	La région dans laquelle l'instance Secrets Manager a été créée.
`secret_name`	Le nom du secret de la valeur-clé.
`Vault-Token`	Le jeton d'authentification extrait de Vault.
`versions`	Les versions du secret de la valeur-clé que vous souhaitez supprimer.

Exemple de réponse

Une demande de restauration d'une version d'une valeur confidentielle d'une valeur clé dans le groupe secret default renvoie une réponse vide avec un code d'état 204 pour confirmer la restauration des versions spécifiées.

Détruisez les versions d'un secret

Détruisez définitivement les versions spécifiées d'un secret de valeur-clé. Pour plutôt faire une suppression logicielle des versions d'un secret, utilisez le nœud final de l'API Supprimer des versions spécifiées .

Exemple de demande

curl -X POST 'https://{instance_id}.{region}.secrets-manager.test.appdomain.cloud/v1/ibmcloud/kv/destroy/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -H 'Content-Type: application/json' \
    -d '{
            "versions": [1, 3]
            }'

Détruire les versions des paramètres d'une demande de clé-valeur secrète
Paramètre de requête	Description
`instance_id`	L'ID de l'instance Secrets Manager .
`region`	La région dans laquelle l'instance Secrets Manager a été créée.
`secret_name`	Le nom du secret de la valeur-clé.
`Vault-Token`	Le jeton d'authentification extrait de Vault.
`versions`	Les versions du secret de la valeur-clé que vous voulez détruire de façon permanente.

Exemple de réponse

Une demande de destruction permanente des versions d'un secret de valeur-clé dans le groupe secret default renvoie une réponse vide avec un code d'état 204 pour confirmer que les versions du secret ont bien été détruites.

Créez ou mettez à jour des métadonnées secrètes de valeur-clé

Créez ou mettez à jour les métadonnées d'un secret de valeur-clé, telles que le nombre maximal de versions ou d'autres valeurs personnalisées. Pour mettre à jour le contenu réel du secret, utilisez la méthode Créer ou mettre à jour un secret.

Exemple de demande

curl -X POST 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/metadata/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -H 'Content-Type: application/json' \
    -d '{
            "custom_metadata": {
                "meta1": "data1",
                "meta2": "data2"
                }
            }'

Mettre à jour les métadonnées d'une demande de paramètres de secret clé-valeur
Paramètre de requête	Description
`instance_id`	L'ID de l'instance Secrets Manager .
`region`	La région dans laquelle l'instance Secrets Manager a été créée.
`secret_name`	Le nom du secret de la valeur-clé.
`Vault-Token`	Le jeton d'authentification extrait de Vault.

Exemple de réponse

Une demande de mise à jour des métadonnées d'une valeur confidentielle de valeur de clé dans le groupe secret default renvoie une réponse vide avec un code d'état 204 pour confirmer que les métadonnées du secret ont bien été mises à jour.

Lisez les métadonnées du secret de la valeur-clé

Obtenez les métadonnées d'un secret de valuer-clé en spécifiant l'ID de la version.

Exemple de demande

curl -X GET 'https://{instance_id}.{region}.secrets-manager.test.appdomain.cloud/v1/ibmcloud/kv/metadata/{secret_name}' \
    -H 'Accept: application/json'
    -H 'X-Vault-Token: {Vault-Token}'

Lire les métadonnées des paramètres d'une demande de secret clé-valeur
Paramètre de requête	Description
`instance_id`	L'ID de l'instance Secrets Manager .
`region`	La région dans laquelle l'instance Secrets Manager a été créée.
`secret_name`	Le nom du secret de la valeur-clé.
`Vault-Token`	Le jeton d'authentification extrait de Vault.

Exemple de réponse

Une demande d'obtention des métadonnées d'un secret de valeur de clé dans le groupe secret default renvoie la réponse suivante :

{
    "request_id": "400000-60000-8e000-0ad0-00000bc0000caebe",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "cas_required": false,
        "created_time": "2022-01-13T21:31:49.893962888Z",
        "current_version": 3,
        "custom_metadata" : {
              "meta1": "data1",
              "meta2": "data2"    
        },
        "delete_version_after": "0s",
        "max_versions": 0,
        "oldest_version": 0,
        "updated_time": "2022-02-09T23:54:16.313286558Z",
        "versions": {
            "1": {
                "created_time": "2022-01-13T21:31:49.893962888Z",
                "deletion_time": "",
                "destroyed": false
            },
            "2": {
                "created_time": "2022-02-09T23:41:58.888138788Z",
                "deletion_time": "",
                "destroyed": false
            },
            "3": {
                "created_time": "2022-02-09T23:54:16.313286558Z",
                "deletion_time": "",
                "destroyed": false
            }
        }
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

Supprimez les métadonnées et toutes les versions d'un secret de valeur-clé

Supprimez définitivement les métadonnées et toutes les données de version d'un secret de valeur-clé spécifiée. Tous les historiques de version sont supprimés lorsque vous utilisez ce nœud final d'API.

Exemple de demande

curl -X DELETE 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/metadata/{secret_name}' \
    -H 'Accept: application/json'
    -H 'X-Vault-Token: {Vault-Token}'

Supprimer les métadonnées d'une demande de paramètres secrets clé-valeur
Paramètre de requête	Description
`instance_id`	L'ID de l'instance Secrets Manager .
`region`	La région dans laquelle l'instance Secrets Manager a été créée.
`secret_name`	Le nom du secret de la valeur-clé.
`Vault-Token`	Le jeton d'authentification extrait de Vault.

Exemple de réponse

Une demande de suppression des métadonnées et de toutes les versions d'une valeur confidentielle de valeur-clé dans le groupe secret default renvoie la réponse suivante :

{
    "request_id": "62b1e2c2-801a-6592-0526-edb38896a546",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": null,
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

Listez les noms de clé d'un secret de valeur-clé

Obtenez une liste de noms de clés d'un secret de valeur-clé. Ne codez pas des informations sensibles dans les noms de clé. Les valeurs des clés ne sont pas accessibles à l'aide de cette commande.

Dans {sm-short}, vous ne pouvez pas utiliser le verbe LIST HTTP pour obtenir la liste des noms de clés. Vous pouvez le faire uniquement dans l'API KV de Vault.

Exemple de demande

curl -X GET "https://{instance_id}.{region}.secrets-manager.test.appdomain.cloud/v1/ibmcloud/kv/metadata/?list=true" \
    -H 'Accept: application/json'\
    -H 'X-Vault-Token: {Vault-Token}'

Liste des noms de clés des paramètres d'une demande de secret clé-valeur
Paramètre de requête	Description
`instance_id`	L'ID de l'instance Secrets Manager .
`region`	La région dans laquelle l'instance Secrets Manager a été créée.
`Vault-Token`	Le jeton d'authentification extrait de Vault.

Exemple de réponse

Une demande de liste des noms de clé d'une valeur confidentielle de la valeur-clé dans le groupe secret defaultrenvoie la réponse suivante :

{
    "request_id": "a21993df-a4b7-21f1-95a9-c1af7be87d1b",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "keys": [
            "secret1",
            "secret2"
        ]
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

Correction d'un secret clé-valeur

Mettez à jour un secret clé-valeur existant en fournissant uniquement les détails que vous souhaitez modifier. Lorsque vous corrigez un secret, une nouvelle version est créée. Les données que vous ne modifiez pas restent exactement telles qu'elles sont dans la version précédente du secret.

Exemple de demande

curl -X PATCH 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/data/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -H 'Content-Type: application/merge-patch+json' \
    -d '{
            "data": {
                "key":"value"
            }
    }'

Créer ou mettre à jour une clé-valeur secrète paramètres de la demande
Paramètre de requête	Description
`instance_id`	L'ID de l'instance Secrets Manager.
`region`	La région dans laquelle l'instance Secrets Manager a été créée.
`secret_name`	Le nom du secret de la valeur-clé.
`Vault-Token`	Le jeton d'authentification extrait de Vault.
`data`	Obligatoire. Données de secret au format JSON avec lequel appliquer un correctif au secret. La taille maximale du fichier est de 512 ko.

Exemple de réponse

Une demande de mise à jour d'un secret de valeur clé dans le groupe secret default renvoie la réponse suivante :

{
    "request_id": "9000000d4-f0000-4c000-000000-800000000f",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "created_time": "2022-02-09T23:41:58.888138788Z",
        "deletion_time": "",
        "destroyed": false,
        "version": 2
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}