Gestione dei segreti chiave - valore con l'API Vault

Con IBM Cloud® Secrets Manager, è possibile gestire più versioni per chiave e accedere alla cronologia e ai metadati del segreto chiave-valore utilizzando l'API HashiCorp Vault HTTP.

Secrets Manager supporta l'API di HashiCorp Vault KV Secrets Engine Version 2. Per ulteriori informazioni sull'API KV v2, consultare il sito Documentazione del Vault KV v2.

Panoramica

Se già utilizzi l'API del vault, puoi utilizzare il formato e le linee guida API per interagire con Secrets Manager. Secrets Manager supporta solo KV versione 2. Gli endpoint per il motore dei segreti chiave - valore definiti nella documentazione del vault sono compatibili con la CLI e altri strumenti applicabili.

Per ulteriori informazioni sull'autenticazione, vedere API Vault.

Per utilizzare l'API REST standard per Secrets Manager, consulta il Riferimento APISecrets Manager.

Differenza tra KV e Secrets Manager

Il motore dei segreti chiave - valore utilizzato da Secrets Manager differisce leggermente dal motore dei segreti KV di Vault.

Non è possibile personalizzare completamente il percorso. Il percorso di un segreto chiave - valore deve essere:
- {secret_group_id}/{secret_name} per i segreti che si trovano in un gruppo di segreti personalizzato.
- /{secret_name} per i segreti che sono nel gruppo predefinito.
I metodi utilizzati su Vault per configurare il motore di valori chiave e leggere la configurazione non sono supportati.

Crea o aggiorna un segreto chiave - valore

Crea una versione di un segreto chiave - valore.

Richiesta di esempio

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"
            }
    }'

Creare o aggiornare i parametri di richiesta di un segreto a valore chiave
Parametro richiesta	Descrizione
`instance_id`	L'ID dell'istanza di Secrets Manager.
`region`	La regione in cui è stata creata l'istanza Secrets Manager.
`secret_name`	Il nome della chiave-valore segreta.
`Vault-Token`	Il token di autenticazione richiamato dal vault.
`data`	Obbligatorio. I dati segreti in formato JSON da assegnare al segreto. La dimensione massima del file è di 512 KB.

Risposta di esempio

Una richiesta di aggiornare un segreto chiave - valore nel gruppo di segreti default restituisce la seguente risposta:

{
    "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
}

Leggere una versione di un segreto chiave - valore

Ottenere una versione di un segreto a valore-chiave. Una richiesta riuscita restituisce i dati segreti associati alla versione specificata del tuo segreto, insieme ad altri metadati.

Richiesta di esempio

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}'

Leggere una versione dei parametri di una richiesta segreta a valore-chiave
Parametro richiesta	Descrizione
`instance_id`	L'ID dell'istanza Secrets Manager.
`region`	La regione in cui è stata creata l'istanza Secrets Manager.
`secret_name`	Il nome della chiave-valore segreta.
`version`	Le versioni che si desidera leggere.
`Vault-Token`	Il token di autenticazione richiamato dal vault.

Risposta di esempio

Una richiesta di ottenere una versione di un segreto del valore chiave nel gruppo di segreto default restituisce la seguente risposta:

{
    "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
}

Elimina l'ultima versione di un segreto chiave - valore

Eliminare l'ultima versione di un segreto chiave - valore. Dopo aver eliminato la versione, non puoi richiamarla utilizzando le chiamate API list o get. Tuttavia, si tratta di una eliminazione soft e i dati sottostanti non vengono rimossi. Puoi annullare l'eliminazione richiamando l'endpoint API undelete.

Richiesta di esempio

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}'

Eliminare l'ultima versione di una richiesta di parametri segreti chiave-valore
Parametro richiesta	Descrizione
`instance_id`	L'ID dell'istanza Secrets Manager.
`region`	La regione in cui è stata creata l'istanza Secrets Manager.
`secret_name`	Il nome della chiave-valore segreta.
`Vault-Token`	Il token di autenticazione richiamato dal vault.

Risposta di esempio

Una richiesta di eliminazione della versione più recente di un segreto chiave - valore nel gruppo di segreti default restituisce una risposta vuota con un codice di stato 204 per confermare che la versione più recente è stata eliminata.

Elimina le versioni specificate di un segreto chiave - valore

Eliminare la versione specificata di un segreto chiave - valore. Dopo aver eliminato le versioni, non puoi richiamarle utilizzando le chiamate API list o get. Tuttavia, si tratta di una eliminazione soft e i dati sottostanti non vengono rimossi. Puoi annullare l'eliminazione richiamando l'endpoint API undelete.

Richiesta di esempio

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]
            }'

Eliminare le versioni specificate di una richiesta di parametri segreti chiave-valore
Parametro richiesta	Descrizione
`instance_id`	L'ID dell'istanza Secrets Manager.
`region`	La regione in cui è stata creata l'istanza Secrets Manager.
`secret_name`	Il nome della chiave-valore segreta.
`Vault-Token`	Il token di autenticazione richiamato dal vault.
`versions`	Le versioni specificate che devono essere eliminate.

Risposta di esempio

Una richiesta di eliminazione delle versioni specificate di un segreto chiave - valore nel gruppo di segreto default restituisce la seguente risposta:

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

Annulla l'eliminazione di un segreto chiave - valore

Ripristinare una versione precedentemente eliminata di un segreto chiave - valore.

Richiesta di esempio

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
                ]
            }

Cancellare una versione dei parametri di una richiesta segreta a valore-chiave
Parametro richiesta	Descrizione
`instance_id`	L'ID dell'istanza Secrets Manager.
`region`	La regione in cui è stata creata l'istanza Secrets Manager.
`secret_name`	Il nome della chiave-valore segreta.
`Vault-Token`	Il token di autenticazione richiamato dal vault.
`versions`	Le versioni del segreto chiave - valore che vuoi eliminare.

Risposta di esempio

Una richiesta di ripristino di una versione di un segreto chiave - valore nel gruppo di segreti default restituisce una risposta vuota con un codice di stato 204 per confermare che le versioni specificate sono state ripristinate.

Distruggere le versioni di un segreto

Eliminare definitivamente le versioni specificate di un segreto chiave - valore. Per eliminare temporaneamente le versioni di un segreto, utilizza invece l'endpoint dell'API delete specified versions.

Richiesta di esempio

curl -X POST 'https://{instance_id}.{region}.secrets-manager.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]
            }'

Distruggere le versioni dei parametri di una richiesta segreta a valore-chiave
Parametro richiesta	Descrizione
`instance_id`	L'ID dell'istanza Secrets Manager.
`region`	La regione in cui è stata creata l'istanza Secrets Manager.
`secret_name`	Il nome della chiave-valore segreta.
`Vault-Token`	Il token di autenticazione richiamato dal vault.
`versions`	Le versioni del segreto chiave - valore che si desidera eliminare definitivamente.

Risposta di esempio

Una richiesta di distruzione permanente delle versioni di un segreto chiave - valore nel gruppo di segreti default restituisce una risposta vuota con un codice di stato 204 per confermare che le versioni del segreto sono state distrutte.

Creare o aggiornare i metadati del segreto chiave - valore

Creare o aggiornare i metadati di un segreto chiave - valore, come il numero massimo di versioni o altri valori personalizzati. Per aggiornare il contenuto effettivo del segreto, utilizzare il metodo Crea o aggiorna un segreto.

Richiesta di esempio

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"
                }
            }'

Aggiornare i metadati di una richiesta di parametri segreti a valore-chiave
Parametro richiesta	Descrizione
`instance_id`	L'ID dell'istanza Secrets Manager.
`region`	La regione in cui è stata creata l'istanza Secrets Manager.
`secret_name`	Il nome della chiave-valore segreta.
`Vault-Token`	Il token di autenticazione richiamato dal vault.

Risposta di esempio

Una richiesta di aggiornare i metadati di un segreto chiave - valore nel gruppo di segreti default restituisce una risposta vuota con un codice di stato 204 per confermare che i metadati del segreto sono stati aggiornati.

Leggi metadati del segreto chiave - valore

Ottenere i metadati di un segreto chiave - valore specificando l'ID della versione.

Richiesta di esempio

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

Leggere i metadati di una richiesta di parametri segreti chiave-valore
Parametro richiesta	Descrizione
`instance_id`	L'ID dell'istanza Secrets Manager.
`region`	La regione in cui è stata creata l'istanza Secrets Manager.
`secret_name`	Il nome della chiave-valore segreta.
`Vault-Token`	Il token di autenticazione richiamato dal vault.

Risposta di esempio

Una richiesta per ottenere i metadati di un segreto chiave - valore nel gruppo di segreti default restituisce la seguente risposta:

{
    "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
}

Elimina i metadati e tutte le versioni di un segreto chiave - valore

Eliminare i metadati e tutti i dati di versione di un segreto chiave - valore specificato in modo permanente. Tutta la cronologia delle versioni viene eliminata quando si utilizza questo endpoint API.

Richiesta di esempio

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}'

Eliminare i metadati di una richiesta di parametri segreti chiave-valore
Parametro richiesta	Descrizione
`instance_id`	L'ID dell'istanza Secrets Manager.
`region`	La regione in cui è stata creata l'istanza Secrets Manager.
`secret_name`	Il nome della chiave-valore segreta.
`Vault-Token`	Il token di autenticazione richiamato dal vault.

Risposta di esempio

Una richiesta per eliminare i metadati e tutte le versioni di un segreto chiave - valore nel gruppo di segreto default restituisce la seguente risposta:

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

Elencare i nomi chiave di un segreto chiave - valore

Ottenere un elenco di nomi chiave di un segreto chiave - valore. Non codificare le informazioni sensibili nei nomi chiave. I valori delle chiavi non sono accessibili utilizzando questo comando.

In {sm-short}, non è possibile utilizzare il verbo LIST HTTP per ottenere l'elenco dei nomi delle chiavi. Puoi farlo solo nell'API KV di Vault.

Richiesta di esempio

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}'

Elencare i nomi delle chiavi dei parametri di una richiesta segreta chiave-valore
Parametro richiesta	Descrizione
`instance_id`	L'ID dell'istanza Secrets Manager.
`region`	La regione in cui è stata creata l'istanza Secrets Manager.
`Vault-Token`	Il token di autenticazione richiamato dal vault.

Risposta di esempio

Una richiesta di elenco dei nomi chiave di un segreto chiave - valore nel gruppo di segreti default restituisce la seguente risposta:

{
    "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
}

Applica patch a un segreto chiave - valore

Aggiorna un segreto chiave - valore esistente fornendo solo i dettagli che vuoi modificare. Quando si applica una patch ad un segreto, viene creata una nuova versione. Tutti i dati che non vengono modificati rimangono esattamente come nella versione precedente del segreto.

Richiesta di esempio

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"
            }
    }'

Creare o aggiornare i parametri di richiesta di un segreto a valore chiave
Parametro richiesta	Descrizione
`instance_id`	L'ID dell'istanza di Secrets Manager.
`region`	La regione in cui è stata creata l'istanza Secrets Manager.
`secret_name`	Il nome della chiave-valore segreta.
`Vault-Token`	Il token di autenticazione richiamato dal vault.
`data`	Obbligatorio. I dati segreti in formato JSON con cui correggere il segreto. La dimensione massima del file è di 512 KB.

Risposta di esempio

Una richiesta di aggiornare un segreto chiave - valore nel gruppo di segreti default restituisce la seguente risposta:

{
    "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
}