Utilizzare il Secret Manager con l'API compatibile con HashiCorp Vault KV2

Accedere ai secret del Secret Manager e gestirli con l'API compatibile con HashiCorp Vault KV2

Obiettivo

L'obiettivo di questa guida è presentare l'utilizzo dell'API compatibile con HashiCorp Vault KV2 per il Secret Manager.

Prerequisiti

Disporre di un account cliente OVHcloud.
Avere ordinato un dominio OKMS o creato un primo secret.
Avere configurato un metodo di autenticazione per il piano dati OKMS.

Procedura

Descrizione

Il Secret Manager è un prodotto che ti permette di memorizzare in modo sicuro le credenziali, le chiavi API, le chiavi SSH o qualsiasi altro tipo di secret necessario al funzionamento delle tue applicazioni.

Un secret è un insieme di una o più coppie chiave-valore raggruppate all'interno di una versione. Ogni modifica di un secret comporta la creazione di una nuova versione di tale secret, consentendo di risalire nella cronologia delle modifiche del secret.

Le API compatibili con HashiCorp Vault KV2 sono uno dei due set di API offerti dal Secret Manager, insieme alle API REST. Sono progettate per essere simili alle API HashiCorp Vault, al fine di garantire la compatibilità con le applicazioni già compatibili con HashiCorp Vault.

Comunicare con il dominio OKMS

La comunicazione con il dominio OKMS per le operazioni di cifratura e firma è disponibile tramite l'API.

Poiché il dominio OKMS è regionalizzato, l'accesso all'API avviene direttamente nella regione dello stesso: https://my-region.okms.ovh.net.

Ad esempio, per un dominio OKMS creato nella regione eu-west-rbx: https://eu-west-rbx.okms.ovh.net.

È possibile comunicare con il dominio OKMS utilizzando:

L'interfaccia utente Swagger
La CLI OKMS: https://github.com/ovh/okms-cli
L'SDK Golang: https://pkg.go.dev/github.com/ovh/okms-sdk-go

Autenticati tramite un token di accesso personale, un account di servizio o un certificato di accesso. Per l'utilizzo dell'API compatibile con HashiCorp Vault KV2, si consiglia un token di accesso personale (PAT) o un account di servizio.

Per testare le chiamate API in modo interattivo, utilizza l'interfaccia Swagger OKMS all'indirizzo https://<region>.okms.ovh.net/swagger/.

Creare un secret

Per creare un secret, è possibile utilizzare la seguente API:

Metodo	Percorso	Descrizione
POST	/api/{okmsId}/v1/secret/data/{path}	Creare un secret

Il percorso del secret deve essere indicato nel percorso dell'API.

L'API prevede i seguenti valori:

Campo	Valore	Descrizione
data	Json	Contenuto del secret. È possibile avere JSON nidificati
cas	Integer	(opzionale) Versione attuale del secret

Ad esempio:

{
  "data": {
      "login": "admin",
      "password": "my_secret_password",
      "address": {
        "ip": "1.1.1.1"
      },
      "ports": [
        "30",
        "31"
      ]
  },
  "options": {
      "cas": 0
  }
}

È inoltre possibile aggiungere metadati al secret tramite l'API:

Metodo	Percorso	Descrizione
POST	/api/{okmsId}/v1/secret/metadata/{path}	Aggiornare i metadati di un secret

L'API prevede i seguenti valori:

Campo	Valore	Descrizione
cas_required	booleano	Se attivato, è necessario indicare sistematicamente il numero della versione attuale durante le modifiche
custom_metadata	Json	Dati aggiuntivi associati al secret. Questi dati non sono protetti dal secret
deactivate_version_after	Duration String	Durata dopo la quale le versioni vengono disattivate
max_versions	Integer	Numero massimo di versioni per il secret

Ad esempio:

{
  "cas_required": true,
  "custom_metadata": {
    "project": "A",
    "team": "X"
  },
  "deactivate_version_after": "10h30m10s",
  "max_versions": 5
}

Gestire i secret

Aggiornare i metadati e la configurazione

Una volta creato il secret, è possibile aggiornare i metadati del secret e la sua configurazione.

Metodo	Percorso	Descrizione
PATCH	/api/{okmsId}/v1/secret/metadata/{path}	Aggiornare i metadati di un secret

L'API prevede i seguenti valori:

Campo	Valore	Descrizione
cas_required	booleano	Se attivato, è necessario indicare sistematicamente il numero della versione attuale durante le modifiche
custom_metadata	Json	Dati aggiuntivi associati al secret. Questi dati non sono protetti dal secret
deactivate_version_after	Duration String	Durata dopo la quale le versioni vengono disattivate
max_versions	Integer	Numero massimo di versioni per il secret

È inoltre possibile modificare la configurazione predefinita del dominio OKMS per i valori cas_required, deactivate_version_after e max_versions tramite l'API:

Metodo	Percorso	Descrizione
POST	/api/{okmsId}/v1/secret/config	Configurare la configurazione predefinita del dominio OKMS

Creare una nuova versione

È inoltre possibile modificare il contenuto del secret, il che comporta la creazione di una nuova versione per tale secret. Le nuove versioni possono essere create tramite l'API:

Metodo	Percorso	Descrizione
PATCH	/api/{okmsId}/v1/secret/data/{path}	Aggiornare un secret

Un secret può contenere tutte le versioni desiderate, nel limite massimo del parametro max_versions. Se viene raggiunto il numero massimo di versioni, la versione più vecchia viene eliminata automaticamente.

Gestire le versioni

È possibile gestire le diverse versioni del secret tramite più API:

Metodo	Percorso	Descrizione
POST	/api/{okmsId}/v1/secret/delete/{path}	Disattiva le versioni specificate del secret
DELETE	/api/{okmsId}/v1/secret/data/{path}	Disattiva l'ultima versione del secret

Le versioni disattivate di un secret sono ancora presenti nel Secret Manager, ma il loro contenuto non è più accessibile.

È possibile riattivare una versione tramite l'API:

Metodo	Percorso	Descrizione
POST	/api/{okmsId}/v1/secret/undelete/{path}	Riattiva le versioni specificate del secret

Infine, è possibile eliminare definitivamente una versione tramite l'API:

Metodo	Percorso	Descrizione
PUT	/api/{okmsId}/v1/secret/destroy/{path}	Elimina le versioni specificate del secret

È inoltre possibile eliminare definitivamente l'intero secret con tutte le sue versioni:

Metodo	Percorso	Descrizione
DELETE	/api/{okmsId}/v1/secret/metadata/{path}	Elimina il secret e le sue versioni

Warning

Una versione eliminata non è più presente nel Secret Manager e non può più essere riattivata.

Per saperne di più

Metodi di autenticazione OKMS

Contatta la nostra Community di utenti.

Questa pagina ti è stata utile?